castrum 0.9.4 → 0.9.6

package/src/native/ffi/build.ts

@@ -16,6 +16,7 @@ import { buildCompress } from './build/compress'
 import { buildInstances } from './build/instances'
 import { buildMetrics } from './build/metrics'
 import { buildParse } from './build/parse'
+import { buildTask } from './build/task'
 import type { BuildCtx } from './build/util'
 import type { BunFFI } from './types'
 
@@ -92,5 +93,6 @@ export function build(
     ...buildParse(sym, ctx),
     ...buildInstances(sym, ctx),
     ...buildMetrics(sym, ctx),
+    ...buildTask(sym, ctx),
   } as BunFFI
 }

package/src/native/ffi/selftest.ts

@@ -15,6 +15,7 @@ import { selfTestCompress } from './build/compress'
 import { selfTestInstances } from './build/instances'
 import { selfTestMetrics } from './build/metrics'
 import { selfTestParse } from './build/parse'
+import { selfTestTask } from './build/task'
 import type { BunFFI } from './types'
 
 /** Verify every bound function against known-good results; false disables ffi. */
@@ -24,6 +25,7 @@ export function selfTest(b: BunFFI): boolean {
     selfTestCompress(b) &&
     selfTestParse(b) &&
     selfTestInstances(b) &&
-    selfTestMetrics(b)
+    selfTestMetrics(b) &&
+    selfTestTask(b)
   )
 }

package/src/native/ffi/types.ts

@@ -218,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). */
@@ -488,6 +494,40 @@ export interface BunFFI {
    * 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
 }
 
 /**

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
@@ -209,6 +230,14 @@ function bind(): BunFFI | null {
       // 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' },
@@ -547,6 +576,27 @@ function bind(): BunFFI | null {
         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' },
     })
 
@@ -557,20 +607,29 @@ function bind(): BunFFI | null {
       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/loader.ts

@@ -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/rust-ffi/scalar/http.ts

@@ -11,12 +11,19 @@
 
 import type { EncodingPrefResult, MediaTypeResult } from '../../native'
 import type { BunFFI } from '../../native/ffi'
-import { decoder } from '../../shared/bytes'
+import { decoder, hasNul } from '../../shared/bytes'
 import { decodeUtf8Fatal, decodeUtf8Range } from '../../shared/codec'
 import { packPairs } from '../../shared/packed'
 import { memoizeFfi, type RustClientContext, resolveNative } from '../context'
 import { writeInto } from '../into'
 
+/**
+ * RFC 6455 `Sec-WebSocket-Accept` is always 28 chars. Reused across calls
+ * because the value is decoded to a string synchronously before returning —
+ * the same discipline as the other pooled scratches in this layer.
+ */
+const WS_ACCEPT_SCRATCH = new Uint8Array(64)
+
 // Mirror napi `url_decode`'s UTF-8 validation (rust/http/url_codec.rs): only
 // validate when a high byte is present (the ASCII fast path skips it — same as
 // Rust's saw_high check). On the Bun path the check is a native C-ABI probe
