castrum 0.9.0 → 0.9.2

package/src/selection.ts

@@ -8,13 +8,23 @@
 //
 // Consumers bind each operation to a fixed implementation at startup by
 // reading `opImpl(op)` here — they do NOT swap native↔js per call.
+//
+// The baked default comes from the PROVEN SELECTION registry
+// (`src/shared/proven.ts`, `PROVEN_SELECTION`): for each op the
+// benchmark-proven winner is 'native' | 'js' | 'bun' (Bun built-in
+// delegation). Bun built-in delegation is runtime-aware via the adapter's
+// `builtins` registry (`runtimeNative.builtins.has(op)` — empty under Node).
+// `test/unit/shared/proven.test.ts` verifies this baked registry matches the
+// live wiring, so it can't drift.
 
-import { lazyAddon, getAddon } from './native'
-import { isBun } from './shared/runtime'
+import { getAddon, lazyAddon } from './native'
+import { provenImpl } from './shared/proven'
+import { runtimeNative } from './runtime/native'
 
 /** Recommended implementation for an operation. */
 export type OpImpl = 'native' | 'js'
 
+/** A selection decision: recommended implementation + rationale note. */
 export interface OpDecision {
   /** The recommended implementation when the addon is available. */
   readonly impl: OpImpl
@@ -22,32 +32,6 @@ export interface OpDecision {
   readonly note?: string
 }
 
-/**
- * Ops where Bun's NATIVE built-in beats the Rust addon (measured in
- * `docs/bun-builtins-decision-matrix.md`: `Bun.gzipSync` ~2.0x, `Bun.hash.crc32`
- * 2.8–8.4x, `Bun.CryptoHasher` ~1.2x, `Bun.hash.xxHash3` ~4.2x, and
- * `crypto.getRandomValues` for token-sized random). Under Bun the fastest
- * choice for these is the pure-JS path that DELEGATES to the Bun built-in
- * (`"js"`), not the Rust addon — so we never ship something slower than what
- * Bun natively provides. Under Node the base benchmark decision stands (Rust
- * wins for gzip/random/hmac there).
- *
- * NOTE: `gzipDecompress` is deliberately NOT in this set — 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.
- */
-const BUN_WINS = new Set([
-  'gzipCompress',
-  'crc32',
-  'randomToken',
-  'hmacSha256',
-  'xxh3',
-  'urlEncode',
-  'urlDecode',
-  'base64Encode',
-  'httpDate',
-])
-
 // Lazy: importing this module does NOT dlopen the addon; `opImpl` reads the
 // baked decision from Rust on first call.
 const addon = lazyAddon(getAddon)
@@ -58,11 +42,23 @@ const addon = lazyAddon(getAddon)
  * Returns `"native"` when the Rust addon is the recommended implementation,
  * `"js"` when a pure-JS (or Bun built-in) implementation wins, or `null` for
  * unknown ops (or when the addon is unavailable — with no addon there is no
- * "native" choice). Under Bun, ops in {@link BUN_WINS} resolve to `"js"` so the
- * consumer's JS path delegates to the faster Bun built-in.
+ * "native" choice). Under Bun, ops in the adapter's builtins registry resolve
+ * to `"js"` so the consumer's JS path delegates to the faster Bun built-in.
+ *
+ * The default is the BAKED proven selection (`src/shared/proven.ts`):
+ * `native` / `js` directly, `bun` resolves to `"js"` via the builtins check
+ * above. Unknown ops (and `bun` entries on a non-Bun runtime, where no
+ * built-in exists) fall back to the addon's embedded decision
+ * (`rust/selection.rs` ← `src/selection.json`).
  */
 export const opImpl = (op: string): OpImpl | null => {
-  if (isBun() && BUN_WINS.has(op)) return 'js'
+  // Bun built-in delegation (runtime-aware — the registry is empty under Node).
+  if (runtimeNative.builtins.has(op)) return 'js'
+  // Baked proven winners are the default selection.
+  const proven = provenImpl(op)
+  if (proven === 'native') return 'native'
+  if (proven === 'js') return 'js'
+  // 'bun' on a non-Bun runtime (no built-in) or unknown ops → addon decision.
   return addon.opImpl(op)
 }
 

