castrum 0.9.2 → 0.9.4

package/src/integration/index.ts

@@ -8,22 +8,22 @@
 //   - sseResponse      → server-sent-events response framed on the fast path
 
 export {
+  runMany,
+  runOne,
+  validateCount,
+  validateMany,
+} from './batch'
+export {
+  type CreatePipelineOptions,
   createPipeline,
   type IngressPipeline,
-  type PipelineResult,
   type PipelineContext,
+  type PipelineResult,
   type PreprocessOutcome,
-  type CreatePipelineOptions,
 } from './pipeline'
+export { type SseEvent, sseResponse } from './streaming'
 export {
   createWebSocketUpgrade,
   type WebSocketUpgradeOptions,
   type WebSocketUpgradeResult,
 } from './websocket'
-export { sseResponse, type SseEvent } from './streaming'
-export {
-  validateMany,
-  validateCount,
-  runMany,
-  runOne,
-} from './batch'

package/src/integration/pipeline.ts

@@ -7,18 +7,18 @@
 // context to the app's own handler. `handleRequest` is a fetch-compatible
 // convenience that serves the terminal response or a rendered OK response.
 
+import { readBodyWithLimit } from '../ingress/body'
+import type { BakedIngressResult } from '../ingress/decode/baked-result'
 import {
-  createIngressHandler,
   type BakedIngressRuntime,
+  createIngressHandler,
   type OptimizedIngressHandler,
 } from '../ingress/handlers'
-import type { BakedContext } from '../ingress/types'
 import type { IngressHandlerOptions } from '../ingress/options'
-import { readBodyWithLimit } from '../ingress/body'
-import { DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS } from '../ingress/shared'
-import { generateRequestId } from '../shared/request-id'
+import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../ingress/shared'
+import type { BakedContext } from '../ingress/types'
 import { decoder } from '../shared/bytes'