@@ -144,11 +151,22 @@ export function buildHttp(ctx: RustClientContext) {
 
   return {
     mimeFromExtension(ext: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi keeps the memoized-bytes
-      // path (cachedMime).
+      // FFI-first. This op has no `*_bytes` sibling, so the bytes must be decoded
+      // for the `cstring` ARG — the decode is the price of the cstring form, not
+      // a speed trick (route new byte-shaped ops to a byte sibling instead; see
+      // docs/FFI_BUN_GUIDE.md §6.1). napi keeps the memoized-bytes path
+      // (cachedMime).
+      //
+      // A NUL would truncate the DECODED string native-side, so `.js\0evil`
+      // would resolve as `.js` — a Content-Type from a prefix. An extension
+      // containing a NUL is not an extension, so it takes the unknown sentinel
+      // (the guard is `indexOf` on an already-decoded string: ~4 ns).
       const f = ffi()
-      if (f) return f.mimeFromExtension(decoder.decode(ext)) ?? 'application/octet-stream'
+      if (f) {
+        const name = decoder.decode(ext)
+        if (hasNul(name)) return 'application/octet-stream'
+        return f.mimeFromExtension(name) ?? 'application/octet-stream'
+      }
       return ctx.cachedMime(ext)
     },
     urlEncode(input: Uint8Array): Uint8Array | string {
@@ -188,34 +206,54 @@ export function buildHttp(ctx: RustClientContext) {
       return n('urlDecodeInto')(input, output) as number
     },
     validateEmail(input: Uint8Array): boolean {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call — still faster than the old
-      // `(ptr,len)` view path (see bench:margin cstring scenario). napi
-      // fallback keeps the byte path.
+      // FFI-first. The bytes cross as a `buffer`/`buffer_length` pair (an atomic
+      // ptr+len snapshot, zero transcode) rather than being decoded to a JS
+      // string for the `cstring` ARG. Measured on Bun 1.4.2 over 400k calls:
+      // 101 ns vs 234 ns (email), 65 vs 164 (uuid), 31 vs 138 (ipv4) — and the
+      // byte form cannot truncate at an embedded NUL the way a cstring ARG
+      // does (a NUL byte used to make "a@b.com\0<script>" validate as TRUE).
       const f = ffi()
-      if (f) return f.validateEmail(decoder.decode(input))
+      if (f) return f.validateEmailBytes(input)
       return n('validateEmail')(input) as boolean
     },
     validateUuid(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateUuid(decoder.decode(input))
+      if (f) return f.validateUuidBytes(input)
       return n('validateUuid')(input) as boolean
     },
     validateIpv4(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv4(decoder.decode(input))
+      if (f) return f.validateIpv4Bytes(input)
       return n('validateIpv4')(input) as boolean
     },
     validateIpv6(input: Uint8Array): boolean {
       const f = ffi()
-      if (f) return f.validateIpv6(decoder.decode(input))
+      if (f) return f.validateIpv6Bytes(input)
       return n('validateIpv6')(input) as boolean
     },
     wsAcceptKey(key: Uint8Array): Uint8Array | string {
-      // FFI-first: the `cstring` ARG is string-only, so bytes are decoded once
-      // (cheap CString clone) before the call. napi fallback keeps the bytes.
+      // FFI-first: the `cstring` ARG + cstring return is the fast path (no JS
+      // encode, engine-cloned result) — end-to-end it measures ~367 ns, while
+      // routing every call through the byte sibling costs ~381 ns (the extra
+      // `subarray` + decode outweighs the transcode saved; measured over 300k
+      // calls on Bun 1.4.2 through THIS function, not the raw binding).
+      //
+      // Correctness rider: a NUL would truncate the `cstring` ARG, so the accept
+      // value would be computed for a PREFIX of the key — verified:
+      // `'dGhlIHNhbXBsZSBub25jZQ==\0junk'` returned exactly the value for the
+      // key WITHOUT the suffix. That case takes the byte sibling (exact length).
       const f = ffi()
-      if (f) return f.wsAcceptKey(decoder.decode(key))
+      if (f) {
+        const text = decoder.decode(key)
+        if (!hasNul(text)) return f.wsAcceptKey(text)
+        const w = f.wsAcceptKeyInto(key, WS_ACCEPT_SCRATCH)
+        if (w > 0 && w <= WS_ACCEPT_SCRATCH.length) {
+          return decoder.decode(WS_ACCEPT_SCRATCH.subarray(0, w))
+        }
+        // Unreachable for a live view (the native side writes 28 for any key);
+        // the napi path is byte-exact, so it can never resurrect truncation.
+        return n('wsAcceptKey')(key) as Uint8Array | string
+      }
       return n('wsAcceptKey')(key) as Uint8Array | string
     },
     wsAcceptKeyInto(key: Uint8Array, output: Uint8Array): number {

package/src/rust-ffi/text.ts

@@ -1,16 +1,27 @@
 // src/rust-ffi/text.ts — String-oriented FFI namespace (text in → text out).
 //
 // `rust.text.*` is the ergonomic string API over the byte-level native
-// functions. Pure wrappers: encode input, call native, decode output.
+// functions. MOST of it is FFI-first with `cstring` args/returns: the engine
+// transcodes a JS string in-call, so there is no JS-side encode at all (and
+// byte-arg ops are not involved). Encode/decode wrappers exist only for the
+// napi fallback and for ops with no cstring form — plus a NUL guard wherever a
+// `cstring` ARG could truncate a verdict or a byte-exact value
+// (docs/FFI_BUN_GUIDE.md §6.1).
 //
 // Runtime dispatch is centralized in the adapter (`ctx.runtime`): the Bun
 // built-in delegations (urlEncode/urlDecode) come from `builtins.has(op)` and
 // the native call from `transport.ffi` / `transport.resolve` (bun:ffi first,
 // napi fallback) — no inline `isBun()` / `getBunFFI()`.
 
-import { decoder, encoder } from '../shared/bytes'
+import { decoder, encoder, hasNul } from '../shared/bytes'
 import { type RustClientContext, resolveNative } from './context'
 
+/**
+ * Scratch for the byte-path `Sec-WebSocket-Accept` fallback (28 chars; the
+ * NUL case only). Decoded synchronously before returning, so reuse is safe.
+ */
+const WS_ACCEPT_OUT = new Uint8Array(64)
+
 /** String-oriented FFI namespace. */
 export interface RustText {
   /**
@@ -91,8 +102,19 @@ export function buildText(ctx: RustClientContext): RustText {
       // FFI-first: `cstring` ARG + cstring return (native transfer both ways —
       // the engine transcodes the key in-engine, no JS encode). napi keeps the
       // encode/decode path.
+      //
+      // Exception: a NUL would truncate the `cstring` ARG, so the accept value
+      // would be computed for a PREFIX of the key. Encode and take the byte path
+      // in that (practically unreachable) case: still a wrong key for a client
+      // that sent a NUL, but wrong for the bytes the caller actually passed.
       const f = transport.ffi
-      if (f) return f.wsAcceptKey(key)
+      if (f) {
+        if (!hasNul(key)) return f.wsAcceptKey(key)
+        const w = f.wsAcceptKeyInto(encoder.encode(key), WS_ACCEPT_OUT)
+        return w > 0 && w <= WS_ACCEPT_OUT.length
+          ? decoder.decode(WS_ACCEPT_OUT.subarray(0, w))
+          : ''
+      }
       return decoder.decode(resolveNative(ctx, 'wsAcceptKey')(encoder.encode(key)) as Uint8Array)
     },
     validateEmail(input) {

package/src/shared/bytes.ts

@@ -134,3 +134,22 @@ export function toPlainBuffer(bytes: Uint8Array): Uint8Array {
   copy.set(bytes)
   return copy
 }
+
+/**
+ * Does this string contain a NUL (`U+0000`)?
+ *
+ * `bun:ffi` transcodes a JS string passed to a `cstring` ARG into a
+ * NUL-TERMINATED UTF-8 buffer, so an embedded NUL SILENTLY TRUNCATES the value
+ * natively (Bun's docs describe the transcode; the truncation is the C
+ * convention it inherits). That is fine for developer-supplied config, and a
+ * real bug wherever the callee answers with a VERDICT (a truncated prefix
+ * passes where the full input fails) or where the exact bytes ARE the result.
+ *
+ * Cheap: one `indexOf` scan, ~4 ns for typical inputs.
+ *
+ * @param s - The string to check.
+ * @returns `true` when a NUL is present.
+ */
+export function hasNul(s: string): boolean {
+  return s.indexOf('\u0000') !== -1
+}

package/src/task/index.ts

@@ -0,0 +1,24 @@
+// src/task/index.ts — public barrel for the off-thread task runtime.
+
+export {
+  TASK_OP,
+  TASK_STATUS_CANCELLED,
+  TASK_STATUS_ERROR,
+  TASK_STATUS_OK,
+  brotliCapacityGuess,
+  encodeArgon2VerifyArgs,
+  encodeBrotliDecompressArgs,
+  encodeGzipCompressHeader,
+  encodeGzipDecompressArgs,
+  encodePbkdf2Args,
+  gzipCompressUpperBound,
+} from './op'
+export type { TaskOpName } from './op'
+export { createTaskRuntime } from './runtime'
+export type {
+  Pbkdf2RunOptions,
+  TaskRunOptions,
+  TaskRuntime,
+  TaskRuntimeOptions,
+  TaskStats,
+} from './runtime'