castrum 0.7.0 → 0.9.1

package/src/runtime/uuid.ts

@@ -0,0 +1,45 @@
+// src/runtime/uuid.ts — UUIDv7 generation (Bun built-in, Node fallback).
+//
+// Deliberately does NOT implement UUIDv7 in Rust: the decision matrix measured
+// `Bun.randomUUIDv7` ~2x faster than the FFI-crossing rust random-token path,
+// so this delegates to the Bun built-in and falls back to
+// `crypto.randomUUID` (RFC 4122 v4) under Node. Formerly in
+// `src/shared/uuid.ts`; the branches now live here, selected once at load.
+
+import { detectedRuntime } from './detect'
+import type { UuidAdapter } from './types'
+
+/** Last-resort synchronous UUIDv4 (only if `crypto.randomUUID` is unavailable). */
+function fallbackRandomUuid(): string {
+  const bytes = new Uint8Array(16)
+  const c = globalThis.crypto
+  if (c?.getRandomValues) {
+    c.getRandomValues(bytes)
+  } else {
+    for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256)
+  }
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40 // version 4
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80 // variant 10xx
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+function bunUuidv7(): string {
+  return (
+    (globalThis as { Bun?: { randomUUIDv7?: () => string } }).Bun?.randomUUIDv7?.() ??
+    globalThis.crypto?.randomUUID?.() ??
+    fallbackRandomUuid()
+  )
+}
+
+function nodeUuidv7(): string {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackRandomUuid()
+}
+
+/** Build the uuid adapter for a runtime. */
+export function createUuidAdapter(name: 'bun' | 'node' | 'unknown'): UuidAdapter {
+  return name === 'bun' ? { uuidv7: bunUuidv7 } : { uuidv7: nodeUuidv7 }
+}
+
+/** The shared uuid adapter for the detected runtime (selected once at load). */
+export const runtimeUuid: UuidAdapter = createUuidAdapter(detectedRuntime)

package/src/runtime/websocket.ts

@@ -0,0 +1,30 @@
+// src/runtime/websocket.ts — platform WebSocket upgrade adapter.
+//
+// `createWebSocketUpgrade` returns the RFC 6455 101 handshake on Bun (whose
+// `Response` can carry status 101) and throws a clear Bun-only error on Node
+// (whose fetch `Response` rejects 101 — Node users must use the server-node
+// `upgrade` option instead). The handshake computation lives in
+// `src/integration/websocket.ts`; this adapter owns the runtime branch.
+
+import type { WebSocketUpgradeOptions, WebSocketUpgradeResult } from '../integration/websocket'
+import { createWebSocketUpgrade as buildBunUpgrade } from '../integration/websocket'
+import { detectedRuntime } from './detect'
+import type { WebsocketAdapter } from './types'
+
+const BUN_ONLY_ERROR =
+  "createWebSocketUpgrade is Bun-only: Node's Response cannot carry status 101. " +
+  "On Node, use createIngressServerNode's `upgrade` option and compute the " +
+  'accept key with rust.text.wsAcceptKey().'
+
+/** The shared websocket adapter for the detected host runtime. */
+export const runtimeWebsocket: WebsocketAdapter = {
+  createWebSocketUpgrade(
+    req: Request,
+    opts?: WebSocketUpgradeOptions,
+  ): WebSocketUpgradeResult | null {
+    if (detectedRuntime !== 'bun') {
+      throw new Error(BUN_ONLY_ERROR)
+    }
+    return buildBunUpgrade(req, opts)
+  },
+}

package/src/rust-ffi/addon.ts

@@ -0,0 +1,10 @@
+// src/rust-ffi/addon.ts — Shared lazy addon accessor for the FFI layer.
+//
+// All rust-ffi namespaces share a single lazily-loading proxy: importing this
+// module does NOT dlopen the addon — the first native call triggers loading
+// exactly once.
+
+import { getAddon, lazyAddon, type NativeAddon } from '../native'
+
+/** The shared lazy addon proxy (typed as the full native surface). */
+export const addon: NativeAddon = lazyAddon(getAddon)

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

