castrum 0.9.3 → 0.9.4

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

@@ -12,10 +12,10 @@
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
 import { decoder } from '../../shared/bytes'
-import { decodeUtf8Fatal } from '../../shared/codec'
+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'
 
 // 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 +60,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 +87,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 +99,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

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

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

@@ -0,0 +1,121 @@
+// src/rust-ffi/scalar/validation.ts — Validation & text-utility scalar methods.
+//
+// Mirrors rust/util/validation.rs (batch fixed-width hex validation) and
+// rust/util/text.rs (JS-RegExp metacharacter escaping). Stateless; on Bun the
+// string paths cross as cstring ARGs (engine-transcoded — zero TextEncoder)
+// and regexEscape returns via a cstring return (engine-cloned — zero decode).
+
+import { encoder, toBytes } from '../../shared/bytes'
+import { decodeUtf8 } from '../../shared/codec'
+import type { RustClientContext } from '../context'
+import { memoizeFfi, resolveNative } from '../context'
+
+/**
+ * Non-zeroing output allocation for the batch verdicts (`Buffer.allocUnsafe`
+ * skips the 4 KB memset a plain `new Uint8Array` pays; every byte is
+ * overwritten by the native write anyway).
+ */
+const allocOut = (n: number): Uint8Array =>
+  typeof Buffer !== 'undefined' && typeof Buffer.allocUnsafe === 'function'
+    ? Buffer.allocUnsafe(n)
+    : new Uint8Array(n)
+
+/** Validation / text-utility methods (`Pick<RustScalar, ...>`). */
+export function buildValidation(ctx: RustClientContext) {
+  const { transport } = ctx.runtime
+  const n = (name: string) => resolveNative(ctx, name)
+  // Lazy-memoized ffi surface: binds on first call (no eager dlopen at import).
+  const ffi = memoizeFfi(transport)
+
+  return {
+    /**
+     * Validate NEWLINE-separated strings as fixed-width hex (e.g. Mongo
+     * ObjectIds at width 24) in ONE native call → one verdict byte per line.
+     * Replaces the per-item `/^[0-9a-f]{24}$/` regex loops list endpoints
+     * scatter everywhere. Accepts an array of id strings directly — the join
+     * crosses as a `cstring` ARG, so the JS side never touches an encoder.
+     *
+     * @param input Newline-separated candidates as bytes, or an array of
+     *   candidate strings (joined internally with `\n`)
+     * @param width Exact expected length of each line (1..=4096)
+     * @returns Uint8Array of 1/0 verdicts, one per line (trailing newline
+     *   does not add an extra verdict)
+     * @throws On `width` outside 1..=4096
+     * @example
+     * ```ts
+     * rust.hexValidateBatch(['507f1f77bcf86cd799439011', 'nope'], 24) // [1, 0]
+     * ```
+     */
+    hexValidateBatch(input: Uint8Array | readonly string[], width: number): Uint8Array {
+      if (width === 0 || width > 4096 || !Number.isInteger(width)) {
+        throw new Error('hex validate batch: width must be an integer 1..=4096')
+      }
+      const f = ffi()
+      if (f) {
+        // Verdict count ≤ line count ≤ input length — one native pass.
+        const joined =
+          typeof input === 'string'
+            ? input
+            : Array.isArray(input)
+              ? (input as readonly string[]).join('\n')
+              : null
+        let out = allocOut(Math.min(joined !== null ? joined.length + 1 : input.length + 1, 4096))
+        let w =
+          joined !== null
+            ? f.hexValidateBatchStr(joined, width, out)
+            : f.hexValidateBatchInto(input as Uint8Array, width, out)
+        if (w > out.length) {
+          out = new Uint8Array(w)
+          w =
+            joined !== null
+              ? f.hexValidateBatchStr(joined, width, out)
+              : f.hexValidateBatchInto(input as Uint8Array, width, out)
+        }
+        return out.subarray(0, w)
+      }
+      const bytes = Array.isArray(input)
+        ? encoder.encode((input as readonly string[]).join('\n'))
+        : (input as Uint8Array)
+      return n('hexValidateBatch')(bytes, width) as Uint8Array
+    },
+
+    /**
+     * Escape JS-RegExp metacharacters (`\ . * + ? ^ $ { } | ( ) [ ]`) so a
+     * pattern built with `new RegExp(rust.regexEscape(userInput), 'i')`
+     * matches the input LITERALLY. Under Bun the whole call is the FFI
+     * crossing + the escape: the input crosses as a `cstring` ARG (engine-
+     * transcoded, zero encode) and the result returns as a `cstring`
+     * (engine-cloned, zero decode).
+     *
+     * @param input Arbitrary text or bytes (multi-byte UTF-8 passes through)
+     * @returns The escaped pattern string
+     * @example
+     * ```ts
+     * const re = new RegExp(rust.regexEscape('a.c*(x)'), 'i')
+     * re.test('A.C(X)') // true — literal match, not wildcard semantics
+     * ```
+     */
+    regexEscape(input: Uint8Array | string): string {
+      const f = ffi()
+      if (f) {
+        if (typeof input === 'string') {
+          const escaped = f.regexEscapeStr(input)
+          if (escaped === null) throw new Error('regex escape failed')
+          return escaped
+        }
+        // Bytes path: needed-size convention with a generous first guess.
+        const bytes = toBytes(input)
+        let out = new Uint8Array(bytes.length + 16)
+        let w = f.regexEscapeInto(bytes, out)
+        if (w > out.length) {
+          out = new Uint8Array(w)
+          w = f.regexEscapeInto(bytes, out)
+        }
+        return decodeUtf8(out.subarray(0, w))
+      }
+      // napi takes/returns strings directly.
+      const s = typeof input === 'string' ? input : decodeUtf8(toBytes(input))
+      return n('regexEscape')(s) as string
+    },
+  }
+}