castrum 0.7.0 → 0.9.0

package/src/rust-ffi/batch.ts

@@ -0,0 +1,431 @@
+// src/rust-ffi/batch.ts — Array-of-bytes FFI namespace.
+//
+// `rust.batch.*` 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 (bitsets, u32 arrays, i64 arrays, byte results).
+
+import {
+  schemaValidateBatch,
+  schemaValidateBatchCount,
+  unpackBitset,
+  unpackByteResults,
+  unpackI64ArrayAsBigInt,
+  unpackMultipartParts,
+  unpackU32Array,
+  unpackU64ArrayAsBigInt,
+  withPackScratch,
+  withPackScratch2,
+  type SchemaValidator,
+} from '../shared/packed'
+import { resolvePoolNative, type RustClientContext } from './context'
+import type { MultipartPart, PasswordHashOptions } from '../native'
+
+/** Array-of-bytes FFI namespace. */
+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[]
+  /** Apply N RFC 6902 patches (docs and patches zipped). Fail-fast on error. */
+  jsonPatch(docs: Uint8Array[], patches: Uint8Array[]): Uint8Array[]
+  /** Encode N items to lowercase hex (packed in → byte results). */
+  hexEncode(items: Uint8Array[]): Uint8Array[]
+  /** Decode N lowercase/uppercase hex strings to bytes. */
+  hexDecode(items: Uint8Array[]): Uint8Array[]
+  /** Base64-encode N items (standard by default; url-safe/padding configurable). */
+  base64Encode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  /** Base64-decode N items (standard by default; url-safe/padding configurable). */
+  base64Decode(items: Uint8Array[], urlSafe?: boolean, padding?: boolean): Uint8Array[]
+  formParse(items: Uint8Array[]): Uint8Array[]
+  /** Sign N cookie values (packed → byte results). */
+  signCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array[]
+  /** Verify N signed cookies (bitset of valid). */
+  verifyCookie(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  /** Verify N CSRF tokens (bitset of valid). */
+  csrfVerify(items: Uint8Array[], secret: Uint8Array): Uint8Array
+  schemaValidate(validator: SchemaValidator, items: Uint8Array[]): Uint8Array
+  schemaValidateCount(validator: SchemaValidator, items: Uint8Array[]): number
+  /** Hash N items with FNV-1a 64 (packed → unsigned u64 array). */
+  fnv1a64(items: Uint8Array[]): BigUint64Array
+  /** Generate N ETags (strong by default; weak flag applies to all items). */
+  etag(items: Uint8Array[], weak?: boolean | null): Uint8Array[]
+  urlEncode(items: Uint8Array[]): Uint8Array[]
+  /** Percent-decode N strings (UTF-8 validated; malformed items → empty). */
+  urlDecode(items: Uint8Array[]): Uint8Array[]
+  /** Strict percent-decode N strings (no UTF-8 validation). */
+  urlDecodeBytes(items: Uint8Array[]): Uint8Array[]
+  mimeFromExtension(items: Uint8Array[]): Uint8Array[]
+  wsAcceptKey(items: Uint8Array[]): Uint8Array[]
+  /** Base64url-encode N items (URL-safe, no padding). */
+  base64UrlEncode(items: Uint8Array[]): Uint8Array[]
+  /** Base64url-decode N items (URL-safe, no padding). */
+  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
+  /** Sign N messages to lowercase-hex HMAC-SHA256 signatures (packed → byte results). */
+  hmacSha256(items: Uint8Array[], key: Uint8Array): Uint8Array[]
+  /** Verify N message + hex-signature pairs (two packed lists, zipped) → bitset of valid. */
+  hmacSha256Verify(items: Uint8Array[], sigs: Uint8Array[], key: Uint8Array): Uint8Array
+  /** Verify N password+PHC pairs (two packed lists, zipped) → bitset of valid. */
+  passwordVerify(items: Uint8Array[], phcs: Uint8Array[]): Uint8Array
+  /** Resolve N references against N bases (two packed lists, zipped). */
+  urlResolve(bases: Uint8Array[], references: Uint8Array[]): Uint8Array[]
+  /** Sign N JSON claim documents (packed → signed tokens). */
+  jwtSign(
+    items: Uint8Array[],
+    secret: Uint8Array,
+    ttlSeconds?: number | null,
+    nowSeconds?: number,
+  ): Uint8Array[]
+  /** Encode N SSE events with shared event/id/retry. */
+  sseEncode(
+    items: Uint8Array[],
+    event?: string | null,
+    id?: string | null,
+    retry?: number | null,
+  ): Uint8Array[]
+  /** Encode N frames (same opcode/mask/fin) from payloads. */
+  wsFrameEncode(items: Uint8Array[], opcode: number, mask: boolean, fin: boolean): Uint8Array[]
+  /** Decode N frames → payloads (opcodes/flags dropped; failed items → empty). */
+  wsFrameDecode(items: Uint8Array[]): Uint8Array[]
+  /** Parse N multipart bodies → array of parts per item (same boundary). */
+  multipartParse(items: Uint8Array[], boundary: Uint8Array): MultipartPart[][]
+  /**
+   * @performance Template render: ~1.7x slower than the JS baseline (1/3 tasks failed) [check:annotate]
+   * @deprecated Slower than the native JS baseline (~1.7x) — prefer the JS/Bun baseline. [check:annotate]
+   * @remarks Promotion candidate: 2/3 benchmarks won in the latest run (static: not-competitive). [check:annotate]
+   * @remarks The allocating render marshals the context via napi DOM (~1.5x loss). Use TemplateRenderer.renderBytes (JSON-bytes context) which avoids it and wins ~1.37x. [check:annotate]
+   */
+  templateRender(source: string, contexts: Uint8Array[]): Uint8Array[]
+}
+
+// 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 the `batch` namespace for a client context. */
+export function buildBatch(ctx: RustClientContext): RustBatch {
+  return {
+    jsonValid(items) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'jsonValidBatchPacked')(packed) as Buffer),
+      )
+    },
+    crc32(items) {
+      return withPackScratch(items, (packed) =>
+        unpackU32Array(nativeFn(ctx, 'crc32BatchPacked')(packed) as Buffer),
+      )
+    },
+    validateEmail(items) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'validateEmailBatchPacked')(packed) as Buffer),
+      )
+    },
+    validateUuid(items) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'validateUuidBatchPacked')(packed) as Buffer),
+      )
+    },
+    validateIpv4(items) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'validateIpv4BatchPacked')(packed) as Buffer),
+      )
+    },
+    validateIpv6(items) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'validateIpv6BatchPacked')(packed) as Buffer),
+      )
+    },
+    jsonSumIds(items) {
+      return withPackScratch(items, (packed) =>
+        unpackI64ArrayAsBigInt(nativeFn(ctx, 'jsonSumBatchPacked')(packed) as Buffer),
+      )
+    },
+    queryParse(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'queryParseBatchPacked')(packed) as Buffer),
+      )
+    },
+    cookieParse(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'cookieParseBatchPacked')(packed) as Buffer),
+      )
+    },
+    formParse(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'formParseBatchPacked')(packed) as Buffer),
+      )
+    },
+    signCookie(items, secret) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'signCookieBatchPacked')(packed, secret) as Buffer),
+      )
+    },
+    verifyCookie(items, secret) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'verifyCookieBatchPacked')(packed, secret) as Buffer),
+      )
+    },
+    csrfVerify(items, secret) {
+      return withPackScratch(items, (packed) =>
+        unpackBitset(nativeFn(ctx, 'csrfVerifyBatchPacked')(packed, secret) as Buffer),
+      )
+    },
+    httpParseRequest(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'httpParseRequestBatchPacked')(packed) as Buffer),
+      )
+    },
+    fnv1a64(items) {
+      return withPackScratch(items, (packed) =>
+        unpackU64ArrayAsBigInt(nativeFn(ctx, 'fnv1A64BatchPacked')(packed) as Buffer),
+      )
+    },
+    etag(items, weak) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'etagBatchPacked')(packed, weak ?? null) as Buffer),
+      )
+    },
+    urlEncode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'urlEncodeBatchPacked')(packed) as Buffer),
+      )
+    },
+    urlDecode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'urlDecodeBatchPacked')(packed) as Buffer),
+      )
+    },
+    urlDecodeBytes(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'urlDecodeBytesBatchPacked')(packed) as Buffer),
+      )
+    },
+    mimeFromExtension(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'mimeFromExtensionBatchPacked')(packed) as Buffer),
+      )
+    },
+    wsAcceptKey(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'wsAcceptKeyBatchPacked')(packed) as Buffer),
+      )
+    },
+    base64UrlEncode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'base64EncodeBatchPacked')(packed, true, false) as Buffer),
+      )
+    },
+    base64UrlDecode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'base64DecodeBatchPacked')(packed, true, false) as Buffer),
+      )
+    },
+    jsonPatch(docs, patches) {
+      return withPackScratch2(docs, patches, (packedDocs, packedPatches) =>
+        unpackByteResults(
+          nativeFn(ctx, 'jsonPatchBatchPacked')(packedDocs, packedPatches) as Buffer,
+        ),
+      )
+    },
+    hexEncode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'hexEncodeBatchPacked')(packed) as Buffer),
+      )
+    },
+    hexDecode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'hexDecodeBatchPacked')(packed) as Buffer),
+      )
+    },
+    base64Encode(items, urlSafe, padding) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'base64EncodeBatchPacked')(
+            packed,
+            urlSafe ?? null,
+            padding ?? null,
+          ) as Buffer,
+        ),
+      )
+    },
+    base64Decode(items, urlSafe, padding) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'base64DecodeBatchPacked')(
+            packed,
+            urlSafe ?? null,
+            padding ?? null,
+          ) as Buffer,
+        ),
+      )
+    },
+    schemaValidate(validator, items) {
+      return schemaValidateBatch(validator, items)
+    },
+    schemaValidateCount(validator, items) {
+      return schemaValidateBatchCount(validator, items)
+    },
+
+    // ── Backend-framework features ──
+    passwordHash(password, salt, options) {
+      return withPackScratch(password, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'passwordHashBatchPacked')(packed, salt, options ?? null) as Buffer,
+        ),
+      )
+    },
+    aeadEncrypt(key, nonce, items, algorithm) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'aeadEncryptBatchPacked')(packed, key, nonce, algorithm ?? null) as Buffer,
+        ),
+      )
+    },
+    aeadDecrypt(key, nonce, items, algorithm) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'aeadDecryptBatchPacked')(packed, key, nonce, algorithm ?? null) as Buffer,
+        ),
+      )
+    },
+    gzipCompress(items, level) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'gzipCompressBatchPacked')(packed, level ?? null) as Buffer,
+        ),
+      )
+    },
+    gzipDecompress(items, maxDecompressed) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'gzipDecompressBatchPacked')(packed, maxDecompressed ?? null) as Buffer,
+        ),
+      )
+    },
+    brotliCompress(items, quality) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'brotliCompressBatchPacked')(packed, quality ?? null) as Buffer,
+        ),
+      )
+    },
+    brotliDecompress(items, maxDecompressed) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'brotliDecompressBatchPacked')(packed, maxDecompressed ?? null) as Buffer,
+        ),
+      )
+    },
+    jwtVerify(tokens, secret, nowSeconds) {
+      return withPackScratch(tokens, (packed) =>
+        unpackBitset(nativeFn(ctx, 'jwtVerifyBatchPacked')(packed, secret, nowSeconds) as Buffer),
+      )
+    },
+    hmacSha256(items, key) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'hmacSha256BatchPacked')(packed, key) as Buffer),
+      )
+    },
+    hmacSha256Verify(items, sigs, key) {
+      return withPackScratch2(items, sigs, (packedItems, packedSigs) =>
+        unpackBitset(
+          nativeFn(ctx, 'hmacSha256VerifyBatchPacked')(packedItems, packedSigs, key) as Buffer,
+        ),
+      )
+    },
+    templateRender(source, contexts) {
+      return withPackScratch(contexts, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'templateRenderBatchPacked')(packed, source) as Buffer),
+      )
+    },
+    passwordVerify(items, phcs) {
+      return withPackScratch2(items, phcs, (packedItems, packedPhcs) =>
+        unpackBitset(nativeFn(ctx, 'passwordVerifyBatchPacked')(packedItems, packedPhcs) as Buffer),
+      )
+    },
+    urlResolve(bases, references) {
+      return withPackScratch2(bases, references, (packedBases, packedRefs) =>
+        unpackByteResults(
+          nativeFn(ctx, 'urlResolveBatchPacked')(packedBases, packedRefs) as Buffer,
+        ),
+      )
+    },
+    jwtSign(items, secret, ttlSeconds, nowSeconds) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'jwtSignBatchPacked')(
+            packed,
+            secret,
+            ttlSeconds ?? null,
+            nowSeconds ?? Math.floor(Date.now() / 1000),
+          ) as Buffer,
+        ),
+      )
+    },
+    sseEncode(items, event, id, retry) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'sseEncodeBatchPacked')(
+            packed,
+            event ?? null,
+            id ?? null,
+            retry ?? null,
+          ) as Buffer,
+        ),
+      )
+    },
+    wsFrameEncode(items, opcode, mask, fin) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(
+          nativeFn(ctx, 'wsFrameEncodeBatchPacked')(packed, opcode, mask, fin) as Buffer,
+        ),
+      )
+    },
+    wsFrameDecode(items) {
+      return withPackScratch(items, (packed) =>
+        unpackByteResults(nativeFn(ctx, 'wsFrameDecodeBatchPacked')(packed) as Buffer),
+      )
+    },
+    multipartParse(items, boundary) {
+      return withPackScratch(items, (packed) =>
+        unpackMultipartParts(
+          nativeFn(ctx, 'multipartParseBatchPacked')(packed, boundary) as Buffer,
+        ),
+      )
+    },
+  }
+}