@@ -0,0 +1,155 @@
+// src/rust-ffi/batch/build.ts — `buildBatch` implementation.
+//
+// Packs an array of byte slices into the packed wire format, calls the native
+// batch function, and unpacks the result into the friendly JS shape. Each
+// method wires one `RustBatch` (./types.ts) member to its `*BatchPacked` napi
+// fn via the shared pool-native resolver (context.ts).
+//
+// The `via` / `via2` builders below collapse the pack → native → unpack
+// plumbing every bulk op shares; each public method keeps its exact signature,
+// so the table stays type-safe against `RustBatch`.
+
+import {
+  schemaValidateBatch,
+  schemaValidateBatchCount,
+  unpackBitset,
+  unpackByteResults,
+  unpackI64ArrayAsBigInt,
+  unpackMultipartParts,
+  unpackU32Array,
+  unpackU64ArrayAsBigInt,
+  withPackScratch,
+  withPackScratch2,
+} from '../../shared/packed'
+import { type RustClientContext, resolvePoolNative } from '../context'
+import type { RustBatch } from './types'
+
+// Native batch fns are process-wide singletons (one lazy addon). `resolvePoolNative`
+// resolves each once (triggering pool init + addon load on first use) and caches
+// it, so the hot path skips the lazy-addon Proxy get on every call — the same
+// cache `resolveNative`/packed use (context.ts), with pool init for the
+// rayon-backed batch surface.
+function nativeFn(ctx: RustClientContext, name: string): (...args: unknown[]) => unknown {
+  return resolvePoolNative(ctx, name)
+}
+
+/**
+ * Build a single-list bulk op: `withPackScratch(items)` →
+ * `unpack(native(packed, ...extras))`. `R` is inferred from `unpack`, so the
+ * result stays assignable to the matching `RustBatch` method.
+ */
+function via<R>(
+  ctx: RustClientContext,
+  name: string,
+  unpack: (bytes: Uint8Array) => R,
+  extras: unknown[] = [],
+): (items: Uint8Array[]) => R {
+  return (items) =>
+    withPackScratch(items, (packed) => unpack(nativeFn(ctx, name)(packed, ...extras) as Buffer))
+}
+
+/**
+ * Build a two-list bulk op (docs+patches, items+sigs, ...): `withPackScratch2(a, b)`
+ * → `unpack(native(packedA, packedB, ...extras))`.
+ */
+function via2<R>(
+  ctx: RustClientContext,
+  name: string,
+  unpack: (bytes: Uint8Array) => R,
+  extras: unknown[] = [],
+): (a: Uint8Array[], b: Uint8Array[]) => R {
+  return (a, b) =>
+    withPackScratch2(a, b, (packedA, packedB) =>
+      unpack(nativeFn(ctx, name)(packedA, packedB, ...extras) as Buffer),
+    )
+}
+
+/** Build the `batch` namespace for a client context. */
+export function buildBatch(ctx: RustClientContext): RustBatch {
+  return {
+    // ── Single-list, no extras ──
+    jsonValid: via(ctx, 'jsonValidBatchPacked', unpackBitset),
+    crc32: via(ctx, 'crc32BatchPacked', unpackU32Array),
+    validateEmail: via(ctx, 'validateEmailBatchPacked', unpackBitset),
+    validateUuid: via(ctx, 'validateUuidBatchPacked', unpackBitset),
+    validateIpv4: via(ctx, 'validateIpv4BatchPacked', unpackBitset),
+    validateIpv6: via(ctx, 'validateIpv6BatchPacked', unpackBitset),
+    jsonSumIds: via(ctx, 'jsonSumBatchPacked', unpackI64ArrayAsBigInt),
+    queryParse: via(ctx, 'queryParseBatchPacked', unpackByteResults),
+    cookieParse: via(ctx, 'cookieParseBatchPacked', unpackByteResults),
+    formParse: via(ctx, 'formParseBatchPacked', unpackByteResults),
+    signCookie: (items, secret) =>
+      via(ctx, 'signCookieBatchPacked', unpackByteResults, [secret])(items),
+    verifyCookie: (items, secret) =>
+      via(ctx, 'verifyCookieBatchPacked', unpackBitset, [secret])(items),
+    csrfVerify: (items, secret) =>
+      via(ctx, 'csrfVerifyBatchPacked', unpackBitset, [secret])(items),
+    httpParseRequest: via(ctx, 'httpParseRequestBatchPacked', unpackByteResults),
+    fnv1a64: via(ctx, 'fnv1A64BatchPacked', unpackU64ArrayAsBigInt),
+    etag: (items, weak) => via(ctx, 'etagBatchPacked', unpackByteResults, [weak ?? null])(items),
+    urlEncode: via(ctx, 'urlEncodeBatchPacked', unpackByteResults),
+    urlDecode: via(ctx, 'urlDecodeBatchPacked', unpackByteResults),
+    urlDecodeBytes: via(ctx, 'urlDecodeBytesBatchPacked', unpackByteResults),
+    mimeFromExtension: via(ctx, 'mimeFromExtensionBatchPacked', unpackByteResults),
+    wsAcceptKey: via(ctx, 'wsAcceptKeyBatchPacked', unpackByteResults),
+    base64UrlEncode: (items) =>
+      via(ctx, 'base64EncodeBatchPacked', unpackByteResults, [true, false])(items),
+    base64UrlDecode: (items) =>
+      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [true, false])(items),
+    jsonPatch: (docs, patches) => via2(ctx, 'jsonPatchBatchPacked', unpackByteResults)(docs, patches),
+    hexEncode: via(ctx, 'hexEncodeBatchPacked', unpackByteResults),
+    hexDecode: via(ctx, 'hexDecodeBatchPacked', unpackByteResults),
+    base64Encode: (items, urlSafe, padding) =>
+      via(ctx, 'base64EncodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(items),
+    base64Decode: (items, urlSafe, padding) =>
+      via(ctx, 'base64DecodeBatchPacked', unpackByteResults, [urlSafe ?? null, padding ?? null])(items),
+    schemaValidate(validator, items) {
+      return schemaValidateBatch(validator, items)
+    },
+    schemaValidateCount(validator, items) {
+      return schemaValidateBatchCount(validator, items)
+    },
+
+    // ── Backend-framework features ──
+    passwordHash: (passwords, salt, options) =>
+      via(ctx, 'passwordHashBatchPacked', unpackByteResults, [salt, options ?? null])(passwords),
+    aeadEncrypt: (key, nonce, items, algorithm) =>
+      via(ctx, 'aeadEncryptBatchPacked', unpackByteResults, [key, nonce, algorithm ?? null])(items),
+    aeadDecrypt: (key, nonce, items, algorithm) =>
+      via(ctx, 'aeadDecryptBatchPacked', unpackByteResults, [key, nonce, algorithm ?? null])(items),
+    gzipCompress: (items, level) =>
+      via(ctx, 'gzipCompressBatchPacked', unpackByteResults, [level ?? null])(items),
+    gzipDecompress: (items, maxDecompressed) =>
+      via(ctx, 'gzipDecompressBatchPacked', unpackByteResults, [maxDecompressed ?? null])(items),
+    brotliCompress: (items, quality) =>
+      via(ctx, 'brotliCompressBatchPacked', unpackByteResults, [quality ?? null])(items),
+    brotliDecompress: (items, maxDecompressed) =>
+      via(ctx, 'brotliDecompressBatchPacked', unpackByteResults, [maxDecompressed ?? null])(items),
+    jwtVerify: (tokens, secret, nowSeconds) =>
+      via(ctx, 'jwtVerifyBatchPacked', unpackBitset, [secret, nowSeconds])(tokens),
+    hmacSha256: (items, key) => via(ctx, 'hmacSha256BatchPacked', unpackByteResults, [key])(items),
+    hmacSha256Verify: (items, sigs, key) =>
+      via2(ctx, 'hmacSha256VerifyBatchPacked', unpackBitset, [key])(items, sigs),
+    // ── Two-list ──
+    passwordVerify: (items, phcs) => via2(ctx, 'passwordVerifyBatchPacked', unpackBitset)(items, phcs),
+    urlResolve: (bases, references) =>
+      via2(ctx, 'urlResolveBatchPacked', unpackByteResults)(bases, references),
+    templateRender: (source, contexts) =>
+      via(ctx, 'templateRenderBatchPacked', unpackByteResults, [source])(contexts),
+    jwtSign: (items, secret, ttlSeconds, nowSeconds) =>
+      via(ctx, 'jwtSignBatchPacked', unpackByteResults, [
+        secret,
+        ttlSeconds ?? null,
+        nowSeconds ?? Math.floor(Date.now() / 1000),
+      ])(items),
+    sseEncode: (items, event, id, retry) =>
+      via(ctx, 'sseEncodeBatchPacked', unpackByteResults, [event ?? null, id ?? null, retry ?? null])(
+        items,
+      ),
+    wsFrameEncode: (items, opcode, mask, fin) =>
+      via(ctx, 'wsFrameEncodeBatchPacked', unpackByteResults, [opcode, mask, fin])(items),
+    wsFrameDecode: via(ctx, 'wsFrameDecodeBatchPacked', unpackByteResults),
+    multipartParse: (items, boundary) =>
+      via(ctx, 'multipartParseBatchPacked', unpackMultipartParts, [boundary])(items),
+  }
+}

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