package/src/shared/adaptive.ts

@@ -7,8 +7,7 @@
 // observed request size to pre-size future buffers (`adaptive` option), and
 // consumers can drive their own runtime decisions (batch-vs-loop, delegate
 // vs-native, cache-size) with a bounded, noise-smoothed estimate.
-
-export interface AdaptiveEstimateOptions {
+/** Options for an `AdaptiveEstimate`: EWMA smoothing, bounds, starting value. */ export interface AdaptiveEstimateOptions {
   /**
    * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
    * lower smooths more. Default: 0.25.

package/src/shared/buffer-pool.ts

@@ -11,8 +11,7 @@
 // hold the buffer past the call). Memory is bounded by `maxBuffers` retained
 // buffers; under heavy concurrency, extra temporary buffers are allocated and
 // discarded on release.
-
-export interface BufferPoolOptions {
+/** Options for configuring a reusable byte-buffer pool. */ export interface BufferPoolOptions {
   /**
    * Initial buffer size in bytes. Default: 131072.
    */
@@ -42,6 +41,7 @@ export interface BufferPoolOptions {
   adaptive?: boolean
 }
 
+/** A borrowed buffer handle handed out by a pool; `release()` returns it. */
 export interface PooledBuffer {
   /**
    * The underlying buffer. Its byteLength is guaranteed to be at least the
@@ -59,6 +59,43 @@ export interface PooledBuffer {
   release(): void
 }
 
+/**
+ * Concrete `PooledBuffer` handle.
+ *
+ * Implemented as a class (not a per-acquire object literal with a getter +
+ * closure) so that `acquire()` allocates a single small object instead of an
+ * object + getter + closure per request. The hot ingress `run()` path
+ * acquires/releases once per request, so this removes one object allocation
+ * and one closure allocation from the per-request cost. `release()` lives on
+ * the prototype; `pool`/`buffer` are the only per-instance fields.
+ *
+ * Handles are RECYCLED by the pool (see `BufferPool.freeHandles`): a released
+ * handle object is re-pointed at a fresh buffer on the next `acquire()` so the
+ * steady state allocates zero handle objects. `buffer` and `released` are the
+ * only fields that change across a recycle. Recycling is safe because it only
+ * happens after `release()` and every internal + documented usage releases
+ * each checkout exactly once; the `released` guard still makes a double
+ * release within a single checkout a no-op.
+ */
+class PooledBufferHandle implements PooledBuffer {
+  readonly pool: BufferPool
+  buffer: Uint8Array
+  released = false
+
+  constructor(pool: BufferPool, buffer: Uint8Array) {
+    this.pool = pool
+    this.buffer = buffer
+  }
+
+  release(): void {
+    if (this.released) {
+      return
+    }
+    this.released = true
+    this.pool.returnHandle(this)
+  }
+}
+
 import { AdaptiveEstimate } from './adaptive'
 
 /**
@@ -79,9 +116,13 @@ import { AdaptiveEstimate } from './adaptive'
  */
 export class BufferPool {
   private readonly free: Uint8Array[] = []
+  /** Released handle objects available for recycling (bounded — see `maxHandles`). */
+  private readonly freeHandles: PooledBufferHandle[] = []
   private readonly initialSize: number
   private readonly maxBuffers: number
   private readonly maxInFlight: number
+  /** Upper bound on recycled handle objects retained (peak concurrency). */
+  private readonly maxHandles: number
   private readonly estimate: AdaptiveEstimate | null
   private created = 0
   private inFlight = 0
@@ -90,6 +131,7 @@ export class BufferPool {
     this.initialSize = Math.max(1, Math.floor(options.initialSize ?? 131_072))
     this.maxBuffers = Math.max(1, Math.floor(options.maxBuffers ?? 16))
     this.maxInFlight = Math.max(0, Math.floor(options.maxInFlight ?? 0))
+    this.maxHandles = this.maxBuffers + Math.max(1, this.maxInFlight)
     this.estimate =
       options.adaptive === true
         ? new AdaptiveEstimate({ alpha: 0.25, min: this.initialSize })
@@ -126,21 +168,34 @@ export class BufferPool {
     }
     const buffer = this.take(Math.max(0, Math.floor(minSize)))
     this.inFlight++
-    let released = false
-
-    return {
-      buffer,
-      get released(): boolean {
-        return released
-      },
-      release: () => {
-        if (released) {
-          return
-        }
-        released = true
-        this.inFlight--
-        this.releaseBuffer(buffer)
-      },
+    // Recycle a released handle object in the steady state instead of
+    // allocating a fresh one per acquire (removes one per-request object from
+    // the hot ingress `run()` path). Safe: handles enter `freeHandles` only
+    // after `release()`, and each checkout is released exactly once by every
+    // internal + documented usage. `buffer`/`released` are the only fields
+    // that change across a recycle.
+    const handle = this.freeHandles.pop()
+    if (handle !== undefined) {
+      handle.buffer = buffer
+      handle.released = false
+      return handle
+    }
+    return new PooledBufferHandle(this, buffer)
+  }
+
+  /**
+   * Return a borrowed handle's buffer to the pool (called by
+   * `PooledBufferHandle.release`). Internal to the pool — do not call from
+   * outside.
+   */
+  returnHandle(handle: PooledBufferHandle): void {
+    this.inFlight--
+    this.releaseBuffer(handle.buffer)
+    // Recycle the handle object for a later acquire, bounding retention so
+    // memory stays proportional to concurrency (peak in-flight), not the
+    // cumulative number of acquisitions.
+    if (this.freeHandles.length < this.maxHandles) {
+      this.freeHandles.push(handle)
     }
   }
 

package/src/shared/bytes.ts

@@ -1,16 +1,85 @@
+// src/shared/bytes.ts — shared UTF-8 / byte helpers (encoder, decoder, toBytes, toText).
+
+import { decodeUtf8, encodeUtf8, encodeUtf8Into } from './codec'
+
+/**
+ * Shared UTF-8 encoder (encode / encodeInto), backed by the runtime-native
+ * codec (`src/shared/codec.ts`): on Bun the work is done by Bun's native
+ * transfer machinery (`Bun.ArrayBufferSink` / a zero-copy `Buffer` view
+ * write); under Node it falls back to `TextEncoder`. Reusing a single object
+ * avoids allocation overhead in hot paths.
+ *
+ * `encode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface (Bun returns strings, Node returns bytes) and normalizes to bytes —
+ * a string is UTF-8 encoded, bytes pass through unchanged.
+ */
+export const encoder: {
+  encode(s: Uint8Array | string): Uint8Array
+  encodeInto(s: string, dest: Uint8Array): { read: number; written: number }
+} = {
+  encode(s) {
+    return typeof s === 'string' ? encodeUtf8(s) : s
+  },
+  encodeInto(s, dest) {
+    const written = encodeUtf8Into(s, dest)
+    // `read` mirrors `TextEncoder.encodeInto`'s shape; callers here only use
+    // `written` (a truncated write consumes the whole source in our call
+    // sites), so this is a documented approximation.
+    return { read: s.length, written }
+  },
+}
+
+/**
+ * Shared UTF-8 decoder, backed by the runtime-native codec
+ * (`src/shared/codec.ts`): on Bun it uses `new CString(ptr, 0, len)` from
+ * `bun:ffi` (JSC-native, exact-length clone); under Node it falls back to
+ * `TextDecoder`. Reusing a single object avoids allocation overhead in hot
+ * paths.
+ *
+ * `decode` accepts the string-or-bytes union the text-returning `rust.*` ops
+ * surface and normalizes to a string — bytes are UTF-8 decoded, strings pass
+ * through unchanged.
+ */
+export const decoder: {
+  decode(bytes: Uint8Array | string): string
+} = {
+  decode(bytes) {
+    return typeof bytes === 'string' ? bytes : decodeUtf8(bytes)
+  },
+}
+
 /**
- * Shared TextEncoder instance for encoding strings to UTF-8 bytes.
+ * Normalize the string-or-bytes union (the text-returning `rust.*` ops return
+ * STRINGS on the Bun path — native transfer — and bytes on the napi path) to
+ * bytes. Codec-backed — no `TextEncoder` runs on the Bun path.
+ *
+ * @param v - A string or UTF-8 byte buffer.
+ * @returns The UTF-8 bytes of `v` (identity when `v` is already bytes).
  *
- * Reusing a single encoder avoids allocation overhead in hot paths.
+ * @example
+ * ```ts
+ * toBytes('aGVsbG8=') // Uint8Array(8)
+ * ```
  */
-export const encoder = new TextEncoder()
+export function toBytes(v: Uint8Array | string): Uint8Array {
+  return typeof v === 'string' ? encodeUtf8(v) : v
+}
 
 /**
- * Shared TextDecoder instance for decoding UTF-8 bytes to strings.
+ * Normalize the string-or-bytes union to a string. Codec-backed — no
+ * `TextDecoder` runs on the Bun path.
  *
- * Reusing a single decoder avoids allocation overhead in hot paths.
+ * @param v - A string or UTF-8 byte buffer.
+ * @returns The decoded string (identity when `v` is already a string).
+ *
+ * @example
+ * ```ts
+ * toText(new Uint8Array([104, 105])) // 'hi'
+ * ```
  */
-export const decoder = new TextDecoder()
+export function toText(v: Uint8Array | string): string {
+  return typeof v === 'string' ? v : decodeUtf8(v)
+}
 
 /**
  * Cache of `DataView`s keyed by their backing buffer + creation offset.

package/src/shared/codec.ts

@@ -0,0 +1,78 @@
+// src/shared/codec.ts — runtime-native UTF-8 codec (facade).
+//
+// The runtime-native UTF-8 codec (Bun transfer machinery vs
+// `TextEncoder`/`TextDecoder`) is implemented in `src/runtime/codec.ts` and
+// selected ONCE at module load by the runtime adapter. This module re-exports
+// it so existing callers are unchanged. The Bun/Node branches live in
+// `src/runtime/codec.ts` — do NOT add `TextEncoder`/`TextDecoder` or `bun:ffi`
+// calls here.
+
+import { runtimeCodec } from '../runtime/codec'
+
+/**
+ * Encode a string to UTF-8 bytes.
+ *
+ * On Bun this uses `Bun.ArrayBufferSink` (native UTF-8 writing — no
+ * `TextEncoder`). Under Node it falls back to the standard `TextEncoder`.
+ * The implementation is selected once at load via the runtime adapter.
+ *
+ * @param s - The string to encode to UTF-8 bytes.
+ * @returns A fresh `Uint8Array` of the UTF-8 encoding of `s`.
+ *
+ * @example
+ * ```ts
+ * encodeUtf8('hello') // Uint8Array [104, 101, 108, 108, 111]
+ * ```
+ */
+export const encodeUtf8: (s: string) => Uint8Array = runtimeCodec.encodeUtf8
+
+/**
+ * Encode a string into `dest` starting at `offset`, returning bytes written.
+ *
+ * On Bun this writes through a zero-copy `Buffer` view over `dest`'s backing
+ * store (native `.write` — never splits a multibyte character); under Node it
+ * uses `TextEncoder.prototype.encodeInto`.
+ *
+ * @param s - The string to encode.
+ * @param dest - The destination buffer.
+ * @param offset - Byte offset into `dest` at which to start writing. Default 0.
+ * @returns The number of UTF-8 bytes written.
+ *
+ * @example
+ * ```ts
+ * const out = new Uint8Array(8)
+ * encodeUtf8Into('hi', out) // 2; out[0..1] = 104, 105
+ * ```
+ */
+export const encodeUtf8Into: (s: string, dest: Uint8Array, offset?: number) => number =
+  runtimeCodec.encodeUtf8Into
+
+/**
+ * Decode UTF-8 bytes to a string.
+ *
+ * On Bun this uses `new CString(ptr(bytes), 0, len)` from `bun:ffi` (JSC-native
+ * exact-length clone); under Node it falls back to the standard `TextDecoder`.
+ *
+ * @param bytes - The UTF-8 bytes to decode.
+ * @returns The decoded string (invalid sequences decode to U+FFFD replacement
+ *   characters, matching `TextDecoder` replacement mode).
+ *
+ * @example
+ * ```ts
+ * decodeUtf8(new Uint8Array([104, 105])) // 'hi'
+ * ```
+ */
+export const decodeUtf8: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8
+
+/**
+ * Decode UTF-8 bytes to a string, throwing on invalid UTF-8.
+ *
+ * Under Node this uses a fatal `TextDecoder`. On Bun (whose `CString` is
+ * replacement-mode) strictness is normally enforced by the native
+ * `castrum_utf8_valid` C-ABI probe (callers check it first via the transport's
+ * ffi surface); this fallback uses the replacement-mode decode.
+ *
+ * @param bytes - The UTF-8 bytes to decode.
+ * @returns The decoded string (throws on invalid UTF-8 under Node).
+ */
+export const decodeUtf8Fatal: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8Fatal

package/src/shared/env.ts

@@ -1,9 +1,9 @@
 // src/shared/env.ts — Centralized environment-variable resolution.
 //
-// Runtime env vars use the `CASTRUM_*` prefix; legacy `RUST_BENCH_*` / `RUST_*`
-// names are still read as aliases (see docs/ENVIRONMENT.md). All alias-chain
-// reads MUST go through `resolveEnvVar` so the chains can never drift apart
-// (they previously lived inline at several call sites with different shapes).
+// Runtime env vars use the `CASTRUM_*` prefix (plus the napi-rs standard
+// `NAPI_RS_NATIVE_LIBRARY_PATH`). All reads MUST go through `resolveEnvVar` so
+// they can never drift apart (they previously lived inline at several call
+// sites with different shapes).
 
 /** First set value among `preferred` and its legacy aliases, or `undefined`. */
 export function resolveEnvVar(

package/src/shared/log.ts

@@ -6,6 +6,7 @@
 // without wiring OpenTelemetry. For full control, use the `onRequest` /
 // `onResponse` / `onError` runtime hooks instead.
 
+/** Structured-logging severity levels (least to most severe). */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'
 
 const LEVEL_ORDER: Record<LogLevel, number> = {

package/src/shared/packed/index.ts

@@ -0,0 +1,10 @@
+// src/shared/packed/index.ts — Packed wire-format helpers (barrel).
+//
+// Re-exports the pure wire encode/decode helpers (./wire.ts), the native
+// JSON-Schema validator + batch helpers (./schema.ts), and the ergonomic
+// string parsers (./parsers.ts). Importing this barrel does NOT dlopen the
+// addon — only calling a parser in ./parsers.ts does (lazy).
+
+export * from './parsers'
+export * from './schema'
+export * from './wire'

package/src/shared/packed/parsers.ts

@@ -0,0 +1,31 @@
+// src/shared/packed/parsers.ts — High-level string parsers (convenience).
+//
+// Wrap the native packed parsers + decoders for ergonomic use, so consumers
+// don't have to hand-pack buffers or decode packed pairs:
+//   parseQueryString("a=1&b=2")    // { a: "1", b: "2" }
+//   parseCookieHeader("a=1; b=2")  // { a: "1", b: "2" }
+
+import { getAddon, lazyAddon } from '../../native'
+import { encoder } from '../bytes'
+import { pairsToObject, readPairsPacked } from './wire'
+
+// Lazy: importing this module does not dlopen the addon until first use.
+const addon = lazyAddon(getAddon)
+
+/** Parse a query string (`a=1&b=2`) into an object via the native parser. */
+export function parseQueryString(query: string): Record<string, string | string[]> {
+  const packed = addon.queryParsePacked(encoder.encode(query))
+  return pairsToObject(readPairsPacked(packed))
+}
+
+/** Parse a cookie header (`a=1; b=2`) into an object via the native parser. */
+export function parseCookieHeader(header: string): Record<string, string | string[]> {
+  const packed = addon.cookieParsePacked(encoder.encode(header))
+  return pairsToObject(readPairsPacked(packed))
+}
+
+/** Parse an application/x-www-form-urlencoded body into a key/value object. */
+export function parseFormBody(body: Uint8Array): Record<string, string | string[]> {
+  const packed = addon.formParsePacked(body)
+  return pairsToObject(readPairsPacked(packed))
+}

package/src/shared/packed/schema.ts

@@ -0,0 +1,23 @@
+// src/shared/packed/schema.ts — Native JSON-Schema validator + batch helpers.
+//
+// Thin wrapper over the native `SchemaValidator` instance: single-item handle
+// alias plus packed-batch validate helpers (bitset / count). The batch entry
+// points reuse the pure pack-scratch pool from ./wire.ts.
+
+import type { SchemaValidatorInstance } from '../../native'
+import { unpackBitset, withPackScratch } from './wire'
+
+/** Native JSON-Schema validator handle (see `createSchemaValidator`). */
+export type SchemaValidator = SchemaValidatorInstance
+
+/** Validate each item against `validator`; returns a packed validity bitset. */
+export function schemaValidateBatch(validator: SchemaValidator, items: Uint8Array[]): Uint8Array {
+  return withPackScratch(items, (packed) =>
+    unpackBitset(validator.validateBatchPackedBitset(packed)),
+  )
+}
+
+/** Validate each item against `validator`; returns the count of valid items. */
+export function schemaValidateBatchCount(validator: SchemaValidator, items: Uint8Array[]): number {
+  return withPackScratch(items, (packed) => validator.validateBatchPackedCount(packed))
+}

package/src/shared/{packed.ts → packed/wire.ts}

@@ -1,10 +1,16 @@
-import { decoder, encoder, viewForArrayBuffer } from './bytes'
-import { getAddon, lazyAddon, type MultipartPart, type SchemaValidatorInstance } from '../native'
-
-// Lazy: importing this module does not dlopen the addon until first use.
-const addon = lazyAddon(getAddon)
-
-export type SchemaValidator = SchemaValidatorInstance
+// src/shared/packed/wire.ts — Pure packed wire-format encode/decode helpers.
+//
+// The zero-allocation byte layouts shared by the batch/loader/rust-ffi layers:
+//   - unpackers:  u32 arrays, bitsets, i64/u64 arrays, byte-results, multipart
+//   - packers:    `[u32 count]{[u32 len][bytes]}` batches + string pairs
+//   - decoders:   pairs, HTTP request, and the reusable pack-scratch pool
+//
+// This module is PURE (no addon dlopen): consumers that only need these
+// helpers never touch the native layer. The native-backed ergonomic parsers
+// live in ./parsers.ts.
+
+import type { MultipartPart } from '../../native'
+import { decoder, encoder, viewForArrayBuffer } from '../bytes'
 
 function dataView(bytes: Uint8Array): DataView {
   return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
@@ -234,8 +240,13 @@ function readMultipartPartsPacked(bytes: Uint8Array): MultipartPart[] {
   return out
 }
 
+/** A decoded `[name, value]` pair from a packed buffer. */
 export type Pair = [string, string]
 
+/**
+ * Decode a packed `[u32 count][u32 keyLen][key][u32 valLen][val]...` buffer
+ * into `[name, value]` string pairs (see `packPairs` for the layout).
+ */
 export function readPairsPacked(bytes: Uint8Array): Pair[] {
   if (bytes.byteLength < 4) {
     return []
@@ -270,6 +281,10 @@ export function readPairsPacked(bytes: Uint8Array): Pair[] {
   return out
 }
 
+/**
+ * Fold `[name, value]` pairs into an object; repeated names collect into a
+ * string array (query-string/cookie semantics).
+ */
 export function pairsToObject(pairs: Pair[]): Record<string, string | string[]> {
   const out: Record<string, string | string[]> = {}
 
@@ -288,6 +303,7 @@ export function pairsToObject(pairs: Pair[]): Record<string, string | string[]>
   return out
 }
 
+/** A decoded HTTP request from the native packed parser. */
 export interface ParsedHttpRequestPacked {
   method: string
   path: string
@@ -295,6 +311,10 @@ export interface ParsedHttpRequestPacked {
   headers: Record<string, string>
 }
 
+/**
+ * Decode a native `httpParseRequestPacked` buffer into a plain request object
+ * (zero-alloc on the Rust side; this builds the JS strings once).
+ */
 export function readHttpPacked(bytes: Uint8Array): ParsedHttpRequestPacked {
   const dv = dataView(bytes)
   let offset = 0
@@ -448,6 +468,10 @@ export function withPackScratch2<T>(
   }
 }
 
+/**
+ * Pack `[name, value]` string pairs into the native `[u32 count]...` layout
+ * that `readPairsPacked` / the batch validators consume.
+ */
 export function packPairs(pairs: Array<[string, string]>): Uint8Array {
   const encoded = pairs.map(([key, value]) => [encoder.encode(key), encoder.encode(value)] as const)
 
@@ -478,35 +502,3 @@ export function packPairs(pairs: Array<[string, string]>): Uint8Array {
 
   return out
 }
-
-export function schemaValidateBatch(validator: SchemaValidator, items: Uint8Array[]): Uint8Array {
-  return withPackScratch(items, (packed) =>
-    unpackBitset(validator.validateBatchPackedBitset(packed)),
-  )
-}
-
-export function schemaValidateBatchCount(validator: SchemaValidator, items: Uint8Array[]): number {
-  return withPackScratch(items, (packed) => validator.validateBatchPackedCount(packed))
-}
-
-// ── High-level string parsers (convenience) ──────────────────────
-// Wrap the native packed parsers + decoders for ergonomic use, so consumers
-// don't have to hand-pack buffers or decode packed pairs:
-//   parseQueryString("a=1&b=2")    // { a: "1", b: "2" }
-//   parseCookieHeader("a=1; b=2")  // { a: "1", b: "2" }
-
-export function parseQueryString(query: string): Record<string, string | string[]> {
-  const packed = addon.queryParsePacked(encoder.encode(query))
-  return pairsToObject(readPairsPacked(packed))
-}
-
-export function parseCookieHeader(header: string): Record<string, string | string[]> {
-  const packed = addon.cookieParsePacked(encoder.encode(header))
-  return pairsToObject(readPairsPacked(packed))
-}
-
-/** Parse an application/x-www-form-urlencoded body into a key/value object. */
-export function parseFormBody(body: Uint8Array): Record<string, string | string[]> {
-  const packed = addon.formParsePacked(body)
-  return pairsToObject(readPairsPacked(packed))
-}