castrum 0.9.3 → 0.9.6

package/src/runtime/codec.ts

@@ -2,7 +2,10 @@
 //
 // 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`.
+//   - encode:     shared `TextEncoder` singleton (Bun's native implementation
+//     measures ~3x faster than the old `Bun.ArrayBufferSink` start/write/flush
+//     path on Bun 1.4 — 34-50ns vs 188-215ns for small strings) vs `TextEncoder`
+//     under Node.
 //   - 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).
@@ -36,7 +39,6 @@ function getNodeFatalDecoder(): TextDecoder {
 }
 
 // ── Bun codec ─────────────────────────────────────────────────────
-let bunSink: Bun.ArrayBufferSink | null = null
 let bunFfiCodec: typeof import('bun:ffi') | null | undefined
 
 function getBunFfiCodec(): typeof import('bun:ffi') | null {
@@ -60,15 +62,13 @@ function createBunCodec(): Utf8Codec {
     }
     return getNodeDecoder().decode(bytes)
   }
+  // Shared encoder singleton — Bun's native TextEncoder implementation
+  // allocates the exact-size buffer in-engine; measured ~3x faster than the
+  // previous ArrayBufferSink start/write/flush path on Bun 1.4 (see header).
+  const bunEncoder = new TextEncoder()
   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
+      return bunEncoder.encode(s)
     },
     encodeUtf8Into(s: string, dest: Uint8Array, offset = 0): number {
       return bunEncodeUtf8Into(s, dest, offset)
@@ -78,6 +78,7 @@ function createBunCodec(): Utf8Codec {
     // `castrum_utf8_valid` probe (callers check it first via the transport's
     // ffi surface). This fallback matches the historical behavior.
     decodeUtf8Fatal: decodeUtf8Bun,
+    decodeUtf8Range: decodeUtf8RangeBun,
   }
 }
 
@@ -120,6 +121,39 @@ function bunEncodeUtf8Into(s: string, dest: Uint8Array, offset = 0): number {
   return view.write(s, start, 'utf8')
 }
 