@@ -0,0 +1,8 @@
+// src/rust-ffi/batch/index.ts — Array-of-bytes batch namespace (barrel).
+//
+// Re-exports the `RustBatch` interface (./types.ts) and its builder
+// (./build.ts) so existing `import { buildBatch, type RustBatch } from
+// '../rust-ffi/batch'` call sites keep working.
+
+export { buildBatch } from './build'
+export type { RustBatch } from './types'

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

@@ -0,0 +1,92 @@
+// src/rust-ffi/batch/types.ts — Array-of-bytes batch namespace type.
+//
+// The `RustBatch` interface — the friendly JS shape of `rust.batch.*`
+// (bitsets, u32 arrays, i64 arrays, byte results) — separated from the
+// implementation (./build.ts) so type-only consumers don't pull the native
+// resolver.
+
+import type { MultipartPart, PasswordHashOptions } from '../../native'
+import type { SchemaValidator } from '../../shared/packed'
+
+/**
+ * The `rust.batch.*` array-of-bytes batch surface: N items in → one packed
+ * native call → bitsets / typed arrays / byte arrays out. Separated from the
+ * implementation (`./build.ts`) so type-only consumers don't pull the native
+ * resolver.
+ */
+export interface RustBatch {
+  jsonValid(items: Uint8Array[]): Uint8Array
+  crc32(items: Uint8Array[]): Uint32Array
+  validateEmail(items: Uint8Array[]): Uint8Array
+  validateUuid(items: Uint8Array[]): Uint8Array
+  validateIpv4(items: Uint8Array[]): Uint8Array
+  validateIpv6(items: Uint8Array[]): Uint8Array
+  jsonSumIds(items: Uint8Array[]): BigInt64Array
+  queryParse(items: Uint8Array[]): Uint8Array[]
+  cookieParse(items: Uint8Array[]): Uint8Array[]
+  httpParseRequest(items: Uint8Array[]): Uint8Array[]
+  jsonPatch(docs: Uint8Array[], patches: Uint8Array[]): Uint8Array[]
+  hexEncode(items: Uint8Array[]): Uint8Array[]
+  hexDecode(items: Uint8Array[]): Uint8Array[]
+  base64Encode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  base64Decode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  formParse(items: Uint8Array[]): Uint8Array[]
+  signCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array[]
+  verifyCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  csrfVerify(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  schemaValidate(validator: SchemaValidator, items: Uint8Array[]): Uint8Array
+  schemaValidateCount(validator: SchemaValidator, items: Uint8Array[]): number
+  fnv1a64(items: Uint8Array[]): BigUint64Array
+  etag(items: Uint8Array[], weak?: boolean | null): Uint8Array[]
+  urlEncode(items: Uint8Array[]): Uint8Array[]
+  urlDecode(items: Uint8Array[]): Uint8Array[]
+  urlDecodeBytes(items: Uint8Array[]): Uint8Array[]
+  mimeFromExtension(items: Uint8Array[]): Uint8Array[]
+  wsAcceptKey(items: Uint8Array[]): Uint8Array[]
+  base64UrlEncode(items: Uint8Array[]): Uint8Array[]
+  base64UrlDecode(items: Uint8Array[]): Uint8Array[]
+
+  // ── Backend-framework features ──
+  passwordHash(
+    passwords: Uint8Array[],
+    salt: Uint8Array,
+    options?: PasswordHashOptions | null,
+  ): Uint8Array[]
+  aeadEncrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    items: Uint8Array[],
+    algorithm?: string | null,
+  ): Uint8Array[]
+  aeadDecrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    items: Uint8Array[],
+    algorithm?: string | null,
+  ): Uint8Array[]
+  gzipCompress(items: Uint8Array[], level?: number | null): Uint8Array[]
+  gzipDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[]
+  brotliCompress(items: Uint8Array[], quality?: number | null): Uint8Array[]
+  brotliDecompress(items: Uint8Array[], maxDecompressed?: number | null): Uint8Array[]
+  jwtVerify(tokens: Uint8Array[], secret: Uint8Array, nowSeconds: number): Uint8Array
+  hmacSha256(items: Uint8Array[], key: Uint8Array): Uint8Array[]
+  hmacSha256Verify(items: Uint8Array[], sigs: Uint8Array[], key: Uint8Array): Uint8Array
+  passwordVerify(items: Uint8Array[], phcs: Uint8Array[]): Uint8Array
+  urlResolve(bases: Uint8Array[], references: Uint8Array[]): Uint8Array[]
+  jwtSign(
+    items: Uint8Array[],
+    secret: Uint8Array,
+    ttlSeconds?: number | null,
+    nowSeconds?: number,
+  ): Uint8Array[]
+  sseEncode(
+    items: Uint8Array[],
+    event?: string | null,
+    id?: string | null,
+    retry?: number | null,
+  ): Uint8Array[]
+  wsFrameEncode(items: Uint8Array[], opcode: number, mask: boolean, fin: boolean): Uint8Array[]
+  wsFrameDecode(items: Uint8Array[]): Uint8Array[]
+  multipartParse(items: Uint8Array[], boundary: Uint8Array): MultipartPart[][]
+  templateRender(source: string, contexts: Uint8Array[]): Uint8Array[]
+}