-import type { BakedIngressResult } from '../ingress/decode/baked-result'
+import { generateRequestId } from '../shared/request-id'
 
 /** Readonly snapshot of the ingress decision, safe after `run()` returns. */
 export interface PipelineResult {

package/src/integration/websocket.ts

@@ -1,8 +1,8 @@
 // src/integration/websocket.ts — WebSocket upgrade handshake helper.
 
-import { isBun } from '../shared/runtime'
 import { rust } from '../rust-ffi'
-/** Options for `createWebSocketUpgrade` (supported subprotocols). */export interface WebSocketUpgradeOptions {
+import { isBun } from '../shared/runtime'
+/** Options for `createWebSocketUpgrade` (supported subprotocols). */ export interface WebSocketUpgradeOptions {
   /** Subprotocols this server supports; the first client-requested match wins. */
   protocols?: ReadonlyArray<string>
 }

package/src/loader/index.ts

@@ -27,11 +27,7 @@
 import { rust } from '../rust-ffi'
 import { encoder, viewForArrayBuffer } from '../shared/bytes'
 import type { SchemaValidator } from '../shared/packed'
-import {
-  createLruCache,
-  createTickCoalescer,
-  type LoadRequest,
-} from './batch'
+import { createLruCache, createTickCoalescer, type LoadRequest } from './batch'
 import { createCostModel, nowNs } from './cost'
 import {
   fnvBatchKeysInto,

package/src/loader/ops.ts

@@ -19,10 +19,10 @@
 // the loader never pays a conversion cost on the hot path. This module is the
 // single source of truth for what the loader can dispatch.
 
+import type { PasswordHashOptions } from '../native'
 import { rust } from '../rust-ffi'
 import { addon } from '../rust-ffi/addon'
 import { decoder } from '../shared/bytes'
-import type { PasswordHashOptions } from '../native'
 import type { SchemaValidator } from '../shared/packed'
 
 /** Empty bytes sentinel for skip-on-error scalar parity (e.g. AEAD decrypt). */

package/src/native/ffi/build/codecs.ts

@@ -9,7 +9,7 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { SELFTEST_HEX, SELFTEST_JSON } from '../constants'
 import type { BunFFI, Raw3, Raw4, Raw5, Raw6, Raw8, Raw9, Raw10, RawCStr } from '../types'
 import type { BuildCtx } from './util'
-import { argon2PhcLength, cstr, flag, growExact, writeOrThrow } from './util'
+import { allocOut, argon2PhcLength, cstr, flag, growExact, writeOrThrow } from './util'
 
 /**
  * Build the codec/crypto/auth methods of the BunFFI surface. `ctx` is
@@ -34,7 +34,17 @@ export function buildCodecs(
   const validateUuid = sym.castrum_validate_uuid as (...a: unknown[]) => number | bigint
   const validateIpv4 = sym.castrum_validate_ipv4 as (...a: unknown[]) => number | bigint
   const validateIpv6 = sym.castrum_validate_ipv6 as (...a: unknown[]) => number | bigint
+  const validateEmailBytes = sym.castrum_validate_email_bytes as (
+    ...a: unknown[]
+  ) => number | bigint
+  const validateUuidBytes = sym.castrum_validate_uuid_bytes as (...a: unknown[]) => number | bigint
+  const validateIpv4Bytes = sym.castrum_validate_ipv4_bytes as (...a: unknown[]) => number | bigint
+  const validateIpv6Bytes = sym.castrum_validate_ipv6_bytes as (...a: unknown[]) => number | bigint
   const jsonSumRaw = sym.castrum_json_sum_ids as Raw4
+  const hexBatchRaw = sym.castrum_hex_validate_batch as Raw5
+  const hexBatchStrRaw = sym.castrum_hex_validate_batch_str as Raw4
+  const regexEscapeRaw = sym.castrum_regex_escape as Raw4
+  const regexEscapeStrRaw = sym.castrum_regex_escape_str as RawCStr
   const hmacVerify = sym.castrum_hmac_sha256_verify as Raw6
   const csrfVerify = sym.castrum_csrf_verify as Raw4
   const passwordVerify = sym.castrum_password_verify as Raw4
@@ -176,6 +186,41 @@ export function buildCodecs(
     validateUuid: (input) => Number(validateUuid(input)) === 1,
     validateIpv4: (input) => Number(validateIpv4(input)) === 1,
     validateIpv6: (input) => Number(validateIpv6(input)) === 1,
+    // Byte-input validators: `(ptr,len)` — zero transcode (no CString decode
+    // + engine re-encode like the cstring-ARG string forms above).
+    validateEmailBytes: (input) => Number(oneArg(validateEmailBytes, input)) === 1,
+    validateUuidBytes: (input) => Number(oneArg(validateUuidBytes, input)) === 1,
+    validateIpv4Bytes: (input) => Number(oneArg(validateIpv4Bytes, input)) === 1,
+    validateIpv6Bytes: (input) => Number(oneArg(validateIpv6Bytes, input)) === 1,
+    hexValidateBatchInto(input, width, output) {
+      // Batch fixed-width hex validation: NEWLINE-separated lines in; one
+      // verdict byte (1/0) per line out. Needed-size convention: `0` = bad
+      // width / null pointers (real error → throw); `> output.length` = the
+      // exact required size (caller grows once and retries). Width is
+      // validated here so an empty input can't mask it.
+      if (width === 0 || width > 4096) {
+        throw new Error('hex validate batch: width must be 1..=4096')
+      }
+      const w = Number(hexBatchRaw(input, lenOrView(input), width >>> 0, output, lenOrView(output)))
+      return w
+    },
+    regexEscapeInto(input, output) {
+      const w = Number(regexEscapeRaw(input, lenOrView(input), output, lenOrView(output)))
+      if (w === 0) {
+        throw new Error('regex escape: output buffer too small')
+      }
+      return w
+    },
+    // Zero-copy text path: cstring ARG in (engine-transcoded), cstring return
+    // out (engine-cloned) — the JS side does zero encode AND zero decode.
+    regexEscapeStr: (input) => regexEscapeStrRaw(input),
+    hexValidateBatchStr(ids, width, output) {
+      if (width === 0 || width > 4096) {
+        throw new Error('hex validate batch: width must be 1..=4096')
+      }
+      const w = Number(hexBatchStrRaw(ids, width >>> 0, output, lenOrView(output)))
+      return w
+    },
     jsonSumIds: (input) => {
       // Packed [u8 ok][i64 sum LE] output (9 B): ok=1 → valid array (the sum
       // may be 0); ok=0 → invalid input. Bytes written: 9/1/0 (0 = real error).
@@ -202,19 +247,19 @@ export function buildCodecs(
       Number(passwordVerifyBcrypt(password, lenOrView(password), phc)) === 1,
 
     hexDecode(input) {
-      const out = new Uint8Array(Math.floor(input.length / 2))
+      const out = allocOut(Math.floor(input.length / 2))
       const w = hexDecodeInto(input, out)
       return out.subarray(0, w)
     },
     hexDecodeInto,
     urlDecode(input) {
-      const out = new Uint8Array(input.length)
+      const out = allocOut(input.length)
       const w = urlDecodeInto(input, out)
       return out.subarray(0, w)
     },
     urlDecodeInto,
     base64Decode(input, urlSafe, padding) {
-      const out = new Uint8Array(Math.ceil((input.length * 3) / 4))
+      const out = allocOut(Math.ceil((input.length * 3) / 4))
       const w = base64DecodeInto(input, out, urlSafe, padding)
       return out.subarray(0, w)
     },
@@ -398,7 +443,7 @@ export function buildCodecs(
     },
     passwordHashBcrypt(password, cost) {
       // `$2b$CC$` + 22 salt chars + 31 hash chars = 60 chars.
-      const out = new Uint8Array(64)
+      const out = allocOut(64)
       const w = Number(passwordHashBcrypt(password, lenOrView(password), cost, out, lenOrView(out)))
       if (w === 0) {
         throw new Error('password hash bcrypt: output buffer too small')
@@ -409,7 +454,7 @@ export function buildCodecs(
       // Rust clamps dkLen to [1, 1MiB] (PBKDF2_MIN_LEN/MAX_LEN) AFTER sizing its
       // own buffer — so pre-clamp here so dkLen 0 still yields a 1-byte result.
       const dk = Math.min(Math.max(dkLen, 1), 1024 * 1024)
-      const out = new Uint8Array(dk)
+      const out = allocOut(dk)
       const w = Number(
         pbkdf2(
           password,
@@ -429,7 +474,7 @@ export function buildCodecs(
     },
     aeadEncrypt(key, nonce, plaintext, algorithm = 0) {
       // ciphertext + 16-byte auth tag.
-      const out = new Uint8Array(plaintext.length + 16)
+      const out = allocOut(plaintext.length + 16)
       const w = Number(
         aeadEncrypt(
           key,
@@ -472,7 +517,7 @@ export function buildCodecs(
       return w
     },
     aeadDecrypt(key, nonce, ciphertext, algorithm = 0) {
-      const out = new Uint8Array(ciphertext.length)
+      const out = allocOut(ciphertext.length)
       const w = Number(
         aeadDecrypt(
           key,
@@ -534,6 +579,17 @@ export function selfTestCodecs(b: BunFFI): boolean {
   ) {
     return false
   }
+  // Byte-input validator siblings: `(ptr,len)` parity with the string forms.
+  if (
+    !b.validateEmailBytes(enc.encode('a@b.com')) ||
+    !b.validateUuidBytes(enc.encode('550e8400-e29b-41d4-a716-446655440000')) ||
+    !b.validateIpv4Bytes(enc.encode('192.168.0.1')) ||
+    !b.validateIpv6Bytes(enc.encode('2001:db8::1')) ||
+    b.validateEmailBytes(enc.encode('not-an-email')) ||
+    b.validateIpv6Bytes(enc.encode('999'))
+  ) {
+    return false
+  }
   // Packed `[u8 ok][i64 sum LE]` ABI: legit zero-sum is ok, invalid input throws.
   if (b.jsonSumIds(enc.encode(`[{"id":1},{"id":2}]`)) !== 3n) return false
   if (b.jsonSumIds(enc.encode(`[{"id":0},{"id":0}]`)) !== 0n) return false
@@ -545,6 +601,46 @@ export function selfTestCodecs(b: BunFFI): boolean {
   }
   if (!sumInvalidThrew) return false
 
+  // Batch fixed-width hex validation (needed-size convention + verdicts).
+  {
+    const ids = enc.encode('507f1f77bcf86cd799439011\nzz\n507F1F77BCF86CD799439012')
+    const tiny = new Uint8Array(2)
+    const needed = b.hexValidateBatchInto(ids, 24, tiny)
+    if (needed !== 3) return false // exact required size on a too-small buffer
+    const out = new Uint8Array(needed)
+    if (b.hexValidateBatchInto(ids, 24, out) !== 3) return false
+    if (out[0] !== 1 || out[1] !== 0 || out[2] !== 1) return false
+    let widthThrew = false
+    try {
+      b.hexValidateBatchInto(ids, 0, new Uint8Array(3))
+    } catch {
+      widthThrew = true
+    }
+    if (!widthThrew) return false
+  }
+
+  // RegExp escaping: metachars get backslashes; plain text is untouched.
+  {
+    const out = new Uint8Array(64)
+    const w = b.regexEscapeInto(enc.encode('a.c(x)'), out)
+    if (w !== 9 || dec.decode(out.subarray(0, w)) !== 'a\\.c\\(x\\)') return false
+    const plain = new Uint8Array(16)
+    const wp = b.regexEscapeInto(enc.encode('hello'), plain)
+    if (wp !== 5 || dec.decode(plain.subarray(0, wp)) !== 'hello') return false
+    // too-small buffer reports the exact required size
+    if (b.regexEscapeInto(enc.encode('a.b'), new Uint8Array(2)) !== 4) return false
+    // zero-copy str sibling must produce the identical escaped string
+    if (b.regexEscapeStr('a.c(x)') !== 'a\\.c\\(x\\)') return false
+    if (b.regexEscapeStr('plain text') !== 'plain text') return false
+  }
+
+  // String-input batch hex validation (cstring ARG sibling).
+  {
+    const out = new Uint8Array(8)
+    const w = b.hexValidateBatchStr('507f1f77bcf86cd799439011\nzz', 24, out)
+    if (w !== 2 || out[0] !== 1 || out[1] !== 0) return false
+  }
+
   // HMAC RFC 4231 test case 1 (0x0b × 20 key, "Hi There" data).
   const hmacKey = new Uint8Array(20).fill(0x0b)
   const hmacData = enc.encode('Hi There')

package/src/native/ffi/build/compress.ts

@@ -29,7 +29,7 @@ export function buildCompress(
   sym: Record<string, (...a: unknown[]) => unknown>,
   ctx: BuildCtx,
 ): Partial<BunFFI> {
-  const { lenOrView } = ctx
+  const { lenOrView, scratchFor } = ctx
 
   const gzipCompress = sym.castrum_gzip_compress as Raw5
   const gzipDecompress = sym.castrum_gzip_decompress as Raw5
@@ -40,15 +40,19 @@ export function buildCompress(
 
   return {
     jsonPatch(doc, patch) {
-      return decodeUtf8(
-        growExact(
-          (out) =>
-            Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out))),
-          Math.min(Math.max(doc.length, patch.length) + 16, 64 * 1024),
-          MAX_JSON_PATCH_OUTPUT,
-          'json patch: output buffer too small or patch inapplicable',
-        ),
-      )
+      // Pooled scratch — the patched doc is decoded to an immutable string
+      // synchronously (same call-scope contract as the cstring returns), so
+      // the bytes never need a fresh buffer. One exact retry on miss.
+      let out = scratchFor(Math.min(Math.max(doc.length, patch.length) + 16, 64 * 1024))
+      let w = Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out)))
+      if (w > out.length && w <= MAX_JSON_PATCH_OUTPUT) {
+        out = new Uint8Array(w)
+        w = Number(jsonPatch(doc, lenOrView(doc), patch, lenOrView(patch), out, lenOrView(out)))
+      }
+      if (w === 0 || w > out.length) {
+        throw new Error('json patch: output buffer too small or patch inapplicable')
+      }
+      return decodeUtf8(out.subarray(0, w))
     },
     gzipCompress(data, level = 6) {
       // The C ABI streams the compressed output directly into `out` (no internal

package/src/native/ffi/build/instances.ts

@@ -8,7 +8,7 @@
 
 import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { EMPTY_VIEW } from '../constants'
-import type { BunFFI, Raw2, Raw3, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
+import type { BunFFI, Raw2, Raw3, Raw4, Raw5, Raw6, Raw7, Raw8, Raw12, RawCStr } from '../types'
 import type { BuildCtx } from './util'
 import { cstr, growExact, unpackRateCheck } from './util'
 
@@ -25,8 +25,9 @@ export function buildInstances(
   const conditionalIsNotModifiedRaw = sym.castrum_conditional_is_not_modified as Raw6
   const mediaTypeMatcherMatchesRaw = sym.castrum_media_type_matcher_matches as Raw3
   const acceptNegotiatorNegotiateRaw = sym.castrum_accept_negotiator_negotiate as RawCStr
-  const acceptNegotiatorNegotiateServerRaw = sym
-    .castrum_accept_negotiator_negotiate_server as (...a: unknown[]) => string | null
+  const acceptNegotiatorNegotiateServerRaw = sym.castrum_accept_negotiator_negotiate_server as (
+    ...a: unknown[]
+  ) => string | null
   const ed25519GenerateKeypairRaw = sym.castrum_ed25519_generate_keypair as Raw2
   const ed25519SignRaw = sym.castrum_ed25519_sign as Raw6
   const ed25519VerifyRaw = sym.castrum_ed25519_verify as Raw6
@@ -36,6 +37,10 @@ export function buildInstances(
   const jwtSignerVerifyRaw = sym.castrum_jwt_signer_verify as Raw6
   const templateRenderRaw = sym.castrum_template_render as Raw5
   const schemaValidatorValidateRaw = sym.castrum_schema_validator_validate as Raw3
+  const queryValidateSym = sym.castrum_query_validate as (...a: unknown[]) => number | bigint
+  const cookieValidateSym = sym.castrum_cookie_validate as (...a: unknown[]) => number | bigint
+  const sessionSealSym = sym.castrum_session_seal as (...a: unknown[]) => string | null
+  const sessionOpenSym = sym.castrum_session_open as Raw4
   const rateLimiterCheckRaw = sym.castrum_rate_limiter_check as Raw5
   const rateLimiterCheckKeyRaw = sym.castrum_rate_limiter_check_key as Raw5
   const jwtSignBytes = sym.castrum_jwt_sign_bytes as RawCStr
@@ -138,6 +143,22 @@ export function buildInstances(
     schemaValidatorValidate(inner, doc) {
       return Number(schemaValidatorValidateRaw(inner, doc, lenOrView(doc))) === 1
     },
+    queryValidate(inner, qs) {
+      // `qs` is a cstring ARG — engine-transcoded (zero JS encode).
+      return Number(queryValidateSym(inner, qs)) === 1
+    },
+    cookieValidate(inner, header) {
+      return Number(cookieValidateSym(inner, header)) === 1
+    },
+    sessionSeal(id, dataJson, expSecs, secret) {
+      // exp is an i64 C arg → BigInt.
+      return sessionSealSym(id, dataJson, BigInt(expSecs), secret)
+    },
+    sessionOpen(token, secret, output) {
+      // Needed-size convention; 0 = bad signature / malformed.
+      const w = Number(sessionOpenSym(token, secret, output, lenOrView(output)))
+      return w
+    },
     rateLimiterCheck(inner, key, nowMs) {
       // Packed [u8 allowed][u32 remaining LE][i64 reset_ms LE] (13 bytes).
       // Reused scratch + cached DataView (no per-call allocs). `key` is a
@@ -583,6 +604,22 @@ export function selfTestInstances(b: BunFFI): boolean {
   if (!urlBuilderThrew) {
     return false
   }
+  // Wire-validate: null inner (0) → false (ABI exercise); real parity lives
+  // in ffi.test.ts with a live compiled instance.
+  if (b.queryValidate(0, 'route=/a') !== false) return false
+  if (b.cookieValidate(0, 'route=/a') !== false) return false
+
+  // Session seal/open round trip through the C ABI.
+  {
+    const tok = b.sessionSeal('sess-9', '{"n":1}', 1234567, 'sekrit')
+    if (tok === null || !tok.includes('.') || !tok.startsWith('{"id":"sess-9"')) return false
+    const out = new Uint8Array(256)
+    const w = b.sessionOpen(tok, 'sekrit', out)
+    if (w <= 13 || out[0] !== 1) return false
+    // bad signature → 0
+    if (b.sessionOpen(tok, 'wrong', out) !== 0) return false
+  }
+
   // rateLimiterCheckKey: null (0) handle → throw (ABI exercise).
   let rlKeyThrew = false
   try {

package/src/native/ffi/build/metrics.ts

@@ -0,0 +1,224 @@
+// src/native/ffi/build/metrics.ts — metrics-registry BunFFI methods.
+//
+// Wraps the `castrum_metrics_*` caller-owned-handle surface (route-stack
+// ownership model): create returns a native `Box<MetricsRegistry>` handle,
+// declare fns cross name/label-keys as cstring ARGS and return the u32 series
+// id, and record/set/render take packed byte slices. Receives the raw dlopen'd
+// symbols from `build()`.
+
+import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
+import type { BunFFI, Raw0, Raw3, Raw4, Raw5 } from '../types'
+import type { BuildCtx } from './util'
+
+/**
+ * Sentinel returned by the declare fns (`u32::MAX`) on invalid input — fits
+ * f64 exactly and can never collide with a real dense family id.
+ */
+export const METRICS_DECLARE_ERR = 0xffffffff
+
+/** Empty label-values view (zero-label families). */
+const EMPTY = new Uint8Array(0)
+
+/**
+ * Build the metrics-registry methods of the BunFFI surface.
+ */
+export function buildMetrics(
+  sym: Record<string, (...a: unknown[]) => unknown>,
+  ctx: BuildCtx,
+): Partial<BunFFI> {
+  const { lenOrView } = ctx
+  const metricsCreateRaw = sym.castrum_metrics_create as Raw0
+  const metricsCounterRaw = sym.castrum_metrics_counter as Raw3
+  const metricsGaugeRaw = sym.castrum_metrics_gauge as Raw3
+  const metricsHistogramRaw = sym.castrum_metrics_histogram as Raw4
+  const metricsRecordRaw = sym.castrum_metrics_record as Raw5
+  const metricsGaugeSetRaw = sym.castrum_metrics_gauge_set as Raw5
+  // Zero-encode siblings: joined values cross as a cstring ARG.
+  const metricsRecordStrRaw = sym.castrum_metrics_record_str as (...a: unknown[]) => number | bigint
+  const metricsGaugeSetStrRaw = sym.castrum_metrics_gauge_set_str as (
+    ...a: unknown[]
+  ) => number | bigint
+  const metricsRenderRaw = sym.castrum_metrics_render as Raw3
+  const metricsSnapshotRaw = sym.castrum_metrics_snapshot as Raw3
+  const metricsRecordBatchRaw = sym.castrum_metrics_record_batch as Raw3
+  const metricsDestroyRaw = sym.castrum_metrics_destroy as (h: unknown) => void
+
+  /** Declare helper: maps the C sentinel to a throw (fail fast at declare). */
+  const declareOrThrow = (id: number | bigint, what: string): number => {
+    const n = Number(id)
+    if (n === METRICS_DECLARE_ERR) {
+      throw new Error(`metrics: failed to declare ${what} (invalid name/labels/buckets)`)
+    }
+    return n
+  }
+
+  return {
+    metricsCreate() {
+      const h = Number(metricsCreateRaw())
+      if (h === 0) throw new Error('metrics: registry allocation failed')
+      return h
+    },
+    metricsCounter(handle, name, labelKeys) {
+      return declareOrThrow(metricsCounterRaw(handle, name, labelKeys), `counter "${name}"`)
+    },
+    metricsGauge(handle, name, labelKeys) {
+      return declareOrThrow(metricsGaugeRaw(handle, name, labelKeys), `gauge "${name}"`)
+    },
+    metricsHistogram(handle, name, labelKeys, bucketsCsv) {
+      return declareOrThrow(
+        metricsHistogramRaw(handle, name, labelKeys, bucketsCsv),
+        `histogram "${name}"`,
+      )
+    },
+    metricsRecord(handle, series, values, amount) {
+      // Packed `\x1f`-separated values cross as `(ptr,len)`; u8 verdict.
+      return Number(metricsRecordRaw(handle, series, values, lenOrView(values), amount)) === 1
+    },
+    metricsGaugeSet(handle, series, values, value) {
+      return Number(metricsGaugeSetRaw(handle, series, values, lenOrView(values), value)) === 1
+    },
+    metricsRecordStr(handle, series, values, amount) {
+      // `values` is the JOINED `\x1f` string — engine-transcoded (zero encode).
+      return Number(metricsRecordStrRaw(handle, series, values, amount)) === 1
+    },
+    metricsGaugeSetStr(handle, series, values, value) {
+      return Number(metricsGaugeSetStrRaw(handle, series, values, value)) === 1
+    },
+    metricsRender(handle, output) {
+      // Needed-size convention (routeRun parity): `0` = real error → throw;
+      // `> output.length` = the EXACT required size (caller grows once and
+      // retries — never a doubling re-run loop).
+      const w = Number(metricsRenderRaw(handle, output, lenOrView(output)))
+      if (w === 0) throw new Error('metrics render: registry handle invalid or render failed')
+      return w
+    },
+    metricsSnapshot(handle, output) {
+      // Needed-size convention (routeRun parity): 0 throws; > length = exact.
+      const w = Number(metricsSnapshotRaw(handle, output, lenOrView(output)))
+      if (w === 0) throw new Error('metrics snapshot: registry handle invalid')
+      return w
+    },
+    metricsRecordBatch(handle, packed) {
+      return Number(metricsRecordBatchRaw(handle, packed, lenOrView(packed))) === 1
+    },
+    metricsDestroy(handle) {
+      metricsDestroyRaw(handle)
+    },
+  }
+}
+
+/**
+ * Bind-time self-test for the metrics surface (unique `ct.selftest.*` names).
+ * Exercises every symbol's ABI at bind time; `false` disables the ffi layer
+ * and forces the napi fallback.
+ */
+export function selfTestMetrics(b: BunFFI): boolean {
+  let handle = 0
+  try {
+    handle = b.metricsCreate()
+    if (handle === 0) return false
+
+    const counter = b.metricsCounter(handle, 'ct_selftest_hits', 'route\u001fstatus')
+    if (!Number.isInteger(counter) || counter < 0 || counter === METRICS_DECLARE_ERR) {
+      console.error('FAIL: declare')
+      return false
+    }
+    if (!b.metricsRecord(handle, counter, encodeUtf8('/a\u001f200'), 2)) {
+      console.error('FAIL: record1')
+      return false
+    }
+    if (!b.metricsRecord(handle, counter, encodeUtf8('/a\u001f200'), 1)) {
+      console.error('FAIL: record2')
+      return false
+    }
+    if (!b.metricsRecordStr(handle, counter, '/b\u001f200', 2)) {
+      console.error('FAIL: recordStr')
+      return false
+    }
+
+    console.error('CK: counter')
+    const gauge = b.metricsGauge(handle, 'ct_selftest_depth', 'q')
+    if (gauge === METRICS_DECLARE_ERR) return false
+    if (!b.metricsGaugeSet(handle, gauge, encodeUtf8('jobs'), 4)) return false
+    if (!b.metricsGaugeSetStr(handle, gauge, 'io', 6)) return false
+
+    console.error('CK: gauge')
+    const hist = b.metricsHistogram(handle, 'ct_selftest_latency', '', '0.1,0.5')
+    if (hist === METRICS_DECLARE_ERR) return false
+    if (!b.metricsRecord(handle, hist, EMPTY, 0.25)) return false
+    if (b.metricsRecord(handle, hist, EMPTY, -1)) return false // negatives rejected
+
+    console.error('CK: hist')
+    // Arity mismatch must fail safely.
+    if (b.metricsRecord(handle, counter, encodeUtf8('/a'), 1)) return false
+
+    console.error('CK: arity')
+    // Render: probe with a small buffer → exact required size; then render.
+    const probe = new Uint8Array(16)
+    const needed = b.metricsRender(handle, probe)
+    if (needed <= probe.length) return false
+    const out = new Uint8Array(needed)
+    const written = b.metricsRender(handle, out)
+    if (written !== needed) return false
+    const text = decodeUtf8(out.subarray(0, written))
+    if (
+      !text.includes('ct_selftest_hits{route="/a",status="200"} 3\n') ||
+      !text.includes('ct_selftest_hits{route="/b",status="200"} 2\n') ||
+      !text.includes('ct_selftest_depth{q="jobs"} 4\n') ||
+      !text.includes('ct_selftest_depth{q="io"} 6\n') ||
+      !text.includes('ct_selftest_latency_bucket{le="0.5"} 1\n') ||
+      !text.includes('ct_selftest_latency_count 1\n')
+    ) {
+      return false
+    }
+
+    console.error('CK: render')
+    // Snapshot: packed dump starts with version=1 + familyCount>=3.
+    {
+      const probe2 = new Uint8Array(16)
+      const need = b.metricsSnapshot(handle, probe2)
+      if (need <= probe2.length) return false
+      const snap = new Uint8Array(need)
+      if (b.metricsSnapshot(handle, snap) !== need) return false
+      const sv = new DataView(snap.buffer)
+      if (sv.getUint32(0, true) !== 1) return false
+      if (sv.getUint32(4, true) < 3) return false
+    }
+
+    console.error('CK: snapshot')
+    // Batch: two entries in ONE crossing.
+    {
+      const c2 = b.metricsCounter(handle, 'ct_selftest_batch', 'k')
+      const buf = new Uint8Array(64)
+      const dv = new DataView(buf.buffer)
+      dv.setUint32(0, 1, true)
+      dv.setUint32(4, c2, true)
+      dv.setUint32(8, 1, true)
+      buf[12] = 'v'.charCodeAt(0)
+      dv.setFloat64(13, 4, true)
+      if (!b.metricsRecordBatch(handle, buf.subarray(0, 21))) return false
+      const probe3 = new Uint8Array(16)
+      const need3 = b.metricsRender(handle, probe3)
+      const out3 = new Uint8Array(need3)
+      b.metricsRender(handle, out3)
+      if (!decodeUtf8(out3.subarray(0, need3)).includes('ct_selftest_batch{k="v"} 4')) {
+        return false
+      }
+    }
+
+    console.error('CK: batch')
+    // A null handle must throw on declare (never dereference freed state).
+    try {
+      b.metricsCounter(0, 'ct_selftest_x', '')
+      return false
+    } catch {
+      // expected
+    }
+    return true
+  } catch (err) {
+    console.error('METRICS SELFTEST THROW:', err)
+    return false
+  } finally {
+    b.metricsDestroy(handle)
+  }
+}