package/src/rust-ffi/client.ts

@@ -0,0 +1,88 @@
+// 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 { createContext } from './context'
+import { buildText, type RustText } from './text'
+import { buildBatch, type RustBatch } from './batch'
+import { buildPacked, type RustPacked } from './packed'
+import { buildScalar, type RustScalar } from './scalar'
+import { getBunFFI } from '../native/ffi'
+import type { RustOptions } from './options'
+
+/** 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 getBunFFI() !== null ? 'ffi' : 'napi'
+    },
+    ffiActive() {
+      return getBunFFI() !== null
+    },
+
+    // ── 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,164 @@
+// 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 { addon } from './addon'
+import { resolveRayonThreads } from './options'
+import { normalizeExt } from './options'
+import type { RustOptions } from './options'
+import type { HmacSignerInstance } from '../native'
+
+// 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 addon function on first use and cache it for all subsequent
+ * calls. 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) {
+    f = (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).
+ */
+export function resolvePoolNative(
+  ctx: RustClientContext,
+  name: string,
+): (...args: unknown[]) => unknown {
+  let f = nativeFnCache.get(name)
+  if (f === undefined) {
+    ctx.ensurePool()
+    f = (ctx.addon as unknown as Record<string, unknown>)[name]
+    nativeFnCache.set(name, f)
+  }
+  return f as (...args: unknown[]) => unknown
+}
+
+/** Shared per-instance state passed to the namespace/scalar builders. */
+export interface RustClientContext {
+  /** The shared lazy addon proxy. */
+  addon: typeof addon
+  /** 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,
+    state,
+    mimeByText,
+    hmacSigners,
+    ensurePool,
+    isPoolInitialized,
+    setPendingThreads,
+    markPoolInitialized,
+    cachedMime,
+    hmacSigner,
+  }
+}