+// Shared cached full-backing view for the ranged DECODE fast path (same
+// WeakMap pattern as the encode views above — one Buffer per ArrayBuffer,
+// never per call).
+const bunDecodeViewCache = new WeakMap<ArrayBufferLike, Buffer>()
+
+function bunDecodeView(bytes: Uint8Array): Buffer {
+  const backing = bytes.buffer
+  let view = bunDecodeViewCache.get(backing)
+  if (view === undefined || view.byteLength !== backing.byteLength) {
+    view = Buffer.from(backing)
+    bunDecodeViewCache.set(backing, view)
+  }
+  return view
+}
+
+/**
+ * Ranged decode: ASCII-only ranges take the latin1 `toString` path (JSC
+ * builds the string without the UTF-8 decoder machinery — measured ~2x the
+ * CString path on Bun 1.4); any high byte falls back to a real UTF-8 decode
+ * of exactly that range. Replacement-mode parity with `decodeUtf8` holds for
+ * both branches (latin1 is byte-identical to UTF-8 when no byte exceeds 0x7F).
+ */
+function decodeUtf8RangeBun(bytes: Uint8Array, start: number, end: number): string {
+  const view = bunDecodeView(bytes)
+  const base = bytes.byteOffset
+  for (let i = start; i < end; i++) {
+    if ((bytes[i] ?? 0) >= 0x80) {
+      return view.toString('utf8', base + start, base + end)
+    }
+  }
+  return view.toString('latin1', base + start, base + end)
+}
+
 // ── Node codec ────────────────────────────────────────────────────
 function createNodeCodec(): Utf8Codec {
   return {
@@ -135,6 +169,16 @@ function createNodeCodec(): Utf8Codec {
     decodeUtf8Fatal(bytes: Uint8Array): string {
       return getNodeFatalDecoder().decode(bytes)
     },
+    decodeUtf8Range(bytes: Uint8Array, start: number, end: number): string {
+      // Node: ranged Buffer toString with the same ASCII fast path.
+      const view = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+      for (let i = start; i < end; i++) {
+        if ((bytes[i] ?? 0) >= 0x80) {
+          return view.toString('utf8', start, end)
+        }
+      }
+      return view.toString('latin1', start, end)
+    },
   }
 }
 

package/src/runtime/types.ts

@@ -31,6 +31,13 @@ export interface Utf8Codec {
   decodeUtf8(bytes: Uint8Array): string
   /** Decode UTF-8 bytes to a string, throwing on invalid UTF-8. */
   decodeUtf8Fatal(bytes: Uint8Array): string
+  /**
+   * Decode the byte RANGE `[start, end)` of `bytes` to a string (replacement
+   * mode on invalid). Zero-copy ranged decode for packed-wire unpackers —
+   * avoids the per-field `subarray` view allocation. ASCII-only ranges take
+   * a latin1 fast path (~2x on Bun); multi-byte ranges fall back to UTF-8.
+   */
+  decodeUtf8Range(bytes: Uint8Array, start: number, end: number): string
 }
 
 /** UUIDv7 generation (Bun built-in vs crypto.randomUUID on Node). */

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

@@ -82,8 +82,7 @@ export function buildBatch(ctx: RustClientContext): RustBatch {
       via(ctx, 'signCookieBatchPacked', unpackByteResults, [secret])(items),
     verifyCookie: (items, secret) =>
       via(ctx, 'verifyCookieBatchPacked', unpackBitset, [secret])(items),
-    csrfVerify: (items, secret) =>
-      via(ctx, 'csrfVerifyBatchPacked', 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),
@@ -96,13 +95,18 @@ export function buildBatch(ctx: RustClientContext): RustBatch {
       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),
+    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),
+      via(ctx, 'base64EncodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(
+        items,
+      ),
     base64Decode: (items, urlSafe, padding) =>
-      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(items),
+      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(
+        items,
+      ),
     schemaValidate(validator, items) {
       return schemaValidateBatch(validator, items)
     },
@@ -131,7 +135,8 @@ export function buildBatch(ctx: RustClientContext): RustBatch {
     hmacSha256Verify: (items, sigs, key) =>
       via2(ctx, 'hmacSha256VerifyBatchPacked', unpackBitset, [key])(items, sigs),
     // ── Two-list ──
-    passwordVerify: (items, phcs) => via2(ctx, 'passwordVerifyBatchPacked', unpackBitset)(items, phcs),
+    passwordVerify: (items, phcs) =>
+      via2(ctx, 'passwordVerifyBatchPacked', unpackBitset)(items, phcs),
     urlResolve: (bases, references) =>
       via2(ctx, 'urlResolveBatchPacked', unpackByteResults)(bases, references),
     templateRender: (source, contexts) =>
@@ -143,9 +148,11 @@ export function buildBatch(ctx: RustClientContext): RustBatch {
         nowSeconds ?? Math.floor(Date.now() / 1000),
       ])(items),
     sseEncode: (items, event, id, retry) =>
-      via(ctx, 'sseEncodeBatchPacked', unpackByteResults, [event ?? null, id ?? null, retry ?? null])(
-        items,
-      ),
+      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),

package/src/rust-ffi/index.ts

