castrum 0.9.7 → 0.9.9

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

@@ -47,17 +47,32 @@ export interface RustBatch {
   base64UrlDecode(items: Uint8Array[]): Uint8Array[]
 
   // ── Backend-framework features ──
+  /**
+   * Parallel password hashing. WARNING: the SAME `salt` is applied to every
+   * item. Reusing one salt across real user passwords enables a single
+   * precomputation to attack them all — generate a unique salt per password in
+   * production (this batch form is for precomputed/benchmark workloads).
+   */
   passwordHash(
     passwords: Uint8Array[],
     salt: Uint8Array,
     options?: PasswordHashOptions | null,
   ): Uint8Array[]
+  /**
+   * Parallel AEAD encrypt. `nonce` MUST be exactly 12 bytes and MUST be fresh
+   * for every batch call with the same key: a unique per-item nonce is derived
+   * by XOR-ing the item index into the low 8 bytes, so reusing a base nonce
+   * across calls reuses keystream/tag material for colliding indices
+   * (catastrophic for AES-GCM / ChaCha20-Poly1305). A non-12-byte nonce is
+   * rejected with an error.
+   */
   aeadEncrypt(
     key: Uint8Array,
     nonce: Uint8Array,
     items: Uint8Array[],
     algorithm?: string | null,
   ): Uint8Array[]
+  /** Parallel AEAD decrypt. Pass the SAME base nonce and item order as the encrypt call. */
   aeadDecrypt(
     key: Uint8Array,
     nonce: Uint8Array,

package/src/rust-ffi/context.ts

@@ -21,6 +21,51 @@ import { normalizeExt, resolveRayonThreads } from './options'
 // batch.ts uses for its packed entries.
 const nativeFnCache = new Map<string, unknown>()
 
+/** Max entries retained per process-wide MIME cache (insertion-order eviction). */
+const MIME_CACHE_MAX = 1024
+
+/**
+ * Process-wide extension-bytes → MIME-bytes cache shared by every client
+ * context: the native addon is a process singleton, so `extension → MIME` is a
+ * global pure lookup. Bounded by `MIME_CACHE_MAX`; on overflow the oldest half
+ * is evicted via {@link evictOldestHalf}. Exported for the memory-flush path
+ * and tests — callers must NOT mutate the returned slices.
+ */
+export const mimeByText = new Map<string, Uint8Array>()
+
+/**
+ * Process-wide extension-string → MIME-string memo (the `text.mimeFromExtension`
+ * fast path). Bounded exactly like {@link mimeByText}.
+ */
+export const mimeStrCache = new Map<string, string>()
+
+/**
+ * Evict the oldest half of a cache map (insertion order) and return the keys
+ * dropped. Generational eviction — halving at the cap amortizes the cost rather
+ * than paying a delete per insertion. Returns an empty array below the cap.
+ */
+export function evictOldestHalf<K, V>(map: Map<K, V>): K[] {
+  if (map.size < MIME_CACHE_MAX) return []
+  const drop = Math.ceil(map.size / 2)
+  const dropped: K[] = []
+  for (const key of map.keys()) {
+    if (dropped.length >= drop) break
+    dropped.push(key)
+  }
+  for (const key of dropped) map.delete(key)
+  return dropped
+}
+
+/**
+ * Clear the process-wide MIME caches (both the bytes and string forms). This is
+ * the impure-boundary hook consumed by the public `flushMemory()`; safe to call
+ * at any time, including before the addon has ever been loaded.
+ */
+export function clearMimeCaches(): void {
+  mimeByText.clear()
+  mimeStrCache.clear()
+}
+
 /**
  * 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
@@ -91,7 +136,6 @@ export interface RustClientContext {
   runtime: NativeRuntimeAdapter
   /** Per-instance toggles (mime/hmac caching). */
   state: { mimeCache: boolean; hmacCache: boolean }
-  mimeByText: Map<string, Uint8Array>
   hmacSigners: WeakMap<Uint8Array, HmacSignerInstance>
 
   /** Initialize the process-wide rayon pool exactly once (no-op after). */
@@ -110,7 +154,6 @@ export interface RustClientContext {
 
 /** Build a per-instance context from client options. */
 export function createContext(options: RustOptions): RustClientContext {
-  const mimeByText = new Map<string, Uint8Array>()
   const hmacSigners = new WeakMap<Uint8Array, HmacSignerInstance>()
   const state = {
     mimeCache: options.mimeCache !== false,
@@ -152,6 +195,7 @@ export function createContext(options: RustOptions): RustClientContext {
 
     let val = mimeByText.get(key)
     if (!val) {
+      evictOldestHalf(mimeByText)
       val = addon.mimeFromExtension(ext)
       mimeByText.set(key, val)
     }
@@ -181,7 +225,6 @@ export function createContext(options: RustOptions): RustClientContext {
     addon,
     runtime: runtimeNative,
     state,
-    mimeByText,
     hmacSigners,
     ensurePool,
     isPoolInitialized,

package/src/rust-ffi/options.ts

@@ -93,6 +93,25 @@ export function asNumber(value: unknown): number {
   return 0
 }
 
+/**
+ * Throw when a signing secret/key is empty.
+ *
+ * An empty HMAC/JWT/CSRF secret is effectively a public function — anyone can
+ * compute the MAC — so a blank/missing env var would silently mint forgeable
+ * tokens. The raw `rust.hmacSha256` primitive deliberately stays tolerant of an
+ * empty key (see the empty-input matrix); this guards the auth surfaces built
+ * on top of it.
+ *
+ * @param secret - The secret/key bytes about to be used.
+ * @param op - Operation name for the error message.
+ * @throws Error when `secret` is empty.
+ */
+export function assertNonEmptySecret(secret: Uint8Array, op: string): void {
+  if (secret.byteLength === 0) {
+    throw new Error(`${op}: secret must not be empty`)
+  }
+}
+
 /** Normalize a file-extension byte slice to a lowercase string w/o a dot. */
 export function normalizeExt(ext: Uint8Array): string {
   let s: string

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

@@ -12,6 +12,7 @@ import type { PasswordHashOptions } from '../../native'
 import { encoder } from '../../shared/bytes'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
+import { assertNonEmptySecret } from '../options'
 
 /** Auth / crypto scalar methods (`Pick<RustScalar, ...>`). */
 export function buildCrypto(ctx: RustClientContext) {
@@ -152,14 +153,17 @@ export function buildCrypto(ctx: RustClientContext) {
       return writeInto('verify cookie', output, value)
     },
     csrfToken(secret: Uint8Array): Uint8Array | string {
+      assertNonEmptySecret(secret, 'csrfToken')
       return resolveNative(ctx, 'csrfToken')(secret) as Uint8Array | string
     },
     csrfTokenInto(secret: Uint8Array, output: Uint8Array): number {
+      assertNonEmptySecret(secret, 'csrfTokenInto')
       const f = ffi()
       if (f) return f.csrfTokenInto(secret, output)
       return writeInto('csrf token', output, addon.csrfToken(secret))
     },
     csrfVerify(token: Uint8Array, secret: Uint8Array): boolean {
+      assertNonEmptySecret(secret, 'csrfVerify')
       return resolveNative(ctx, 'csrfVerify')(token, secret) as boolean
     },
     jwtSign(
@@ -175,6 +179,7 @@ export function buildCrypto(ctx: RustClientContext) {
       // preserves JS insertion order while napi's serde_json sorts keys — for
       // multi-key claims the two transports emit different-but-equally-valid
       // tokens (both verify; parity tests cross-verify semantically).
+      assertNonEmptySecret(secret, 'jwtSign')
       const f = ffi()
       if (f) {
         const token = f.jwtSignBytes(
@@ -198,6 +203,7 @@ export function buildCrypto(ctx: RustClientContext) {
       ttlSeconds?: number | null,
       nowSeconds?: number,
     ): Uint8Array | string {
+      assertNonEmptySecret(secret, 'jwtSignBytes')
       const f = ffi()
       if (f) {
         // The C-ABI `ttl <= 0` sentinel matches napi's Option<i64> (inject only
@@ -223,6 +229,7 @@ export function buildCrypto(ctx: RustClientContext) {
       ttlSeconds?: number | null,
       nowSeconds?: number,
     ): number {
+      assertNonEmptySecret(secret, 'jwtSignBytesInto')
       const f = ffi()
       if (f) {
         return f.jwtSignBytesInto(
@@ -245,6 +252,7 @@ export function buildCrypto(ctx: RustClientContext) {
       )
     },
     jwtVerify(token: Uint8Array, secret: Uint8Array, nowSeconds?: number): unknown {
+      assertNonEmptySecret(secret, 'jwtVerify')
       const f = ffi()
       if (f) {
         // Verify via the FFI cstring path (castrum_jwt_verify): the engine

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

@@ -27,7 +27,20 @@ import type { BunFFI } from '../../native/ffi'
 import { encoder } from '../../shared/bytes'
 import { decodeUtf8, encodeUtf8 } from '../../shared/codec'
 import type { RustClientContext } from '../context'
-import { asNumber } from '../options'
+import { asNumber, assertNonEmptySecret } from '../options'
+
+/**
+ * Convert a napi `innerPtr()` (u64) into a JS number handle, rejecting values
+ * above `Number.MAX_SAFE_INTEGER`: the `Number()` conversion would silently
+ * round a high canonical address into a wild pointer.
+ */
+function handlePtr(inner: bigint | null | undefined): number {
+  const v = inner ?? 0n
+  if (v < 0n || v > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error('castrum: native handle exceeds Number.MAX_SAFE_INTEGER')
+  }
+  return Number(v)
+}
 
 // ── FFI-backed instance wrappers ───────────────────────────────────────────
 // On Bun, instances whose methods have a STATELESS C-ABI sibling are backed by
@@ -339,17 +352,24 @@ function ffiFormParser(ffi: BunFFI): FormParserInstance {
  * `values.join('\u001f')` — ZERO TextEncoder work (Bun 1.4 zero-copy text).
  */
 function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
-  const handle = ffi.metricsCreate()
+  let handle = ffi.metricsCreate()
+  // Destroyed state is terminal: every method that would pass the handle to
+  // native memory throws instead of dereferencing a freed pointer, and a
+  // second destroy is a no-op (not a double-free).
+  const live = (): number => {
+    if (handle === 0) throw new Error('metrics registry: already destroyed')
+    return handle
+  }
   return {
     counter(name, labelKeys) {
-      return ffi.metricsCounter(handle, name, (labelKeys ?? []).join('\u001f'))
+      return ffi.metricsCounter(live(), name, (labelKeys ?? []).join('\u001f'))
     },
     gauge(name, labelKeys) {
-      return ffi.metricsGauge(handle, name, (labelKeys ?? []).join('\u001f'))
+      return ffi.metricsGauge(live(), name, (labelKeys ?? []).join('\u001f'))
     },
     histogram(name, labelKeys, buckets) {
       return ffi.metricsHistogram(
-        handle,
+        live(),
         name,
         (labelKeys ?? []).join('\u001f'),
         (buckets ?? []).join(','),
@@ -357,13 +377,13 @@ function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
     },
     record(series, values, amount) {
       const joined = (values ?? []).join('\u001f')
-      if (!ffi.metricsRecordStr(handle, series, joined, amount ?? 1)) {
+      if (!ffi.metricsRecordStr(live(), 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)) {
+      if (!ffi.metricsGaugeSetStr(live(), series, joined, value)) {
         throw new Error('metrics gauge set: unknown series / arity mismatch')
       }
     },
@@ -371,24 +391,27 @@ function ffiMetricsRegistry(ffi: BunFFI): MetricsRegistryInstance {
       // 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)
+      let w = ffi.metricsRender(live(), out)
       if (w > out.length) {
         out = new Uint8Array(w)
-        w = ffi.metricsRender(handle, out)
+        w = ffi.metricsRender(live(), out)
       }
       return decodeUtf8(out.subarray(0, w))
     },
     destroy() {
-      ffi.metricsDestroy(handle)
+      if (handle !== 0) {
+        ffi.metricsDestroy(handle)
+        handle = 0
+      }
     },
     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)
+      let w = ffi.metricsSnapshot(live(), out)
       if (w > out.length) {
         out = new Uint8Array(w)
-        w = ffi.metricsSnapshot(handle, out)
+        w = ffi.metricsSnapshot(live(), out)
       }
       return out.subarray(0, w)
     },
@@ -405,11 +428,12 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.SchemaValidator(schema)
-        return ffiSchemaValidator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiSchemaValidator(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.SchemaValidator(schema)
     },
     createHmacSigner(key: Uint8Array): HmacSignerInstance {
+      assertNonEmptySecret(key, 'createHmacSigner')
       const ffi = transport.ffi
       if (ffi) return ffiHmacSigner(key, ffi)
       return new addon.HmacSigner(key)
@@ -418,7 +442,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.TemplateRenderer(source)
-        return ffiTemplateRenderer(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiTemplateRenderer(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.TemplateRenderer(source)
     },
@@ -440,7 +464,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
-        return ffiConditionalRequest(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiConditionalRequest(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.ConditionalRequest(etagValue, lastModifiedSecs ?? undefined)
     },
@@ -448,7 +472,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.AcceptNegotiator(supported)
-        return ffiAcceptNegotiator(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiAcceptNegotiator(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.AcceptNegotiator(supported)
     },
@@ -458,11 +482,13 @@ export function buildFactories(ctx: RustClientContext) {
       return new addon.Base64Codec(urlSafe ?? undefined, padding ?? undefined)
     },
     createCookieSigner(secret: Uint8Array): CookieSignerInstance {
+      assertNonEmptySecret(secret, 'createCookieSigner')
       const ffi = transport.ffi
       if (ffi) return ffiCookieSigner(secret, ffi)
       return new addon.CookieSigner(secret)
     },
     createCsrfProtector(secret: Uint8Array): CsrfProtectorInstance {
+      assertNonEmptySecret(secret, 'createCsrfProtector')
       const ffi = transport.ffi
       if (ffi) return ffiCsrfProtector(secret, ffi)
       return new addon.CsrfProtector(secret)
@@ -474,15 +500,16 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.UrlBuilder(base)
-        return ffiUrlBuilder(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiUrlBuilder(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.UrlBuilder(base)
     },
     createJwtSigner(secret: Uint8Array, ttlSeconds?: number): JwtSignerInstance {
+      assertNonEmptySecret(secret, 'createJwtSigner')
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.JwtSigner(secret, ttlSeconds ?? undefined)
-        return ffiJwtSigner(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiJwtSigner(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.JwtSigner(secret, ttlSeconds ?? undefined)
     },
@@ -500,7 +527,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.MediaTypeMatcher(expected)
-        return ffiMediaTypeMatcher(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiMediaTypeMatcher(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.MediaTypeMatcher(expected)
     },
@@ -512,7 +539,7 @@ export function buildFactories(ctx: RustClientContext) {
       const ffi = transport.ffi
       if (ffi) {
         const napi = new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
-        return ffiRateLimiter(napi, Number(napi.innerPtr?.() ?? 0n), ffi)
+        return ffiRateLimiter(napi, handlePtr(napi.innerPtr?.()), ffi)
       }
       return new addon.RateLimiter(limit, windowMs, maxEntries ?? undefined)
     },
@@ -532,5 +559,11 @@ export function buildFactories(ctx: RustClientContext) {
     rayonNumThreads(): number {
       return asNumber(addon.rayonNumThreads() as unknown)
     },
+    clearSchemaCache(): void {
+      // Defensive: a stale addon built before this symbol, or a failed bind,
+      // must make this a no-op rather than a throw (flushMemory calls it).
+      const native = addon as unknown as { clearSchemaCache?: () => void }
+      native.clearSchemaCache?.()
+    },
   }
 }

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

@@ -12,7 +12,7 @@
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
 import { decoder, hasNul } from '../../shared/bytes'
-import { decodeUtf8Fatal, decodeUtf8Range } from '../../shared/codec'
+import { decodeUtf8Fatal, decodeUtf8Range, decodeUtf8RangeView } from '../../shared/codec'
 import { packPairs } from '../../shared/packed'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
@@ -59,6 +59,19 @@ function u32LE(b: Uint8Array, off: number): number {
   )
 }
 
+/** ASCII byte form of the two known media-type param keys (byte-compare
+ * targets — avoids decoding the key string for every packed param). */
+const CHARSET_KEY_BYTES = new Uint8Array([0x63, 0x68, 0x61, 0x72, 0x73, 0x65, 0x74]) // 'charset'
+const BOUNDARY_KEY_BYTES = new Uint8Array([0x62, 0x6f, 0x75, 0x6e, 0x64, 0x61, 0x72, 0x79]) // 'boundary'
+
+/** Byte-equality of `b[off..off+len]` with the literal `lit` (no allocation). */
+function keyBytesEqual(b: Uint8Array, off: number, lit: Uint8Array): boolean {
+  for (let i = 0; i < lit.length; i++) {
+    if ((b[off + i] ?? 0) !== (lit[i] ?? 0)) return false
+  }
+  return true
+}
+
 /**
  * Unpack the `castrum_parse_media_type` verdict into the napi-shaped result.
  * Layout: `[u32 mediaTypeLen][mediaType][u32 charsetLen (0xFFFFFFFF = none)]
@@ -69,42 +82,75 @@ function u32LE(b: Uint8Array, off: number): number {
 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.
+  // ONE view per result: `decodeUtf8RangeView` decodes at absolute offsets
+  // into a bounded Buffer resolved once here — the per-field WeakMap lookup
+  // + offset arithmetic in `decodeUtf8Range` disappear (profile: unpackMediaType
+  // called the cached-view path 5x per result).
+  const view = Buffer.from(packed.buffer, packed.byteOffset, packed.byteLength)
   let off = 0
   const mtLen = u32LE(packed, off)
   off += 4
-  const mediaType = decodeUtf8Range(packed, off, off + mtLen)
+  const mediaType = decodeUtf8RangeView(view, off, off + mtLen)
   off += mtLen
   let charset: string | null = null
   const csLen = u32LE(packed, off)
   off += 4
   if (csLen !== 0xffffffff) {
-    charset = decodeUtf8Range(packed, off, off + csLen)
+    charset = decodeUtf8RangeView(view, off, off + csLen)
     off += csLen
   }
   let boundary: string | null = null
   const bLen = u32LE(packed, off)
   off += 4
   if (bLen !== 0xffffffff) {
-    boundary = decodeUtf8Range(packed, off, off + bLen)
+    boundary = decodeUtf8RangeView(view, off, off + bLen)
     off += bLen
   }
   const count = u32LE(packed, off)
   off += 4
   const params: Record<string, string> = {}
+  // The summary slots above hold the FIRST charset/boundary occurrence (the
+  // Rust core fills them via `params.iter().find(...)`), while `params` keeps
+  // the LAST duplicate (JS assignment order). Reusing the already-decoded
+  // summary string for the first matching param skips one redundant ranged
+  // decode per named field without changing any observable value.
+  let charsetTaken = charset === null
+  let boundaryTaken = boundary === null
   for (let i = 0; i < count; i++) {
     const kLen = u32LE(packed, off)
     off += 4
-    const key = decodeUtf8Range(packed, off, off + kLen)
+    // Byte-compare the param KEY against the ASCII literals BEFORE decoding:
+    // on a match the key decode is skipped (`params` is keyed by the identical
+    // literal) and the summary/decided-value path handles the value. A
+    // byte-match to 'charset'/'boundary' implies valid UTF-8 for those bytes,
+    // so the skipped decode was exact — observable behavior unchanged
+    // (non-matching keys decode normally, casing preserved).
+    let key: string
+    if (kLen === 7 && keyBytesEqual(packed, off, CHARSET_KEY_BYTES)) {
+      key = 'charset'
+    } else if (kLen === 8 && keyBytesEqual(packed, off, BOUNDARY_KEY_BYTES)) {
+      key = 'boundary'
+    } else {
+      key = decodeUtf8RangeView(view, off, off + kLen)
+    }
     off += kLen
     const vLen = u32LE(packed, off)
     off += 4
-    const val = decodeUtf8Range(packed, off, off + vLen)
+    let val: string
+    if (!charsetTaken && key === 'charset' && charset !== null) {
+      val = charset
+      charsetTaken = true
+    } else if (!boundaryTaken && key === 'boundary' && boundary !== null) {
+      val = boundary
+      boundaryTaken = true
+    } else {
+      val = decodeUtf8RangeView(view, off, off + vLen)
+    }
     off += vLen
     params[key] = val
   }
   return { mediaType, charset, boundary, params }
 }
-
 /** 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]}`.
  * Ranged decode off the pooled buffer + shared f32 bit-reinterpret views —
@@ -276,7 +322,11 @@ export function buildHttp(ctx: RustClientContext) {
     queryParsePacked(input: Uint8Array): Uint8Array {
       const f = ffi()
       if (f) {
-        const out = new Uint8Array(input.length * 9 + 16)
+        // For k nonempty pairs in n bytes, k <= (n + 1) / 2: each
+        // pair needs a byte and adjacent pairs need a separator. Packed size
+        // <= 4 + 8k + (n - k + 1) <= 5n + 8; decoding never expands bytes.
+        // Cookie/form siblings use the same bound and retain fresh ownership.
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.queryParsePackedInto(input, out)
         return out.subarray(0, w)
       }
@@ -288,7 +338,7 @@ export function buildHttp(ctx: RustClientContext) {
     cookieParsePacked(input: Uint8Array): Uint8Array {
       const f = ffi()
       if (f) {
-        const out = new Uint8Array(input.length * 9 + 16)
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.cookieParsePackedInto(input, out)
         return out.subarray(0, w)
       }
@@ -301,7 +351,7 @@ export function buildHttp(ctx: RustClientContext) {
       const f = ffi()
       if (f) {
         // x-www-form-urlencoded uses the SAME packed-pairs core as query parse.
-        const out = new Uint8Array(input.length * 9 + 16)
+        const out = new Uint8Array(input.length * 5 + 8)
         const w = f.formParsePackedInto(input, out)
         return out.subarray(0, w)
       }

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

@@ -215,7 +215,10 @@ export interface RustScalar {
   createMediaTypeMatcher(expected: Uint8Array): MediaTypeMatcherInstance
   /**
    * Sharded fixed-window per-key rate limiter. `maxEntries` clamps internally
-   * (default 1,048,576). Each instance owns an independent budget.
+   * (default 1,048,576) and has an effective floor of 16,384
+   * (`max_per_shard = max(maxEntries / 256, 64)` × 256 shards) — values below
+   * that are silently raised, so don't rely on it to bound a tiny key space.
+   * Each instance owns an independent budget.
    * @remarks Scalar per-check cost: ~3-14x SLOWER than the JS Map baseline —
    * prefer the ingress pipeline (one FFI for all stages) for native rate
    * limiting in a request path. [measured 2026-08]
@@ -234,6 +237,20 @@ export interface RustScalar {
   createMetricsRegistry(): MetricsRegistryInstance
   initThreadPool(rayonThreads?: number): void
   rayonNumThreads(): number
+  /**
+   * Drop the process-wide compiled request-body schema cache. Identical schema
+   * bytes are compiled once and shared across `Ingress` / `NativeRoute`
+   * instances; this releases those compiled validators (already-constructed
+   * instances keep their own shared reference and are unaffected). Idempotent,
+   * and a safe no-op when the native addon is absent or predates the symbol
+   * (the public `flushMemory()` relies on that).
+   *
+   * Maintenance-only escape hatch — NOT a benchmarked op, so it is intentionally
+   * exempt from `PROVEN_SELECTION` / `selection.json` (there is no native-vs-JS
+   * winner to classify). `test/unit/contract/proven.test.ts` only requires
+   * registry coverage for selection.json ops + Bun built-ins.
+   */
+  clearSchemaCache(): void
 
   // ── Backend-framework scalar features ──
   jwtSign(

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

@@ -72,6 +72,11 @@ export function buildPayload(ctx: RustClientContext) {
   // Lazy-memoized ffi surface: binds on first call, single local read after.
   const ffi = memoizeFfi(transport)
 
+  // Per-Worker reused scratch for the object-returning multipartParse (the
+  // packed bytes are consumed synchronously — data is copied out, so the
+  // scratch never escapes; NOT shared with the byte-returning packed paths).
+  let SCRATCH: Uint8Array | null = null
+
   return {
     gzipCompress(data: Uint8Array, level?: number | null): Uint8Array {
       // Optimal by default under Bun: `Bun.gzipSync` (native zlib) is ~2x
@@ -140,8 +145,29 @@ export function buildPayload(ctx: RustClientContext) {
     multipartParse(body: Uint8Array, boundary: Uint8Array): MultipartPart[] {
       // FFI-first: packed parts (castrum_multipart_parse_packed) → unpack to
       // the object shape. napi keeps its object path.
+      //
+      // REUSED SCRATCH: the unpack consumes the packed bytes synchronously and
+      // each part's `data` is COPIED out (napi parity) — nothing aliases the
+      // scratch after return, so the escaping-buffer rule does not apply here.
+      // Sizing matches the allocating sibling (body + boundary + 64).
       const f = ffi()
-      if (f) return unpackMultipart(f.multipartParsePacked(body, boundary))
+      if (f) {
+        const need = body.length + boundary.length + 64
+        // Keep retained scratch bounded; the allocating transport handles exact
+        // growth and the output cap for large uploads. The public Into wrapper
+        // THROWS on insufficient capacity, rather than returning a needed size.
+        if (need > 64 * 1024) return unpackMultipart(f.multipartParsePacked(body, boundary))
+        if (!SCRATCH || SCRATCH.length < need) SCRATCH = new Uint8Array(need)
+        let w: number
+        try {
+          w = f.multipartParsePackedInto(body, boundary, SCRATCH)
+        } catch {
+          // An estimate miss (e.g. UTF-8 replacement expansion) uses the same
+          // checked allocating path. Malformed input still fails there.
+          return unpackMultipart(f.multipartParsePacked(body, boundary))
+        }
+        return unpackMultipart(SCRATCH.subarray(0, w))
+      }
       // Normalize napi `Option<String>` (undefined) → null and expose the
       // camelCase `contentType` key (napi renames `content_type` to camelCase).
       return addon.multipartParse(body, boundary).map((p) => ({

package/src/rust-ffi/text.ts

@@ -14,7 +14,7 @@
 // napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
 import { decoder, encoder, hasNul } from '../shared/bytes'
-import { type RustClientContext, resolveNative } from './context'
+import { evictOldestHalf, mimeStrCache, type RustClientContext, resolveNative } from './context'
 
 /**
  * Scratch for the byte-path `Sec-WebSocket-Accept` fallback (28 chars; the
@@ -67,9 +67,9 @@ export function buildText(ctx: RustClientContext): RustText {
   const { builtins, transport } = ctx.runtime
   // String memo: the byte path already caches the native bytes; this avoids the
   // encode → native lookup → slice → decode round-trip for repeated extension
-  // strings (the common case) — 0 allocations on a cache hit.
-  const mimeStrCache = new Map<string, string>()
-
+  // strings (the common case) — 0 allocations on a cache hit. The map is
+  // process-wide and bounded by `evictOldestHalf` (MIME_CACHE_MAX) — see
+  // ./context.ts.
   return {
     mimeFromExtension(ext) {
       let mime = mimeStrCache.get(ext)
@@ -81,6 +81,7 @@ export function buildText(ctx: RustClientContext): RustText {
         mime = f
           ? (f.mimeFromExtension(ext) ?? 'application/octet-stream')
           : decoder.decode(ctx.cachedMime(encoder.encode(ext)))
+        evictOldestHalf(mimeStrCache)
         mimeStrCache.set(ext, mime)
       }
       return mime