package/src/rust-ffi/client.ts

@@ -0,0 +1,87 @@
+// src/rust-ffi/client.ts — Rust client factory + default instance.
+//
+// Composes the per-namespace builders (scalar / text / batch / packed) over a
+// shared per-instance context (./context.ts) and exposes `configure`.
+
+import { buildBatch, type RustBatch } from './batch'
+import { createContext } from './context'
+import type { RustOptions } from './options'
+import { buildPacked, type RustPacked } from './packed'
+import { buildScalar, type RustScalar } from './scalar'
+import { buildText, type RustText } from './text'
+
+/** The full Rust FFI client (scalar methods + namespaces + configuration). */
+export interface RustClient extends RustScalar {
+  // ── Namespaces ──
+  text: RustText
+  batch: RustBatch
+  packed: RustPacked
+
+  // ── Transport introspection ──
+  /**
+   * Resolve the native transport in use on this runtime: `"ffi"` (bun:ffi —
+   * the PRIMARY transport under Bun) or `"napi"` (Node, forced
+   * `CASTRUM_FFI_MODE=napi`, or a failed ffi bind-time self-test).
+   */
+  transport(): 'ffi' | 'napi'
+  /** Whether the bun:ffi transport is live (equivalent to `transport() === "ffi"`). */
+  ffiActive(): boolean
+
+  // ── Configuration ──
+  /**
+   * Update defaults on this instance. `mimeCache` / `hmacCache` apply
+   * immediately (per-instance). `rayonThreads` is applied only if the
+   * process-wide pool is not yet initialized (see {@link RustOptions}).
+   */
+  configure(options: RustOptions): void
+}
+
+/**
+ * Create an isolated Rust client with the given defaults.
+ *
+ * `mimeCache` / `hmacCache` are per-instance. `rayonThreads` only applies
+ * before the process-wide rayon pool is initialized (once per process — see
+ * {@link RustOptions.rayonThreads}); the pool defaults to the env var or
+ * `max(1, hardwareConcurrency - 1)` otherwise.
+ */
+export function createRust(options: RustOptions = {}): RustClient {
+  const ctx = createContext(options)
+
+  return {
+    ...buildScalar(ctx),
+    text: buildText(ctx),
+    batch: buildBatch(ctx),
+    packed: buildPacked(ctx),
+
+    // ── Transport introspection (FFI-primary on Bun; napi is the fallback) ──
+    transport() {
+      return ctx.runtime.transport.name
+    },
+    ffiActive() {
+      return ctx.runtime.transport.ffiActive()
+    },
+
+    // ── Configuration ──
+    configure(next) {
+      // rayonThreads only takes effect BEFORE the pool is first used.
+      if (next.rayonThreads !== undefined && !ctx.isPoolInitialized()) {
+        ctx.setPendingThreads(next.rayonThreads)
+      }
+
+      if (next.mimeCache !== undefined) {
+        ctx.state.mimeCache = next.mimeCache
+      }
+
+      if (next.hmacCache !== undefined) {
+        ctx.state.hmacCache = next.hmacCache
+      }
+    },
+  }
+}
+
+/**
+ * The default, ready-to-use `RustClient` created with no options (resolves
+ * rayon threads from the host automatically). Most consumers just do
+ * `import { rust } from "castrum"` and call `rust.<fn>(...)` directly.
+ */
+export const rust = createRust()

