castrum 0.9.3 → 0.9.6

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
@@ -213,6 +218,12 @@ export interface BunFFI {
   gzipDecompress(data: Uint8Array, maxDecompressed?: number): Uint8Array
   /** gzip-decompress into `output`; returns bytes written (throws if too small). */
   gzipDecompressInto(data: Uint8Array, output: Uint8Array, maxDecompressed?: number): number
+  /**
+   * gzip ISIZE trailer probe → the uncompressed size for a single-member gzip
+   * stream, or `0` when unknown (invalid stream / multi-member). Used to
+   * PRE-SIZE a destination buffer for the zero-copy task path.
+   */
+  gzipIsize(data: Uint8Array): number
   /** brotli-compress into a fresh buffer (quality clamped 0..=11, default 5). */
   brotliCompress(data: Uint8Array, quality?: number): Uint8Array
   /** brotli-compress into `output`; returns bytes written (throws if too small). */
@@ -308,7 +319,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 +402,132 @@ 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
+
+  // ── Off-thread task runtime (castrum_task_*) ──────────────────────
+  /** Start the shared native task pool; 0 = started, 1 = already running. */
+  taskInit(threads: number): number
+  /** Submit a task op with packed `args` under `taskId`; 1 = accepted. */
+  taskSubmit(op: number, args: Uint8Array, taskId: number): number
+  /**
+   * Zero-copy submit: the op writes its result DIRECTLY into `output` on the
+   * pool thread. `output` must be a stable, caller-owned buffer that stays
+   * alive (and untouched) until the completion is drained — the runtime holds
+   * the reference. The completion body is the 8-byte LE written length.
+   */
+  taskSubmitOut(op: number, args: Uint8Array, taskId: number, output: Uint8Array): number
+  /**
+   * Zero-copy INPUT: only `hdr` is copied; `data` is read in place by the pool
+   * thread, so the caller must keep it alive (and untouched) until completion.
+   */
+  taskSubmitSlice(op: number, hdr: Uint8Array, data: Uint8Array, taskId: number): number
+  /**
+   * Drain finished tasks into `output` (packed `[u32 count][entry…]`).
+   * Returns bytes written, `0` when nothing is pending, or the EXACT required
+   * size when `output` is too small (nothing is consumed in that case).
+   */
+  taskDrain(output: Uint8Array): number
+  /** Finished-but-undrained completion count. */
+  taskPending(): number
+  /** Mark a task cancelled; 1 = newly marked, 0 = unknown/already finished. */
+  taskCancel(taskId: number): number
+  /** Register the thread-safe doorbell trampoline address (`0` disables it). */
+  taskSetDoorbell(ptr: number): number
+  /** Stop the task pool and drop pending completions. */
+  taskShutdown(): number
+  /** Configured task-pool worker count (0 before the pool starts). */
+  taskThreads(): number
 }
 
 /**
@@ -411,6 +551,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

@@ -34,7 +34,7 @@ import type { BunFFI, FfiMode } from './ffi/types'
 // Static import: loader.ts has no side effects (path resolution only — no
 // dlopen), so this adds zero import-time cost while letting `bind()` reuse the
 // exact same resolved `.node` path the napi fallback uses (the shared seam).
-import { getAddonPath } from './loader'
+import { getAddonPath, getAddonPathCandidates } from './loader'
 
 // Re-export the type surface so `import type { BunFFI } from '../native/ffi'`
 // keeps working (existing call sites).
@@ -49,6 +49,12 @@ let cached: BunFFI | null | undefined
  */
 let bufferAbiMode: 'buffer-pair' | 'ptr-len' | null = null
 
