castrum 0.9.3 → 0.9.4

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

@@ -11,12 +11,29 @@ import { decodeUtf8, encodeUtf8 } from '../../../shared/codec'
 import { EMPTY_VIEW, SELFTEST_HEX } from '../constants'
 import type { BunFFI, Raw3, Raw4, Raw6, Raw7, Raw10 } from '../types'
 import type { BuildCtx } from './util'
-import { flag, growExact } from './util'
+import { allocOut, flag, growExact } from './util'
 
 /**
  * Build the parser/wire-format methods of the BunFFI surface. `ctx` is
  * destructured so the method bodies read exactly as the original `build()`.
  */
+
+// ── SSE event/id encode memo ────────────────────────────────────────────────
+// SSE streams repeat the same event NAME constantly ('message'/'update') and
+// often repeat ids; re-encoding them per event is pure waste (~60ns each).
+// One memo slot each: a `===` hit returns the cached bytes, a miss re-encodes.
+// Per-Worker module state (single-threaded event loop), same safety model as
+// the pooled scratches in BuildCtx.
+const sseMemoEvent = { str: null as string | null, bytes: EMPTY_VIEW }
+const sseMemoId = { str: null as string | null, bytes: EMPTY_VIEW }
+function sseMemoEncode(slot: { str: string | null; bytes: Uint8Array }, s: string): Uint8Array {
+  if (s === slot.str) return slot.bytes
+  const bytes = encodeUtf8(s)
+  slot.str = s
+  slot.bytes = bytes
+  return bytes
+}
+
 export function buildParse(
   sym: Record<string, (...a: unknown[]) => unknown>,
   ctx: BuildCtx,
@@ -67,8 +84,9 @@ export function buildParse(
       return w
     },
     wsFrameEncode(opcode, payload, mask, fin) {
-      // Header (max 10) + payload + mask key (4).
-      const out = new Uint8Array(payload.length + 14)
+      // Header (max 10) + payload + mask key (4). allocOut skips the zeroing
+      // (the native write fills [0,w) and only that slice escapes).
+      const out = allocOut(payload.length + 14)
       const w = Number(
         wsFrameEncode(
           opcode,
@@ -182,15 +200,24 @@ export function buildParse(
     parseMediaType(input) {
       // Packed verdict: [u32 mediaTypeLen][mediaType][u32 charsetLen
       // (0xFFFFFFFF = none)][charset][u32 boundaryLen][boundary]
-      // [u32 paramCount]{[u32 keyLen][key][u32 valLen][val]}. 0 = invalid media
-      // type (real error → growExact throws); w > output.length = exact needed
-      // size (one exact retry).
-      return growExact(
-        (out) => Number(parseMediaTypeSym(input, lenOrView(input), out, lenOrView(out))),
-        Math.min(input.length + 64, 64 * 1024),
-        1024 * 1024,
-        'media type parse: invalid media type or output buffer too small',
-      )
+      // [u32 paramCount]{[u32 keyLen][key][u32 valLen][val]}.
+      // POOLED SCRATCH: the only consumer (the scalar `unpackMediaType`)
+      // decodes the verdict synchronously into a JS object before the next
+      // call, so the packed bytes never need to outlive this call — no
+      // growExact fresh-buffer per request. 0 = invalid media type (throw).
+      // 2x + 128 covers the worst-case packed expansion (every byte becomes a
+      // param key/value length prefix); a still-too-small write falls back to
+      // ONE exact-size buffer (needed-size convention).
+      let out = scratchFor(input.length * 2 + 128)
+      let w = Number(parseMediaTypeSym(input, lenOrView(input), out, lenOrView(out)))
+      if (w > out.length) {
+        out = new Uint8Array(w)
+        w = Number(parseMediaTypeSym(input, lenOrView(input), out, lenOrView(out)))
+      }
+      if (w === 0 || w > out.length) {
+        throw new Error('media type parse: invalid media type or output buffer too small')
+      }
+      return out.subarray(0, w)
     },
     parseHttpDate(input) {
       // Packed [u8 ok][i64 secs LE] (9 B) / 1 B (ok=0). A too-small buffer is
@@ -207,13 +234,18 @@ export function buildParse(
     },
     parseAcceptEncoding(input) {
       // Packed: [u32 count]{[u32 encLen][enc][f32 q][u32 order]} (empty header →
-      // count 0, 4 bytes). 0 = too small (real error → growExact throws).
-      return growExact(
-        (out) => Number(parseAcceptEncodingSym(input, lenOrView(input), out, lenOrView(out))),
-        Math.min(input.length + 64, 64 * 1024),
-        1024 * 1024,
-        'accept encoding parse: output buffer too small',
-      )
+      // count 0, 4 bytes). POOLED SCRATCH: consumed synchronously by the scalar
+      // `unpackAcceptEncoding` — never escapes as raw bytes. 0 = too small.
+      let out = scratchFor(input.length * 2 + 128)
+      let w = Number(parseAcceptEncodingSym(input, lenOrView(input), out, lenOrView(out)))
+      if (w > out.length) {
+        out = new Uint8Array(w)
+        w = Number(parseAcceptEncodingSym(input, lenOrView(input), out, lenOrView(out)))
+      }
+      if (w === 0 || w > out.length) {
+        throw new Error('accept encoding parse: output buffer too small')
+      }
+      return out.subarray(0, w)
     },
     urlEncodeQuery(input) {
       // Packed pairs `[u32 count]{[u32 keyLen][key][u32 valLen][val]}` (the JS
@@ -255,8 +287,12 @@ export function buildParse(
       // non-null (flag bits 1/2/4 = present) so a present-but-empty string is
       // distinct from absent (napi Option parity). growExact with the needed-size
       // convention; `data.length + 64` covers the common single-line case.
-      const ev = event === null ? EMPTY_VIEW : encodeUtf8(event)
-      const idv = id === null ? EMPTY_VIEW : encodeUtf8(id)
+      // NOTE (2026-08-24): cstring-ARG variants were once blamed for JIT
+      // crashes here — docs/FFI_BUN_GUIDE.md §14 traced every report to
+      // dev-loop ABI desync, not bun:ffi. The memo captures the win without
+      // an ABI change anyway.
+      const ev = event === null ? EMPTY_VIEW : sseMemoEncode(sseMemoEvent, event)
+      const idv = id === null ? EMPTY_VIEW : sseMemoEncode(sseMemoId, id)
       const flags = (event === null ? 0 : 1) | (id === null ? 0 : 2) | (retry === null ? 0 : 4)
       return growExact(
         (out) =>
@@ -283,8 +319,8 @@ export function buildParse(
       // Pooled sibling — caller-owned output buffer (sized ≥ `data.length + 64`
       // for the common single-line case). Needed-size convention: w > output.length
       // = exact required size → throw; w === 0 = real error (invalid UTF-8).
-      const ev = event === null ? EMPTY_VIEW : encodeUtf8(event)
-      const idv = id === null ? EMPTY_VIEW : encodeUtf8(id)
+      const ev = event === null ? EMPTY_VIEW : sseMemoEncode(sseMemoEvent, event)
+      const idv = id === null ? EMPTY_VIEW : sseMemoEncode(sseMemoId, id)
       const flags = (event === null ? 0 : 1) | (id === null ? 0 : 2) | (retry === null ? 0 : 4)
       const w = Number(
         sseEncodeIntoRaw(

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

@@ -42,6 +42,19 @@ export interface BuildCtx {
 /** Coerce an optional boolean to the C `u8` flag (1/0). */
 export const flag = (v?: boolean): number => (v ? 1 : 0)
 
+/**
+ * Output-buffer allocation for the FFI wrappers. The native write fills
+ * `[0, w)` and only `subarray(0, w)` escapes, so zero-initialization is pure
+ * waste: `Buffer.allocUnsafe` skips it (measured ~2x at 4 KB, ~3.4x at 16 KB
+ * on Bun 1.4; small sizes stay on the plain constructor where it is faster).
+ */
+export function allocOut(n: number): Uint8Array {
+  if (n >= 512 && typeof Buffer !== 'undefined' && typeof Buffer.allocUnsafe === 'function') {
+    return Buffer.allocUnsafe(n)
+  }
+  return new Uint8Array(n)
+}
+
 /**
  * Write with the C ABI's "needed" convention. The C side returns the EXACT
  * total bytes the result requires: `0` = real error (throw immediately — no
@@ -59,7 +72,7 @@ export function growExact(
 ): Uint8Array {
   let cap = Math.min(Math.max(initial, 16), max)
   for (;;) {
-    const out = new Uint8Array(cap)
+    const out = allocOut(cap)
     const w = Number(write(out))
     if (w === 0) throw new Error(error)
     if (w <= out.length) return out.subarray(0, w)

package/src/native/ffi/build.ts

@@ -14,6 +14,7 @@
 import { buildCodecs } from './build/codecs'
 import { buildCompress } from './build/compress'
 import { buildInstances } from './build/instances'
+import { buildMetrics } from './build/metrics'
 import { buildParse } from './build/parse'
 import type { BuildCtx } from './build/util'
 import type { BunFFI } from './types'
@@ -90,5 +91,6 @@ export function build(
     ...buildCompress(sym, ctx),
     ...buildParse(sym, ctx),
     ...buildInstances(sym, ctx),
+    ...buildMetrics(sym, ctx),
   } as BunFFI
 }

package/src/native/ffi/selftest.ts

@@ -7,16 +7,23 @@
 // the safety net. New C-ABI symbols MUST be added to the self-test for their
 // domain: each check lives in the same `ffi/build/` file where the method is
 // bound (`selfTestCodecs` / `selfTestCompress` / `selfTestParse` /
-// `selfTestInstances`), and this entry point ANDs them together so any single
-// failure disables the whole layer.
+// `selfTestInstances` / `selfTestMetrics`), and this entry point ANDs them
+// together so any single failure disables the whole layer.
 
 import { selfTestCodecs } from './build/codecs'
 import { selfTestCompress } from './build/compress'
 import { selfTestInstances } from './build/instances'
+import { selfTestMetrics } from './build/metrics'
 import { selfTestParse } from './build/parse'
 import type { BunFFI } from './types'
 
 /** Verify every bound function against known-good results; false disables ffi. */
 export function selfTest(b: BunFFI): boolean {
-  return selfTestCodecs(b) && selfTestCompress(b) && selfTestParse(b) && selfTestInstances(b)
+  return (
+    selfTestCodecs(b) &&
+    selfTestCompress(b) &&
+    selfTestParse(b) &&
+    selfTestInstances(b) &&
+    selfTestMetrics(b)
+  )
 }

package/src/native/ffi/types.ts

@@ -29,14 +29,23 @@ export interface BunFFI {
   /** RFC 3986 percent-encode into `output`; returns bytes written. */
   urlEncodeInto(input: Uint8Array, output: Uint8Array): number
 
-  // ── Validators (u8 → boolean) — `cstring` ARG ────────────────────
-  // The input crosses as a `cstring` ARG: the engine transcodes the JS string
+  // ── Validators (u8 → boolean) ─────────────────────────────────────
+  // String forms cross as a `cstring` ARG: the engine transcodes the JS string
   // to a call-scoped NUL-terminated UTF-8 buffer in-engine, so the JS side does
-  // ZERO `encoder.encode` work and Rust borrows via `CStr::from_ptr`.
+  // ZERO encode work and Rust borrows via `CStr::from_ptr`. Byte forms are the
+  // `(ptr,len)` siblings — zero transcode when the caller already holds bytes.
   validateEmail(input: string): boolean
   validateUuid(input: string): boolean
   validateIpv4(input: string): boolean
   validateIpv6(input: string): boolean
+  /** Byte-input sibling of {@link validateEmail} (`(ptr,len)` — no decode). */
+  validateEmailBytes(input: Uint8Array): boolean
+  /** Byte-input sibling of {@link validateUuid} (`(ptr,len)` — no decode). */
+  validateUuidBytes(input: Uint8Array): boolean
+  /** Byte-input sibling of {@link validateIpv4} (`(ptr,len)` — no decode). */
+  validateIpv4Bytes(input: Uint8Array): boolean
+  /** Byte-input sibling of {@link validateIpv6} (`(ptr,len)` — no decode). */
+  validateIpv6Bytes(input: Uint8Array): boolean
   /** Sum of `id` fields across a JSON array → bigint (throws on non-array input). */
   jsonSumIds(input: Uint8Array): bigint
 
@@ -114,11 +123,7 @@ export interface BunFFI {
     nowSeconds: number,
   ): string | null
   /** EdDSA (Ed25519) JWT verify → claims JSON string; `null` = invalid. */
-  jwtEdDSAVerify(
-    token: Uint8Array,
-    publicKey: Uint8Array,
-    nowSeconds: number,
-  ): string | null
+  jwtEdDSAVerify(token: Uint8Array, publicKey: Uint8Array, nowSeconds: number): string | null
   /** Compiled `TemplateRenderer` → UTF-8 bytes from a pre-serialized JSON
    * context (opaque `inner` handle); throws on invalid context / render error. */
   templateRender(inner: number, contextJson: Uint8Array): Uint8Array
@@ -308,7 +313,10 @@ export interface BunFFI {
   /**
    * Encode one SSE event → bytes (fresh buffer). event/id null = line omitted
    * (a present-but-empty string emits the line, matching napi `Option`).
-   * FFI sibling of the napi `sse_encode_event` — kills the napi crossing.
+   * NOTE: event/id stay `(ptr,len)` byte args — a cstring-ARG conversion was
+   * attempted and reverted (2026-08-23); see docs/FFI_BUN_GUIDE.md §14 before
+   * touching this signature.
+   * FFI sibling of the napi `sse_encode_event`.
    */
   sseEncodeEvent(
     event: string | null,
@@ -388,6 +396,98 @@ export interface BunFFI {
   routeRun(handle: number, frame: Uint8Array, output: Uint8Array): number
   /** Destroy a compiled route handle (frees the native `Box<NativeRoute>`). */
   routeDestroy(handle: number): void
+
+  // ── Metrics registry (`castrum_metrics_*`) ─────────────────────────
+  /** Create an empty metrics registry → a caller-owned opaque handle. */
+  metricsCreate(): number
+  /**
+   * Declare a counter family → its `u32` series id (`0xFFFFFFFF` = error).
+   * `name` and `labelKeys` are `cstring` ARGs; label keys are
+   * `\u001f`-separated (empty string = no labels).
+   */
+  metricsCounter(handle: number, name: string, labelKeys: string): number
+  /** Declare a gauge family → its series id. Same ABI as {@link metricsCounter}. */
+  metricsGauge(handle: number, name: string, labelKeys: string): number
+  /**
+   * Declare a histogram family → its series id. `bucketsCsv` is a
+   * comma-separated finite positive list (empty string = default buckets).
+   */
+  metricsHistogram(handle: number, name: string, labelKeys: string, bucketsCsv: string): number
+  /**
+   * Counter/gauge `+= amount`, or histogram observe `amount`. `values` is the
+   * packed `\u001f`-separated label values. Returns true on success.
+   */
+  metricsRecord(handle: number, series: number, values: Uint8Array, amount: number): boolean
+  /** Gauge assignment (`= value`). Returns true on success. */
+  metricsGaugeSet(handle: number, series: number, values: Uint8Array, value: number): boolean
+  /**
+   * Zero-encode sibling of {@link metricsRecord}: `values` is the JOINED
+   * `\u001f`-separated JS string — the engine transcodes it in-engine.
+   */
+  metricsRecordStr(handle: number, series: number, values: string, amount: number): boolean
+  /** Zero-encode sibling of {@link metricsGaugeSet} (joined string values). */
+  metricsGaugeSetStr(handle: number, series: number, values: string, value: number): boolean
+  /**
+   * Render the Prometheus text format into `output`; returns bytes written
+   * (`0` = null handle / error; `> output.length` = exact required size).
+   */
+  metricsRender(handle: number, output: Uint8Array): number
+  /**
+   * Dump the packed v1 series snapshot into `output`; returns bytes written
+   * (`0` = null handle / error; `> output.length` = exact required size).
+   */
+  metricsSnapshot(handle: number, output: Uint8Array): number
+  /** Destroy a registry handle (frees the native `Box<MetricsRegistry>`). */
+  metricsDestroy(handle: number): void
+  /**
+   * Record a BATCH of events in one crossing. Packed layout:
+   * `[u32 n]{[u32 series][u32 valsLen][vals][f64 amount]}`; returns true when
+   * all entries applied.
+   */
+  metricsRecordBatch(handle: number, packed: Uint8Array): boolean
+  /**
+   * Fused wire-level validation: RAW query string → JSON → draft-07 validate
+   * against the compiled schema (`inner` from `SchemaValidator.innerPtr()`).
+   */
+  queryValidate(inner: number, qs: string): boolean
+  /** Fused cookie-header variant of {@link queryValidate}. */
+  cookieValidate(inner: number, header: string): boolean
+  /**
+   * Seal a session envelope natively: builds
+   * `{"id":"…","data":<dataJson>,"exp":exp}` and HMAC-signs it →
+   * `payload.<hex>` token string (`null` = failure).
+   */
+  sessionSeal(id: string, dataJson: string, expSecs: number, secret: string): string | null
+  /**
+   * Open a sealed session token: verify + extract in one crossing into
+   * `output` as `[u8 ok][i64 exp][u32 idLen][id][u32 dataLen][dataJson]`.
+   * Returns bytes written (`0` = bad signature / error; `> output.length` =
+   * exact required size).
+   */
+  sessionOpen(token: string, secret: string, output: Uint8Array): number
+
+  // ── Batch fixed-width hex validation / RegExp escaping ─────────────
+  /**
+   * Validate NEWLINE-separated lines as fixed-width hex into `output`
+   * (one verdict byte per line); returns bytes written (`0` = bad width /
+   * error; `> output.length` = exact required size).
+   */
+  hexValidateBatchInto(input: Uint8Array, width: number, output: Uint8Array): number
+  /**
+   * String-input sibling of {@link hexValidateBatchInto}: the NEWLINE-
+   * separated ids cross as a `cstring` ARG (engine-transcoded — no encode).
+   */
+  hexValidateBatchStr(ids: string, width: number, output: Uint8Array): number
+  /**
+   * Escape JS-RegExp metacharacters into `output`; returns bytes written
+   * (`0` = error; `> output.length` = exact required size).
+   */
+  regexEscapeInto(input: Uint8Array, output: Uint8Array): number
+  /**
+   * Zero-copy text sibling of {@link regexEscapeInto}: cstring ARG in,
+   * cstring return out (engine-cloned — zero JS decode). `null` = failure.
+   */
+  regexEscapeStr(input: string): string | null
 }
 
 /**
@@ -411,6 +511,8 @@ export interface RateLimiterVerdict {
   resetMs: number
 }
 
+/** Raw 0-arg C-ABI symbol signature (`castrum_metrics_create`). */
+export type Raw0 = () => number | bigint
 /** Raw 2-arg C-ABI symbol signature (`(ptr,len)` pairs → scalar result). */
 export type Raw2 = (a: unknown, b: unknown) => number | bigint
 /** Raw 3-arg C-ABI symbol signature. */

package/src/native/ffi.ts

@@ -206,10 +206,17 @@ function bind(): BunFFI | null {
       castrum_url_decode: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
       // String-input validators: `cstring` ARG (the engine transcodes the JS
       // string in-engine — no JS-side encode; Rust borrows via CStr::from_ptr).
+      // The `_bytes` siblings take a `(ptr,len)` pair — zero transcode when
+      // the caller already holds bytes (a cstring arg would force a decode +
+      // engine re-encode; docs/FFI_BUN_GUIDE.md §3 shape 4).
       castrum_validate_email: { args: ['cstring'], returns: 'u8' },
       castrum_validate_uuid: { args: ['cstring'], returns: 'u8' },
       castrum_validate_ipv4: { args: ['cstring'], returns: 'u8' },
       castrum_validate_ipv6: { args: ['cstring'], returns: 'u8' },
+      castrum_validate_email_bytes: { args: inputAbi, returns: 'u8' },
+      castrum_validate_uuid_bytes: { args: inputAbi, returns: 'u8' },
+      castrum_validate_ipv4_bytes: { args: inputAbi, returns: 'u8' },
+      castrum_validate_ipv6_bytes: { args: inputAbi, returns: 'u8' },
       castrum_json_sum_ids: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
       castrum_hmac_sha256_verify: {
         args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize']),
@@ -357,6 +364,11 @@ function bind(): BunFFI | null {
       },
       castrum_http_date_into: { args: ['f64', ...abi(['ptr', 'usize'])], returns: U64_FAST },
       castrum_sse_encode_into: {
+        // event/id stay `(ptr,len)` byte args. A cstring-ARG conversion was
+        // tried (2026-08-23) and reverted: the win was unproven once the
+        // codec encode path got faster, and ABI-desync segfaults during the
+        // experiment were misread as an engine bug — see docs/FFI_BUN_GUIDE.md
+        // §14 before touching this signature.
         args: abi(['ptr', 'usize', 'ptr', 'usize', 'ptr', 'usize', 'u8', 'u32', 'ptr', 'usize']),
         returns: U64_FAST,
       },
@@ -467,9 +479,83 @@ function bind(): BunFFI | null {
         returns: U64_FAST,
       },
       castrum_route_destroy: { args: ['usize'], returns: 'void' },
+      // ── Batch fixed-width hex validation (ObjectId-shaped ids, etc.) ──
+      // NEWLINE-separated lines in; one verdict byte (1/0) per line out.
+      castrum_hex_validate_batch: {
+        args: abi(['ptr', 'usize', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      // ── JS-RegExp metacharacter escaping (needed-size convention) ──
+      castrum_regex_escape: { args: abi(['ptr', 'usize', 'ptr', 'usize']), returns: U64_FAST },
+      // ── Metrics registry (`castrum_metrics_*`) ──────────────────────
+      // Caller-owned handle (route-stack ownership model): create returns a
+      // Box<Registry> as usize; declare fns take name/label-keys as cstring
+      // ARGS (label keys `\x1f`-separated) and return the u32 series id
+      // (0xFFFFFFFF = error); record/set cross the packed label VALUES as a
+      // `(ptr,len)` pair + the amount as f64.
+      castrum_metrics_create: { args: [], returns: U64_FAST },
+      castrum_metrics_counter: { args: ['usize', 'cstring', 'cstring'], returns: 'u32' },
+      castrum_metrics_gauge: { args: ['usize', 'cstring', 'cstring'], returns: 'u32' },
+      castrum_metrics_histogram: {
+        args: ['usize', 'cstring', 'cstring', 'cstring'],
+        returns: 'u32',
+      },
+      castrum_metrics_record: {
+        args: abi(['usize', 'u32', 'ptr', 'usize', 'f64']),
+        returns: 'u8',
+      },
+      castrum_metrics_gauge_set: {
+        args: abi(['usize', 'u32', 'ptr', 'usize', 'f64']),
+        returns: 'u8',
+      },
+      // Zero-encode siblings: the joined label values cross as ONE `cstring`
+      // ARG — the engine transcodes the JS string in-engine (no TextEncoder).
+      castrum_metrics_record_str: {
+        args: ['usize', 'u32', 'cstring', 'f64'],
+        returns: 'u8',
+      },
+      castrum_metrics_gauge_set_str: {
+        args: ['usize', 'u32', 'cstring', 'f64'],
+        returns: 'u8',
+      },
+      // Zero-copy text escape: cstring ARG in, cstring return out — the JS
+      // side does zero encode AND zero decode (engine clones at return).
+      castrum_regex_escape_str: { args: ['cstring'], returns: 'cstring' },
+      // String-input batch hex validation: `ids.join('\n')` crosses as a
+      // cstring ARG.
+      castrum_hex_validate_batch_str: {
+        args: abi(['cstring', 'u32', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_metrics_render: { args: abi(['usize', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_metrics_snapshot: { args: abi(['usize', 'ptr', 'usize']), returns: U64_FAST },
+      castrum_metrics_record_batch: {
+        args: abi(['usize', 'ptr', 'usize']),
+        returns: 'u8',
+      },
+      // Fused wire-level validation: RAW query/cookie → JSON → draft-07 gate.
+      // `inner` is the SchemaValidator inner handle; strings cross as cstring
+      // ARGs (engine-transcoded).
+      castrum_query_validate: { args: ['usize', 'cstring'], returns: 'u8' },
+      castrum_cookie_validate: { args: ['usize', 'cstring'], returns: 'u8' },
+      // Fused session envelope: seal builds+signs; open verifies + extracts.
+      castrum_session_seal: {
+        args: ['cstring', 'cstring', 'i64', 'cstring'],
+        returns: 'cstring',
+      },
+      castrum_session_open: {
+        args: abi(['cstring', 'cstring', 'ptr', 'usize']),
+        returns: U64_FAST,
+      },
+      castrum_metrics_destroy: { args: ['usize'], returns: 'void' },
     })
 
-    const bindings = build(symbols as Record<string, (...a: unknown[]) => unknown>, useBufferLength)
+    // (`as unknown as`: the zero-arg `castrum_metrics_create` infers
+    // `(...args: never[])`, which can't overlap `(...a: unknown[])` directly.)
+    const bindings = build(
+      symbols as unknown as Record<string, (...a: unknown[]) => unknown>,
+      useBufferLength,
+    )
     if (!selfTest(bindings)) {
       if (mode === 'ffi') {
         throw new Error(

package/src/native/index.ts

@@ -4,5 +4,5 @@
 // (./loader.ts). Importing this barrel does NOT dlopen the addon — use
 // `getAddon()` / `lazyAddon` at call time.
 
+export { getAddon, getAddonPath, lazyAddon } from './loader'
 export * from './types'
-export { getAddonPath, getAddon, lazyAddon } from './loader'

package/src/native/loader.ts

@@ -5,9 +5,9 @@
 // `import castrum` as cheap as possible on Bun.
 
 import { existsSync, readFileSync, statSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { join, dirname } from 'node:path'
 import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { resolveEnvVar } from '../shared/env'
 import type { NativeAddon } from './types'
 

package/src/native/types/instances.ts

@@ -57,6 +57,40 @@ export interface RouteInstance {
   destroy?(): void
 }
 
+/**
+ * The native `MetricsRegistry` class instance — sharded counters / gauges /
+ * histograms with a Prometheus text-format render. Series are declared once
+ * (`counter`/`gauge`/`histogram` return a reusable id); per-event updates
+ * take the id + the label values for that event.
+ */
+export interface MetricsRegistryInstance {
+  /** Declare a counter family → its series id (idempotent per shape). */
+  counter(name: string, labelKeys?: string[]): number
+  /** Declare a gauge family → its series id (idempotent per shape). */
+  gauge(name: string, labelKeys?: string[]): number
+  /**
+   * Declare a histogram family → its series id. Omitted/empty `buckets`
+   * selects the default latency buckets.
+   */
+  histogram(name: string, labelKeys?: string[], buckets?: number[]): number
+  /** Counter/gauge `+= amount`, or histogram observe `amount`. */
+  record(series: number, values?: string[], amount?: number): void
+  /** Gauge assignment (`= value`). */
+  gaugeSet(series: number, values: string[] | undefined, value: number): void
+  /** Render the Prometheus text exposition format (deterministic order). */
+  render(): string
+  /**
+   * Packed v1 series snapshot bytes (families then series — see the Rust
+   * registry docs). bun:ffi-backed wrappers only; napi exposes
+   * `MetricsRegistry.snapshot()` directly.
+   */
+  snapshot?(): Uint8Array
+  /** Number of live series (tests / introspection; napi transport only). */
+  seriesCount?(): number
+  /** Free the native handle (bun:ffi-backed wrappers only). */
+  destroy?(): void
+}
+
 /** A single JSON Schema validation error (fast path + DOM fallback). */
 export interface SchemaError {
   /** RFC 6901 JSON pointer to the failing instance value ("" = root). */

package/src/native/types.ts

@@ -25,6 +25,7 @@ import type {
   MediaTypeMatcherInstance,
   MediaTypeParserInstance,
   MediaTypeResult,
+  MetricsRegistryInstance,
   MultipartPart,
   PasswordHashOptions,
   RateLimiterInstance,
@@ -145,6 +146,10 @@ export interface NativeAddon {
   validateUuid(input: Uint8Array): boolean
   validateIpv4(input: Uint8Array): boolean
   validateIpv6(input: Uint8Array): boolean
+  /** Batch fixed-width hex validation → one verdict byte per newline-separated line. */
+  hexValidateBatch(input: Uint8Array, width: number): Uint8Array
+  /** Escape JS-RegExp metacharacters so a pattern matches the input literally. */
+  regexEscape(input: string): string
 
   wsAcceptKey(key: Uint8Array): Uint8Array
   wsAcceptKeyBatchPacked(input: Uint8Array): Uint8Array
@@ -244,6 +249,12 @@ export interface NativeAddon {
     windowMs: number,
     maxEntries?: number | null,
   ) => RateLimiterInstance
+  /**
+   * Sharded counters / gauges / histograms registry with a Prometheus
+   * text-format render (the napi fallback transport for the `castrum_metrics_*`
+   * C-ABI surface).
+   */
+  MetricsRegistry: new () => MetricsRegistryInstance
 
   wsFrameEncode(opcode: number, payload: Uint8Array, mask: boolean, fin: boolean): Uint8Array
   wsFrameDecode(data: Uint8Array): WsFrame | null