package/src/rust-ffi/context.ts

@@ -0,0 +1,193 @@
+// src/rust-ffi/context.ts — Per-instance state + shared helpers for the Rust
+// client namespaces.
+//
+// Each `createRust()` call builds one context holding its own caches, toggles
+// and the lazily-initialized rayon-pool bookkeeping. The mutable pool state
+// (initialized flag / pending thread count) stays encapsulated behind accessor
+// functions so it cannot be corrupted externally.
+
+import type { HmacSignerInstance } from '../native'
+import type { BunFFI } from '../native/ffi'
+import { runtimeNative } from '../runtime/native'
+import type { NativeRuntimeAdapter, TransportAdapter } from '../runtime/types'
+import { addon } from './addon'
+import type { RustOptions } from './options'
+import { normalizeExt, resolveRayonThreads } from './options'
+
+// Module-level cache of resolved native fns. The native addon is a process
+// singleton, so the resolved function is identical across all client contexts;
+// caching it here lets scalar/packed/text wrappers skip the lazy-addon Proxy
+// `get` trap (a branch + `Reflect.get`) on every call — the same pattern
+// batch.ts uses for its packed entries.
+const nativeFnCache = new Map<string, unknown>()
+
+/**
+ * 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
+ * fallback otherwise), so builders no longer repeat `getBunFFI()` inline.
+ * Preserves the lazy-load contract (the addon is only loaded on the first
+ * real native call) while removing per-call Proxy overhead.
+ */
+export function resolveNative(
+  ctx: RustClientContext,
+  name: string,
+): (...args: unknown[]) => unknown {
+  let f = nativeFnCache.get(name)
+  if (f === undefined) {
+    const fn = ctx.runtime.transport.resolve(name)
+    f = fn ?? (ctx.addon as unknown as Record<string, unknown>)[name]
+    nativeFnCache.set(name, f)
+  }
+  return f as (...args: unknown[]) => unknown
+}
+
+/**
+ * Resolve a native fn and ensure the process-wide rayon pool is initialized
+ * on first use — the rayon-backed `batch`/`packed` surfaces need this, while
+ * `resolveNative` (plain scalars) must NOT init the pool so
+ * `rust.configure({ rayonThreads })` can still take effect at startup.
+ * Shares the SAME `nativeFnCache` as `resolveNative` (the batch fn names are
+ * disjoint from the scalar names, so the shared cache is safe). FFI-first via
+ * the runtime adapter's transport, like `resolveNative`.
+ */
+export function resolvePoolNative(
+  ctx: RustClientContext,
+  name: string,
+): (...args: unknown[]) => unknown {
+  let f = nativeFnCache.get(name)
+  if (f === undefined) {
+    ctx.ensurePool()
+    const fn = ctx.runtime.transport.resolve(name)
+    f = fn ?? (ctx.addon as unknown as Record<string, unknown>)[name]
+    nativeFnCache.set(name, f)
+  }
+  return f as (...args: unknown[]) => unknown
+}
+
+/**
+ * Lazy memoized `bun:ffi` resolver for the scalar builders.
+ *
+ * Returns a closure that resolves `transport.ffi` ONCE — on the first call —
+ * and reads the local from then on. This keeps the FFI bind DEFERRED
+ * (importing `rust` does not eagerly dlopen; the builder factories run at
+ * module load) while removing the per-call `() => transport.ffi` getter hop
+ * from the hot path. The transport's own cache already makes the steady-state
+ * resolve a single `undefined`-check; this collapses the getter + inner
+ * closure into one local read.
+ */
+export function memoizeFfi(transport: TransportAdapter): () => BunFFI | null {
+  let resolved: BunFFI | null | undefined
+  return () => {
+    if (resolved === undefined) resolved = transport.ffi
+    return resolved
+  }
+}
+
+/** Shared per-instance state passed to the namespace/scalar builders. */
+export interface RustClientContext {
+  /** The shared lazy addon proxy (napi surface). */
+  addon: typeof addon
+  /** The runtime adapter seam (Bun/Node — builtins + ffi/napi transport). */
+  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). */
+  ensurePool(): void
+  /** Whether the rayon pool state has been established on this instance. */
+  isPoolInitialized(): boolean
+  /** Record the caller's intent for the process-wide pool before it inits. */
+  setPendingThreads(threads: number | undefined): void
+  /** Mark the pool state as established (explicit initThreadPool calls). */
+  markPoolInitialized(): void
+  /** Cached MIME lookup (returns the cached bytes by reference — do not mutate). */
+  cachedMime(ext: Uint8Array): Uint8Array
+  /** Cached HMAC signer lookup. */
+  hmacSigner(key: Uint8Array): HmacSignerInstance
+}
+
+/** 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,
+    hmacCache: options.hmacCache !== false,
+  }
+
+  // The native rayon pool is a process-wide OnceLock: the FIRST call wins.
+  // We therefore defer init until the first batch/packed operation so that
+  // rust.configure({ rayonThreads }) called at startup actually takes effect
+  // (previously the pool was initialized eagerly at module load, silently
+  // ignoring later rayonThreads tuning).
+  let poolInitialized = false
+  let pendingThreads = options.rayonThreads
+
+  function ensurePool(): void {
+    if (poolInitialized) return
+    poolInitialized = true
+    addon.initThreadPool(resolveRayonThreads(pendingThreads))
+  }
+
+  function isPoolInitialized(): boolean {
+    return poolInitialized
+  }
+
+  function setPendingThreads(threads: number | undefined): void {
+    pendingThreads = threads
+  }
+
+  function markPoolInitialized(): void {
+    poolInitialized = true
+  }
+
+  function cachedMime(ext: Uint8Array): Uint8Array {
+    if (!state.mimeCache) {
+      return addon.mimeFromExtension(ext)
+    }
+
+    const key = normalizeExt(ext)
+
+    let val = mimeByText.get(key)
+    if (!val) {
+      val = addon.mimeFromExtension(ext)
+      mimeByText.set(key, val)
+    }
+
+    // Return the cached bytes BY REFERENCE (no per-call defensive copy — a
+    // measurable win on the MIME parity op). The returned slice aliases the
+    // cache: callers must NOT mutate it (same contract as `generateRequestId`).
+    return val
+  }
+
+  function hmacSigner(key: Uint8Array): HmacSignerInstance {
+    if (!state.hmacCache) {
+      return new addon.HmacSigner(key)
+    }
+
+    let signer = hmacSigners.get(key)
+
+    if (!signer) {
+      signer = new addon.HmacSigner(key)
+      hmacSigners.set(key, signer)
+    }
+
+    return signer
+  }
+
+  return {
+    addon,
+    runtime: runtimeNative,
+    state,
+    mimeByText,
+    hmacSigners,
+    ensurePool,
+    isPoolInitialized,
+    setPendingThreads,
+    markPoolInitialized,
+    cachedMime,
+    hmacSigner,
+  }
+}