+/**
+ * The addon file the live `bun:ffi` binding was opened from, or `null` while
+ * unbound. Diagnostics only — a v3→baseline fallback is visible here.
+ */
+let boundAddonPath: string | null = null
+
 // ── Transport selection (CASTRUM_FFI_MODE) ───────────────────────
 
 function resolveFfiMode(): FfiMode {
@@ -96,6 +102,20 @@ export function ffiBufferMode(): 'buffer-pair' | 'ptr-len' | null {
   return bufferAbiMode
 }
 
+/**
+ * The addon file path the live `bun:ffi` binding was opened from, or `null`
+ * when the transport is unavailable (Node, `CASTRUM_FFI_MODE=napi`, or every
+ * candidate failed). Lazy — triggers the same one-time bind as
+ * {@link getBunFFI}. Use it to confirm WHICH artifact bound, e.g. when a stale
+ * v3 SIMD binary forced the baseline fallback.
+ */
+export function ffiAddonPath(): string | null {
+  if (cached === undefined) {
+    getBunFFI()
+  }
+  return boundAddonPath
+}
+
 /**
  * Probe whether this Bun build accepts the `buffer`/`buffer_length` ABI pair in
  * `dlopen`. Bun's docs list `buffer_length` as engine-native (dlopen-supported),
@@ -127,7 +147,7 @@ function probeBufferLength(dlopen: typeof import('bun:ffi')['dlopen'], path: str
   }
 }
 
-function bind(): BunFFI | null {
+function bind(forcedPath?: string, tried: string[] = []): BunFFI | null {
   bufferAbiMode = null // reset — the mode below is only valid for a live bind
   const mode = resolveFfiMode()
   if (!isBun()) {
@@ -143,12 +163,13 @@ function bind(): BunFFI | null {
   if (mode === 'napi') {
     return null
   }
+  // Resolve the SAME addon file napi uses (./loader.ts — statically imported
+  // above; it only resolves the path, it never dlopens the addon). On a retry,
+  // `forcedPath` is the next candidate from `getAddonPathCandidates()`.
+  const path = forcedPath ?? getAddonPath()
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { dlopen } = require('bun:ffi') as typeof import('bun:ffi')
-    // Resolve the SAME addon file napi uses (./loader.ts — statically imported
-    // above; it only resolves the path, it never dlopens the addon).
-    const path = getAddonPath()
 
     // Probe `buffer`/`buffer_length` (the engine reads ptr + len off the SAME
     // TypedArray at call time — an atomic snapshot) once; when supported we use
@@ -206,10 +227,25 @@ 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).
+      //
+      // SAFETY RULE for every `cstring` ARG added here: the transcode is
+      // NUL-TERMINATED, so an embedded U+0000 truncates the value in-engine. A
+      // verdict op bound this way can be fooled (`validateEmail` on
+      // 'a@b.com\0<script>' returned TRUE before the byte re-route). Either
+      // give the op a `_bytes` sibling and route byte callers to it, or guard
+      // the string form with `hasNul` — see docs/FFI_BUN_GUIDE.md §6.1,
+      // pinned by test/unit/native/cstring-nul.test.ts.
       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 +393,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,24 +508,128 @@ 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,
+      },
+      // Off-thread task runtime: `submit` takes a packed `(ptr,len)` arg blob
+      // plus a JS-assigned id; `drain` writes the packed completion batch into
+      // a caller buffer (needed-size convention). `set_doorbell` takes the raw
+      // `JSCallback({threadsafe:true}).ptr` as a bare pointer (`abi` leaves a
+      // lone `ptr` untouched), so the pool can wake JS once per batch.
+      castrum_task_init: { args: ['u32'], returns: 'u32' },
+      castrum_task_submit: { args: abi(['u32', 'ptr', 'usize', 'usize']), returns: 'u32' },
+      castrum_task_submit_slice: {
+        args: abi(['u32', 'ptr', 'usize', 'ptr', 'usize', 'usize']),
+        returns: 'u32',
+      },
+      castrum_task_submit_out: {
+        args: abi(['u32', 'ptr', 'usize', 'usize', 'ptr', 'usize']),
+        returns: 'u32',
+      },
+      castrum_task_drain: { args: abi(['ptr', 'usize']), returns: U64_FAST },
+      castrum_task_pending: { args: [], returns: 'u32' },
+      castrum_task_cancel: { args: ['usize'], returns: 'u32' },
+      castrum_task_set_doorbell: { args: ['ptr'], returns: 'u32' },
+      castrum_task_shutdown: { args: [], returns: 'u32' },
+      castrum_task_threads: { args: [], returns: 'u32' },
+      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(
-          'CASTRUM_FFI_MODE=ffi: the bun:ffi bind-time self-test failed, so the ' +
-            'primary transport cannot be trusted on this Bun/addon combination. ' +
-            'Unset CASTRUM_FFI_MODE (or use CASTRUM_FFI_MODE=auto) to fall back to napi.',
-        )
-      }
-      return null
+      throw new Error(`bun:ffi bind-time self-test failed on ${path}`)
     }
+    boundAddonPath = path
     return bindings
   } catch (err) {
+    bufferAbiMode = null
+    // The preferred artifact failed to dlopen/bind/self-test. The common cause
+    // is a STALE v3 SIMD binary (`castrum.linux-x64-v3-gnu.node`) that predates
+    // a newly added `castrum_*` symbol: dlopen fails, and without this walk the
+    // whole FFI transport would be disabled (every call silently downgraded to
+    // napi, and the task runtime silently made synchronous). Try the remaining
+    // existing candidates — the baseline binary — before giving up.
+    for (const next of getAddonPathCandidates()) {
+      if (next === path || tried.includes(next)) continue
+      const bound = bind(next, [...tried, path])
+      if (bound) return bound
+    }
     if (mode === 'ffi') {
       const cause = err instanceof Error ? `: ${err.message}` : ''
-      throw new Error(`CASTRUM_FFI_MODE=ffi: failed to bind bun:ffi${cause}`)
+      throw new Error(
+        `CASTRUM_FFI_MODE=ffi: failed to bind bun:ffi${cause} ` +
+          `(tried: ${[...tried, path].join(', ')})`,
+      )
     }
     return null
   }

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'
 
@@ -67,15 +67,16 @@ export function supportsX8664V3(cpuinfo?: string): boolean {
  * @param arch `process.arch`
  * @param cpuinfo optional `/proc/cpuinfo` text (tests inject it; the real call
  *   omits it and reads the file lazily on linux/x64 only)
- * @returns the first existing candidate path (throws if none exists)
+ * @returns every candidate path, in preference order (v3 SIMD first on a
+ *   capable linux/x64 host, then the baseline names)
  */
-export function resolveAddonPathFrom(
+export function addonCandidatesFrom(
   envOverride: string | undefined,
   baseDir: string,
   platform: string,
   arch: string,
   cpuinfo?: string,
-): string {
+): string[] {
   // napi-rs artifact naming: castrum.<platform>-<arch>[-<libc>].node
   // e.g. linux-x64-gnu, linux-x64-musl, win32-x64-msvc, darwin-arm64.
   const libcVariants =
@@ -156,6 +157,22 @@ export function resolveAddonPathFrom(
     candidates.push(join(baseDir, '..', '..', 'target', 'release', name))
   }
 
+  return candidates
+}
+
+/**
+ * Resolve the addon path: the FIRST existing candidate from
+ * {@link addonCandidatesFrom} (v3 SIMD first on a capable linux/x64 host).
+ * Throws when nothing exists.
+ */
+export function resolveAddonPathFrom(
+  envOverride: string | undefined,
+  baseDir: string,
+  platform: string,
+  arch: string,
+  cpuinfo?: string,
+): string {
+  const candidates = addonCandidatesFrom(envOverride, baseDir, platform, arch, cpuinfo)
   for (const candidate of candidates) {
     if (existsSync(candidate)) {
       return candidate
@@ -169,6 +186,39 @@ export function resolveAddonPathFrom(
   )
 }
 
+/** Cached result of {@link getAddonPathCandidates} (existing files only). */
+let cachedCandidates: string[] | undefined
+
+/**
+ * Every EXISTING addon candidate, in preference order (v3 SIMD first on a
+ * capable linux/x64 host, then the baseline names).
+ *
+ * The bun:ffi binder walks this list so a stale or partial *preferred* artifact
+ * — e.g. a `castrum.linux-x64-v3-gnu.node` built before a newly added
+ * `castrum_*` symbol — falls back to the baseline binary instead of silently
+ * disabling the whole FFI transport (which would downgrade every native call to
+ * napi and make the off-thread task runtime run synchronously).
+ */
+export function getAddonPathCandidates(): string[] {
+  if (cachedCandidates) return cachedCandidates
+  const all = addonCandidatesFrom(
+    resolveEnvVar('CASTRUM_NATIVE_LIBRARY_PATH', ['NAPI_RS_NATIVE_LIBRARY_PATH']),
+    dirname(fileURLToPath(import.meta.url)),
+    process.platform,
+    process.arch,
+  )
+  const seen = new Set<string>()
+  const existing: string[] = []
+  for (const candidate of all) {
+    if (!seen.has(candidate) && existsSync(candidate)) {
+      seen.add(candidate)
+      existing.push(candidate)
+    }
+  }
+  cachedCandidates = existing
+  return existing
+}
+
 function resolveAddonPath(): string {
   return resolveAddonPathFrom(
     resolveEnvVar('CASTRUM_NATIVE_LIBRARY_PATH', ['NAPI_RS_NATIVE_LIBRARY_PATH']),

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