@@ -37,6 +37,7 @@ export type {
   HmacSignerInstance,
   MediaTypeParserInstance,
   MediaTypeResult,
+  MetricsRegistryInstance,
   MultipartPart,
   PasswordHashOptions,
   SchemaError,
@@ -46,20 +47,20 @@ export type {
   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 type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'
 export {
-  PROVEN_SELECTION,
   isProven,
+  PROVEN_SELECTION,
   provenEntry,
   provenImpl,
   provenStatus,
   provenSummary,
   provenSurface,
 } from '../shared/proven'
-export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'
+export type { RustBatch } from './batch'
+export type { RustClient } from './client'
+export { createRust, rust } from './client'
 export type { RustOptions } from './options'
 export type { RustPacked } from './packed'
+export { proven } from './proven'
 export type { RustText } from './text'

package/src/rust-ffi/options.ts

@@ -50,9 +50,7 @@ export function resolveRayonThreads(explicit?: number): number {
     return Math.max(1, Math.min(cores, Math.floor(explicit)))
   }
 
-  const envThreads = Number(
-    resolveEnvVar('CASTRUM_RAYON_THREADS'),
-  )
+  const envThreads = Number(resolveEnvVar('CASTRUM_RAYON_THREADS'))
 
   if (Number.isFinite(envThreads) && envThreads > 0) {
     return Math.max(1, Math.min(cores, Math.floor(envThreads)))

package/src/rust-ffi/proven.ts

@@ -8,7 +8,7 @@
 // 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'
+import { type RustClient, rust } from './client'
 
 /** The full `rust.*` surface — identical to `rust`; the proven wiring is baked (see {@link ../shared/proven}). */
 export type ProvenClient = RustClient
@@ -16,13 +16,13 @@ export type ProvenClient = RustClient
 /** The full `rust.*` surface, exposed for audit. Same object as `rust`. */
 export const proven: ProvenClient = rust
 
+export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'
 export {
-  PROVEN_SELECTION,
   isProven,
+  PROVEN_SELECTION,
   provenEntry,
   provenImpl,
   provenStatus,
   provenSummary,
   provenSurface,
 } from '../shared/proven'
-export type { ProvenEntry, ProvenImpl, ProvenStatus } from '../shared/proven'

package/src/rust-ffi/scalar/crypto.ts

@@ -10,8 +10,8 @@
 
 import type { PasswordHashOptions } from '../../native'
 import { encoder } from '../../shared/bytes'
-import { writeInto } from '../into'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
+import { writeInto } from '../into'
 
 /** Auth / crypto scalar methods (`Pick<RustScalar, ...>`). */
 export function buildCrypto(ctx: RustClientContext) {

package/src/rust-ffi/scalar/factories.ts

@@ -16,6 +16,7 @@ import type {
   JwtSignerInstance,
   MediaTypeMatcherInstance,
   MediaTypeParserInstance,
+  MetricsRegistryInstance,
   PasswordHashOptions,
   RateLimiterInstance,
   SchemaValidatorInstance,
@@ -329,6 +330,71 @@ function ffiFormParser(ffi: BunFFI): FormParserInstance {
   }
 }
 
+/**
+ * Caller-owned-handle `MetricsRegistry`: on Bun the whole surface runs through
+ * the C-ABI (`castrum_metrics_*`) with a native handle — no napi instance is
+ * involved at all (the route-stack ownership model). Label values cross as a
+ * JOINED `\u001f` string via the cstring-ARG `_str` symbols: the engine
+ * transcodes them in-engine, so the per-event JS cost is just
+ * `values.join('\u001f')` — ZERO TextEncoder work (Bun 1.4 zero-copy text).
+ */
+function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
+  const handle = ffi.metricsCreate()
+  return {
+    counter(name, labelKeys) {
+      return ffi.metricsCounter(handle, name, (labelKeys ?? []).join('\u001f'))
+    },
+    gauge(name, labelKeys) {
+      return ffi.metricsGauge(handle, name, (labelKeys ?? []).join('\u001f'))
+    },
+    histogram(name, labelKeys, buckets) {
+      return ffi.metricsHistogram(
+        handle,
+        name,
+        (labelKeys ?? []).join('\u001f'),
+        (buckets ?? []).join(','),
+      )
+    },
+    record(series, values, amount) {
+      const joined = (values ?? []).join('\u001f')
+      if (!ffi.metricsRecordStr(handle, series, joined, amount ?? 1)) {
+        throw new Error('metrics record: unknown series / arity mismatch / invalid amount')
+      }
+    },
+    gaugeSet(series, values, value) {
+      const joined = (values ?? []).join('\u001f')
+      if (!ffi.metricsGaugeSetStr(handle, series, joined, value)) {
+        throw new Error('metrics gauge set: unknown series / arity mismatch')
+      }
+    },
+    render() {
+      // Probe large enough for typical registries (one native pass), then
+      // grow exactly once if ever exceeded (needed-size convention).
+      let out = new Uint8Array(8192)
+      let w = ffi.metricsRender(handle, out)
+      if (w > out.length) {
+        out = new Uint8Array(w)
+        w = ffi.metricsRender(handle, out)
+      }
+      return decodeUtf8(out.subarray(0, w))
+    },
+    destroy() {
+      ffi.metricsDestroy(handle)
+    },
+    snapshot() {
+      // Packed v1 dump — decoded by consumers (the @ignex/native metrics
+      // wrapper); probe large, grow exactly once.
+      let out = new Uint8Array(4096)
+      let w = ffi.metricsSnapshot(handle, out)
+      if (w > out.length) {
+        out = new Uint8Array(w)
+        w = ffi.metricsSnapshot(handle, out)
+      }
+      return out.subarray(0, w)
+    },
+  }
+}
+
 /** Compiled-once factory + runtime-control methods (`Pick<RustScalar, ...>`). */
 export function buildFactories(ctx: RustClientContext) {
   const { transport } = ctx.runtime
@@ -450,6 +516,13 @@ export function buildFactories(ctx: RustClientContext) {
       }
       return new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
     },
+    createMetricsRegistry(): MetricsRegistryInstance {
+      // Fully C-ABI-backed on Bun (native handle owned by the wrapper — no
+      // napi instance involved); napi class on Node / fallback.
+      const ffi = transport.ffi
+      if (ffi) return ffiMetricsRegistry(ffi)
+      return new addon.MetricsRegistry()
+    },
     initThreadPool(threads?: number): void {
       // Explicit user call also establishes the pool state locally.
       ctx.markPoolInitialized()

package/src/rust-ffi/scalar/hashing.ts

@@ -9,8 +9,8 @@
 // (bun:ffi first, napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
 import { toBytes } from '../../shared/bytes'
-import { writeInto } from '../into'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
+import { writeInto } from '../into'
 import { asBigInt, asNumber } from '../options'
 
 /** Hashing scalar methods (`Pick<RustScalar, ...>`). */

package/src/rust-ffi/scalar/http.ts

@@ -11,11 +11,18 @@
 
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
-import { decoder } from '../../shared/bytes'
-import { decodeUtf8Fatal } from '../../shared/codec'
+import { decoder, hasNul } from '../../shared/bytes'
+import { decodeUtf8Fatal, decodeUtf8Range } from '../../shared/codec'
 import { packPairs } from '../../shared/packed'
-import { writeInto } from '../into'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
+import { writeInto } from '../into'
+
+/**
+ * RFC 6455 `Sec-WebSocket-Accept` is always 28 chars. Reused across calls
+ * because the value is decoded to a string synchronously before returning —
+ * the same discipline as the other pooled scratches in this layer.
+ */
+const WS_ACCEPT_SCRATCH = new Uint8Array(64)
 
 // Mirror napi `url_decode`'s UTF-8 validation (rust/http/url_codec.rs): only
 // validate when a high byte is present (the ASCII fast path skips it — same as
@@ -60,23 +67,25 @@ function u32LE(b: Uint8Array, off: number): number {
  * napi `HashMap` (which keeps every param including charset/boundary).
  */
 function unpackMediaType(packed: Uint8Array): MediaTypeResult {
+  // Ranged decode straight off the (pooled) packed buffer — no per-field
+  // subarray views. ASCII fields take the latin1 fast path.
   let off = 0
   const mtLen = u32LE(packed, off)
   off += 4
-  const mediaType = decoder.decode(packed.subarray(off, off + mtLen))
+  const mediaType = decodeUtf8Range(packed, off, off + mtLen)
   off += mtLen
   let charset: string | null = null
   const csLen = u32LE(packed, off)
   off += 4
   if (csLen !== 0xffffffff) {
-    charset = decoder.decode(packed.subarray(off, off + csLen))
+    charset = decodeUtf8Range(packed, off, off + csLen)
     off += csLen
   }
   let boundary: string | null = null
   const bLen = u32LE(packed, off)
   off += 4
   if (bLen !== 0xffffffff) {
-    boundary = decoder.decode(packed.subarray(off, off + bLen))
+    boundary = decodeUtf8Range(packed, off, off + bLen)
     off += bLen
   }
   const count = u32LE(packed, off)
@@ -85,11 +94,11 @@ function unpackMediaType(packed: Uint8Array): MediaTypeResult {
   for (let i = 0; i < count; i++) {
     const kLen = u32LE(packed, off)
     off += 4
-    const key = decoder.decode(packed.subarray(off, off + kLen))
+    const key = decodeUtf8Range(packed, off, off + kLen)
     off += kLen
     const vLen = u32LE(packed, off)
     off += 4
-    const val = decoder.decode(packed.subarray(off, off + vLen))
+    const val = decodeUtf8Range(packed, off, off + vLen)
     off += vLen
     params[key] = val
   }
@@ -97,18 +106,22 @@ function unpackMediaType(packed: Uint8Array): MediaTypeResult {
 }
 
 /** Unpack the `castrum_parse_accept_encoding` verdict (f32 q-values) into the
- * napi-shaped array. Layout: `[u32 count]{[u32 encLen][enc][f32 q][u32 order]}`. */
+ * napi-shaped array. Layout: `[u32 count]{[u32 encLen][enc][f32 q][u32 order]}`.
+ * Ranged decode off the pooled buffer + shared f32 bit-reinterpret views —
+ * no per-field subarrays, no per-call DataView. */
+const f32Bits = new Float32Array(1)
+const f32BitsU32 = new Uint32Array(f32Bits.buffer)
 function unpackAcceptEncoding(packed: Uint8Array): EncodingPrefResult[] {
   const count = u32LE(packed, 0)
   let off = 4
   const out: EncodingPrefResult[] = []
-  const view = new DataView(packed.buffer, packed.byteOffset, packed.byteLength)
   for (let i = 0; i < count; i++) {
     const encLen = u32LE(packed, off)
     off += 4
-    const encoding = decoder.decode(packed.subarray(off, off + encLen))
+    const encoding = decodeUtf8Range(packed, off, off + encLen)
     off += encLen
-    const q = view.getFloat32(off, true)
+    f32BitsU32[0] = u32LE(packed, off)
+    const q: number = f32Bits[0] ?? 0
     off += 4
     const order = u32LE(packed, off)
     off += 4
@@ -138,11 +151,22 @@ export function buildHttp(ctx: RustClientContext) {
 
   return {
     mimeFromExtension(ext: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi keeps the memoized-bytes
-      // path (cachedMime).
+      // FFI-first. This op has no `*_bytes` sibling, so the bytes must be decoded
+      // for the `cstring` ARG — the decode is the price of the cstring form, not
+      // a speed trick (route new byte-shaped ops to a byte sibling instead; see
+      // docs/FFI_BUN_GUIDE.md §6.1). napi keeps the memoized-bytes path
+      // (cachedMime).
+      //
+      // A NUL would truncate the DECODED string native-side, so `.js\0evil`
+      // would resolve as `.js` — a Content-Type from a prefix. An extension
+      // containing a NUL is not an extension, so it takes the unknown sentinel
+      // (the guard is `indexOf` on an already-decoded string: ~4 ns).
       const f = ffi()
-      if (f) return f.mimeFromExtension(decoder.decode(ext)) ?? 'application/octet-stream'
+      if (f) {
+        const name = decoder.decode(ext)
+        if (hasNul(name)) return 'application/octet-stream'
+        return f.mimeFromExtension(name) ?? 'application/octet-stream'
+      }
       return ctx.cachedMime(ext)
     },
     urlEncode(input: Uint8Array): Uint8Array | string {
@@ -182,34 +206,54 @@ export function buildHttp(ctx: RustClientContext) {
       return n('urlDecodeInto')(input, output) as number
     },
     validateEmail(input: Uint8Array): boolean {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call — still faster than the old
-      // `(ptr,len)` view path (see bench:margin cstring scenario). napi
-      // fallback keeps the byte path.
+      // FFI-first. The bytes cross as a `buffer`/`buffer_length` pair (an atomic
+      // ptr+len snapshot, zero transcode) rather than being decoded to a JS
+      // string for the `cstring` ARG. Measured on Bun 1.4.2 over 400k calls:
+      // 101 ns vs 234 ns (email), 65 vs 164 (uuid), 31 vs 138 (ipv4) — and the
+      // byte form cannot truncate at an embedded NUL the way a cstring ARG
+      // does (a NUL byte used to make "a@b.com\0<script>" validate as TRUE).
       const f = ffi()
-      if (f) return f.validateEmail(decoder.decode(input))
+      if (f) return f.validateEmailBytes(input)
       return n('validateEmail')(input) as boolean
     },
     validateUuid(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateUuid(decoder.decode(input))
+      if (f) return f.validateUuidBytes(input)
       return n('validateUuid')(input) as boolean
     },
     validateIpv4(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv4(decoder.decode(input))
+      if (f) return f.validateIpv4Bytes(input)
       return n('validateIpv4')(input) as boolean
     },
     validateIpv6(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv6(decoder.decode(input))
+      if (f) return f.validateIpv6Bytes(input)
       return n('validateIpv6')(input) as boolean
     },
     wsAcceptKey(key: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi fallback keeps the bytes.
+      // FFI-first: the `cstring` ARG + cstring return is the fast path (no JS
+      // encode, engine-cloned result) — end-to-end it measures ~367 ns, while
+      // routing every call through the byte sibling costs ~381 ns (the extra
+      // `subarray` + decode outweighs the transcode saved; measured over 300k
+      // calls on Bun 1.4.2 through THIS function, not the raw binding).
+      //
+      // Correctness rider: a NUL would truncate the `cstring` ARG, so the accept
+      // value would be computed for a PREFIX of the key — verified:
+      // `'dGhlIHNhbXBsZSBub25jZQ==\0junk'` returned exactly the value for the
+      // key WITHOUT the suffix. That case takes the byte sibling (exact length).
       const f = ffi()
-      if (f) return f.wsAcceptKey(decoder.decode(key))
+      if (f) {
+        const text = decoder.decode(key)
+        if (!hasNul(text)) return f.wsAcceptKey(text)
+        const w = f.wsAcceptKeyInto(key, WS_ACCEPT_SCRATCH)
+        if (w > 0 && w <= WS_ACCEPT_SCRATCH.length) {
+          return decoder.decode(WS_ACCEPT_SCRATCH.subarray(0, w))
+        }
+        // Unreachable for a live view (the native side writes 28 for any key);
+        // the napi path is byte-exact, so it can never resurrect truncation.
+        return n('wsAcceptKey')(key) as Uint8Array | string
+      }
       return n('wsAcceptKey')(key) as Uint8Array | string
     },
     wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number {

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

@@ -15,6 +15,7 @@ import { buildHashing } from './hashing'
 import { buildHttp } from './http'
 import { buildJson } from './json'
 import { buildPayload } from './payload'
+import { buildValidation } from './validation'
 
 export type { RustScalar } from './interface'
 
@@ -26,6 +27,7 @@ export function buildScalar(ctx: RustClientContext): import('./interface').RustS
     ...buildHttp(ctx),
     ...buildCrypto(ctx),
     ...buildPayload(ctx),
+    ...buildValidation(ctx),
     ...buildFactories(ctx),
   }
 }

package/src/rust-ffi/scalar/interface.ts

@@ -19,6 +19,7 @@ import type {
   MediaTypeMatcherInstance,
   MediaTypeParserInstance,
   MediaTypeResult,
+  MetricsRegistryInstance,
   MultipartPart,
   PasswordHashOptions,
   RateLimiterInstance,
@@ -67,6 +68,18 @@ export interface RustScalar {
   validateUuid(input: Uint8Array): boolean
   validateIpv4(input: Uint8Array): boolean
   validateIpv6(input: Uint8Array): boolean
+  /**
+   * Batch fixed-width hex validation: NEWLINE-separated lines in → one
+   * verdict byte (1/0) per line. One native call replaces per-item
+   * `/^[0-9a-f]{width}$/` regex loops (ObjectIds = width 24). Accepts bytes,
+   * a joined string, or an array of id strings (joined internally).
+   */
+  hexValidateBatch(input: Uint8Array | readonly string[], width: number): Uint8Array
+  /**
+   * Escape JS-RegExp metacharacters so `new RegExp(escaped, flags)` matches
+   * the input literally — the safe literal-substring-search primitive.
+   */
+  regexEscape(input: Uint8Array | string): string
   wsAcceptKey(key: Uint8Array): Uint8Array | string
   wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number
 
@@ -212,6 +225,13 @@ export interface RustScalar {
     windowMs: number,
     maxEntries?: number | null,
   ): RateLimiterInstance
+  /**
+   * Create a sharded metrics registry (counters / gauges / histograms +
+   * Prometheus render). Fully C-ABI-backed on Bun (caller-owned native
+   * handle); the napi class on Node. Call `destroy()` on ffi-backed
+   * registries at shutdown.
+   */
+  createMetricsRegistry(): MetricsRegistryInstance
   initThreadPool(rayonThreads?: number): void
   rayonNumThreads(): number
 

package/src/rust-ffi/scalar/payload.ts

@@ -10,8 +10,8 @@
 
 import type { MultipartPart, WsFrame } from '../../native'
 import { decoder } from '../../shared/bytes'
-import { writeInto } from '../into'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
+import { writeInto } from '../into'
 
 /** Read an unsigned little-endian u32 at `off`. */
 function u32LE(b: Uint8Array, off: number): number {
@@ -102,7 +102,11 @@ export function buildPayload(ctx: RustClientContext) {
       // it via the `_into` core; keeps the 64 MiB decompression-bomb cap).
       const f = ffi()
       if (f) return f.gzipDecompressInto(data, output, maxDecompressed ?? undefined)
-      return writeInto('gzip decompress', output, addon.gzipDecompress(data, maxDecompressed ?? null))
+      return writeInto(
+        'gzip decompress',
+        output,
+        addon.gzipDecompress(data, maxDecompressed ?? null),
+      )
     },
     brotliCompress(data: Uint8Array, quality?: number | null): Uint8Array {
       const f = ffi()
@@ -127,7 +131,11 @@ export function buildPayload(ctx: RustClientContext) {
       // Pooled sibling — caller-owned output buffer (keeps the 64 MiB cap).
       const f = ffi()
       if (f) return f.brotliDecompressInto(data, output, maxDecompressed ?? undefined)
-      return writeInto('brotli decompress', output, addon.brotliDecompress(data, maxDecompressed ?? null))
+      return writeInto(
+        'brotli decompress',
+        output,
+        addon.brotliDecompress(data, maxDecompressed ?? null),
+      )
     },
     multipartParse(body: Uint8Array, boundary: Uint8Array): MultipartPart[] {
       // FFI-first: packed parts (castrum_multipart_parse_packed) → unpack to