castrum 0.9.7 → 0.9.9

package/src/shared/buffer-pool.ts

@@ -39,6 +39,21 @@
    * converge on one buffer size instead of re-growing each time. Default false.
    */
   adaptive?: boolean
+  /**
+   * Number of buffers (beyond the initial one) to ALLOCATE UP FRONT at
+   * construction, so a burst-ramp (e.g. a load-test connection flood) never
+   * pays per-request `new Uint8Array` + GC during its first wave. A pure
+   * memory-for-latency trade: retained memory becomes `prefill + 1` ×
+   * `initialSize` (still bounded by `maxBuffers`). Default 0.
+   */
+  prefill?: number
+  /**
+   * Byte budget for `prefill`: the prefilled count is additionally capped to
+   * `floor(prefillBytes / initialSize)`, so a large `initialSize` (e.g. a
+   * 64 MiB output buffer) cannot multiply into gigabytes when a router creates
+   * one pool per route. Default `Infinity` (only `prefill`/`maxBuffers` apply).
+   */
+  prefillBytes?: number
 }
 
 /** A borrowed buffer handle handed out by a pool; `release()` returns it. */
@@ -138,6 +153,22 @@ export class BufferPool {
         : null
     this.free.push(new Uint8Array(this.initialSize))
     this.created = 1
+    // Pre-fill (memory-for-latency trade, see `prefill` in BufferPoolOptions):
+    // spend up-front allocation so a burst ramp never allocates during its
+    // first wave. Capped at maxBuffers so the documented retention bound
+    // (free list ≤ maxBuffers) still holds, and by `prefillBytes` so a large
+    // `initialSize` cannot multiply into an unbounded up-front allocation.
+    const prefill = Math.min(
+      Math.max(0, Math.floor(options.prefill ?? 0)),
+      this.maxBuffers - 1,
+      options.prefillBytes !== undefined
+        ? Math.max(0, Math.floor(options.prefillBytes / this.initialSize))
+        : Number.POSITIVE_INFINITY,
+    )
+    for (let i = 0; i < prefill; i++) {
+      this.free.push(new Uint8Array(this.initialSize))
+      this.created++
+    }
   }
 
   /** Number of buffers currently available for immediate reuse. */
@@ -150,6 +181,16 @@ export class BufferPool {
     return this.created
   }
 
+  /**
+   * Drop every retained free buffer. In-flight (borrowed) buffers are
+   * unaffected and return to an empty pool on `release()`, so the next
+   * `acquire()` allocates (or grows) as needed. Used by an explicit memory
+   * flush; the pool stays fully functional afterwards.
+   */
+  shrink(): void {
+    this.free.length = 0
+  }
+
   /**
    * Acquire a buffer of at least `minSize` bytes. The returned handle must be
    * released (directly, or via a zero-copy Response) once the caller is done.
@@ -204,11 +245,14 @@ export class BufferPool {
     // Learn the observed demand so future allocations pre-size to it.
     this.estimate?.sample(minSize)
 
-    // 1) Reuse a free buffer that is already large enough.
+    // 1) Reuse a free buffer that is already large enough. Free-list ORDER is
+    //    irrelevant, so remove by swap-with-last (O(1), no splice compaction/
+    //    allocation) — this is a per-request hot path.
     for (let i = 0; i < this.free.length; i++) {
       const candidate = this.free[i] as Uint8Array
       if (candidate.byteLength >= minSize) {
-        this.free.splice(i, 1)
+        const last = this.free.pop() as Uint8Array
+        if (i < this.free.length) this.free[i] = last
         return candidate
       }
     }
@@ -227,7 +271,8 @@ export class BufferPool {
       }
     }
     if (largestBuf !== null) {
-      this.free.splice(largest, 1)
+      const last = this.free.pop() as Uint8Array
+      if (largest < this.free.length) this.free[largest] = last
       this.created++
       return new Uint8Array(target)
     }
@@ -241,16 +286,16 @@ export class BufferPool {
   private releaseBuffer(buffer: Uint8Array): void {
     if (this.free.length >= this.maxBuffers) {
       // Free list is full: drop the smallest retained buffer to stay bounded.
-      let smallestBuf: Uint8Array | null = null
       let smallest = 0
-      for (let i = 0; i < this.free.length; i++) {
-        const candidate = this.free[i] as Uint8Array
-        if (smallestBuf === null || candidate.byteLength < smallestBuf.byteLength) {
-          smallestBuf = candidate
+      for (let i = 1; i < this.free.length; i++) {
+        if (
+          (this.free[i] as Uint8Array).byteLength < (this.free[smallest] as Uint8Array).byteLength
+        ) {
           smallest = i
         }
       }
-      this.free.splice(smallest, 1)
+      const last = this.free.pop() as Uint8Array
+      if (smallest < this.free.length) this.free[smallest] = last
     }
     this.free.push(buffer)
   }

package/src/shared/codec.ts

@@ -79,6 +79,32 @@ export const decodeUtf8: (bytes: Uint8Array) => string = runtimeCodec.decodeUtf8
 export const decodeUtf8Range: (bytes: Uint8Array, start: number, end: number) => string =
   runtimeCodec.decodeUtf8Range
 
+/**
+ * Decode a range of a PREPARED bounded Buffer `view` (absolute offsets into
+ * the view) to a string — replacement mode on invalid. Companion to
+ * `decodeUtf8Range` for packed-wire unpackers that decode MANY fields from
+ * ONE packed result: the caller resolves the Buffer view once and every field
+ * decode skips the per-field cache lookup + offset arithmetic.
+ *
+ * Falls back to `decodeUtf8Range` when the runtime codec does not provide the
+ * view variant (older adapters / custom codecs).
+ *
+ * @param view - A bounded Buffer over the packed bytes.
+ * @param start - Range start (inclusive, relative to the view).
+ * @param end - Range end (exclusive, relative to the view).
+ * @returns The decoded string.
+ *
+ * @example
+ * ```ts
+ * const view = Buffer.from(packed.buffer, packed.byteOffset, packed.byteLength)
+ * decodeUtf8RangeView(view, 4, 24) // → 'multipart/form-data'
+ * ```
+ */
+export const decodeUtf8RangeView: (view: Buffer, start: number, end: number) => string =
+  runtimeCodec.decodeUtf8RangeView
+    ? runtimeCodec.decodeUtf8RangeView
+    : (view, start, end) => decodeUtf8Range(view, start, end)
+
 /**
  * Decode UTF-8 bytes to a string, throwing on invalid UTF-8.
  *

package/src/shared/memory.ts

@@ -0,0 +1,68 @@
+// src/shared/memory.ts — Public memory-flush escape hatch.
+//
+// Impure boundary module: it owns no state of its own but reaches the cache
+// owners (the global loader LRU and the process-wide MIME caches) to drop their
+// retained entries, then optionally requests a runtime GC. The metrics registry
+// is deliberately NOT flushed — an observability registry is not a cache, and
+// clearing it would erase the counters an operator is watching.
+
+import { loader } from '../loader'
+import { rust } from '../rust-ffi'
+import { clearMimeCaches } from '../rust-ffi/context'
+import { forceGc } from './runtime'
+
+/** Options for {@link flushMemory}. */
+export interface FlushMemoryOptions {
+  /**
+   * When true (the default), also request a full garbage collection from the
+   * runtime: `Bun.gc(true)` on Bun, `globalThis.gc?.()` on Node when the
+   * process runs with `--expose-gc`. Set false to flush caches only.
+   */
+  gc?: boolean
+}
+
+/**
+ * Flush process-level caches and (by default) request a full GC. Intended for
+ * explicit memory-pressure handling — e.g. after a burst or before a snapshot.
+ *
+ * Clears:
+ * - the global loader LRU cache (`loader.clear()`),
+ * - the process-wide MIME caches (`clearMimeCaches()`),
+ * - the native compiled-schema cache (`rust.clearSchemaCache()`).
+ *
+ * The metrics registry is intentionally left untouched.
+ *
+ * Idempotent, and safe to call before the native addon has ever been loaded
+ * (every cache starts empty, the loader cache is a plain Map, and the native
+ * schema-cache clear is a defensive no-op when the addon/symbol is absent).
+ *
+ * @param options - `gc: false` skips the runtime GC request. Defaults to `{}`
+ *   (GC requested).
+ * @example
+ * ```ts
+ * import { flushMemory } from 'castrum'
+ *
+ * flushMemory()            // drop caches + request GC
+ * flushMemory({ gc: false }) // drop caches only
+ * ```
+ */
+export function flushMemory(options: FlushMemoryOptions = {}): void {
+  // Global loader LRU (createLoader() instances own their own caches and are
+  // not registered globally — flush the shared singleton only).
+  loader.clear()
+
+  // Process-wide MIME caches (bytes + string forms).
+  clearMimeCaches()
+
+  // Process-wide native compiled-schema cache. Defensive: an absent or stale
+  // addon (no `clearSchemaCache` symbol) must be a no-op, never a throw.
+  try {
+    rust.clearSchemaCache()
+  } catch {
+    // addon not loaded / stale build — nothing to clear.
+  }
+
+  if (options.gc !== false) {
+    forceGc()
+  }
+}

package/src/shared/metrics.ts

@@ -12,6 +12,27 @@ export const DEFAULT_BUCKETS: readonly number[] = [
   0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
 ]
 
+/**
+ * Per-family cap on the number of distinct label sets (series) retained by a
+ * single counter/gauge/histogram. A metrics registry is keyed by caller-supplied
+ * label values, so an unbounded label (e.g. a raw path or user id) would grow a
+ * `Map` without limit. At the cap the oldest half of that family is evicted
+ * (insertion order) and the count is accumulated into the synthetic counter
+ * `castrum_metrics_series_dropped_total`, making the loss observable instead of
+ * silent. That name is RESERVED — a caller declaring a counter/gauge/histogram
+ * with it suppresses the synthetic emission (see {@link SERIES_DROPPED_METRIC}).
+ */
+export const MAX_SERIES_PER_METRIC = 10_000
+
+/**
+ * Reserved exposition name of the synthetic counter reporting series evicted by
+ * {@link MAX_SERIES_PER_METRIC}. Callers must not register a metric family with
+ * this name; if one exists, `render()` skips the synthetic emission so the
+ * scrape never carries two `# HELP`/`# TYPE` lines for one family (Prometheus
+ * rejects that).
+ */
+const SERIES_DROPPED_METRIC = 'castrum_metrics_series_dropped_total'
+
 type LabelValues = readonly string[]
 type Labels = Readonly<Record<string, string>>
 
@@ -29,6 +50,24 @@ function escapeLabel(v: string): string {
   return v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')
 }
 
+/**
+ * Once a series map is at {@link MAX_SERIES_PER_METRIC}, evict its oldest half
+ * (insertion order) and return the keys dropped; returns `[]` below the cap.
+ * Mirrors Elysia's `evictOldestHalf` generational policy: halving at the cap
+ * amortizes the eviction cost instead of paying a delete per insertion.
+ */
+function evictOldestHalf<K, V>(map: Map<K, V>): K[] {
+  if (map.size < MAX_SERIES_PER_METRIC) return []
+  const drop = Math.ceil(map.size / 2)
+  const dropped: K[] = []
+  for (const key of map.keys()) {
+    if (dropped.length >= drop) break
+    dropped.push(key)
+  }
+  for (const key of dropped) map.delete(key)
+  return dropped
+}
+
 /** A single labelled counter value. */
 export interface Counter {
   /** Increment by 1 (or `by`). `labels` must match the label names exactly. */
@@ -97,6 +136,8 @@ export function createMetrics(): MetricsRegistry {
   const counters = new Map<string, CounterEntry>()
   const gauges = new Map<string, GaugeEntry>()
   const histograms = new Map<string, HistogramEntry>()
+  /** Series evicted by the per-family cardinality cap, rendered as a counter. */
+  let seriesDropped = 0
 
   const bucketUpper = (buckets: number[]): number[] => [
     ...buckets.map((b) => b),
@@ -144,6 +185,22 @@ export function createMetrics(): MetricsRegistry {
     for (const e of counters.values()) out.push(...renderCounter(e))
     for (const e of gauges.values()) out.push(...renderGauge(e))
     for (const e of histograms.values()) out.push(...renderHistogram(e))
+    // Only emitted once a family has actually overflowed, so the output for a
+    // well-behaved registry is byte-identical to before the cap existed. Guard
+    // against a caller-registered family of the same (reserved) name — two
+    // `# HELP`/`# TYPE` lines for one family make the scrape invalid.
+    if (
+      seriesDropped > 0 &&
+      !counters.has(SERIES_DROPPED_METRIC) &&
+      !gauges.has(SERIES_DROPPED_METRIC) &&
+      !histograms.has(SERIES_DROPPED_METRIC)
+    ) {
+      out.push(
+        `# HELP ${SERIES_DROPPED_METRIC} Total metric series evicted by the per-family cardinality cap.`,
+      )
+      out.push(`# TYPE ${SERIES_DROPPED_METRIC} counter`)
+      out.push(`${SERIES_DROPPED_METRIC} ${seriesDropped}`)
+    }
     return `${out.join('\n')}\n`
   }
 
@@ -151,6 +208,7 @@ export function createMetrics(): MetricsRegistry {
     counters.clear()
     gauges.clear()
     histograms.clear()
+    seriesDropped = 0
   }
 
   return {
@@ -172,7 +230,14 @@ export function createMetrics(): MetricsRegistry {
             names,
             names.map((n) => labels?.[n] ?? ''),
           )
-          entry.values.set(key, (entry.values.get(key) ?? 0) + by)
+          const prev = entry.values.get(key)
+          if (prev === undefined) {
+            // New series: make room first (bounded family) and count evictions.
+            seriesDropped += evictOldestHalf(entry.values).length
+            entry.values.set(key, by)
+          } else {
+            entry.values.set(key, prev + by)
+          }
         },
       }
     },
@@ -192,14 +257,27 @@ export function createMetrics(): MetricsRegistry {
           names,
           names.map((n) => labels?.[n] ?? ''),
         )
+      const add = (labels: Labels | undefined, delta: number): void => {
+        const key = keyOf(labels)
+        const prev = entry.values.get(key)
+        if (prev === undefined) {
+          seriesDropped += evictOldestHalf(entry.values).length
+          entry.values.set(key, delta)
+        } else {
+          entry.values.set(key, prev + delta)
+        }
+      }
       return {
         inc(labels, by = 1) {
-          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) + by)
+          add(labels, by)
         },
         dec(labels, by = 1) {
-          entry.values.set(keyOf(labels), (entry.values.get(keyOf(labels)) ?? 0) - by)
+          add(labels, -by)
         },
         set(labels, value) {
+          if (!entry.values.has(keyOf(labels))) {
+            seriesDropped += evictOldestHalf(entry.values).length
+          }
           entry.values.set(keyOf(labels), value)
         },
       }
@@ -225,6 +303,11 @@ export function createMetrics(): MetricsRegistry {
           )
           let counts = entry.counts.get(key)
           if (!counts) {
+            // New series: bound the family and drop the matching sum entries
+            // (counts and sums always share the same key set).
+            const dropped = evictOldestHalf(entry.counts)
+            for (const k of dropped) entry.sums.delete(k)
+            seriesDropped += dropped.length
             // One slot per bucket PLUS the implicit +Inf slot.
             counts = new Array<number>(entry.buckets.length + 1).fill(0)
             entry.counts.set(key, counts)

package/src/shared/packed/parsers.ts

@@ -4,28 +4,85 @@
 // don't have to hand-pack buffers or decode packed pairs:
 //   parseQueryString("a=1&b=2")    // { a: "1", b: "2" }
 //   parseCookieHeader("a=1; b=2")  // { a: "1", b: "2" }
+//
+// Transport: bun:ffi PRIMARY — the packed pairs are consumed SYNCHRONOUSLY
+// (readPairsPacked + pairsToObject materialize strings before return), so a
+// reused per-parser scratch is safe (same model as the scalar unpackers);
+// the bytes never escape. Node / `CASTRUM_FFI_MODE=napi` / bind failure fall
+// back to the napi addon (same wire output — pinned by packed-parsers-routing).
 
+import { getBunFFI } from '../../native/ffi'
 import { getAddon, lazyAddon } from '../../native'
 import { encoder } from '../bytes'
 import { pairsToObject, readPairsPacked } from './wire'
 
-// Lazy: importing this module does not dlopen the addon until first use.
+// Lazy: importing this module does not dlopen the addon until first use
+// (getBunFFI binds on first call; the napi proxy loads on first get).
 const addon = lazyAddon(getAddon)
 
+// FFI scratch (documented impure module state, per-Worker): grown lazily and
+// reused across calls — the parsed result is a JS object, the packed bytes
+// never escape.
+const ffiCaches: Record<'query' | 'cookie' | 'form', Uint8Array | null> = {
+  query: null,
+  cookie: null,
+  form: null,
+}
+function scratchFor(kind: 'query' | 'cookie' | 'form', input: Uint8Array): Uint8Array {
+  // Packed pairs worst case ≈ 9× input (u32 len + bytes per key/value) + header.
+  const need = input.length * 9 + 16
+  let s = ffiCaches[kind]
+  if (s === null || s.length < need) {
+    s = new Uint8Array(need)
+    ffiCaches[kind] = s
+  }
+  return s
+}
+
+function parsePackedInto(
+  kind: 'query' | 'cookie' | 'form',
+  input: Uint8Array,
+): Record<string, string | string[]> | null {
+  const f = getBunFFI()
+  if (!f) return null
+  const out = scratchFor(kind, input)
+  const w =
+    kind === 'query'
+      ? f.queryParsePackedInto(input, out)
+      : kind === 'cookie'
+        ? f.cookieParsePackedInto(input, out)
+        : f.formParsePackedInto(input, out)
+  if (w === 0 || w > out.length) return null
+  return pairsToObject(readPairsPacked(out.subarray(0, w)))
+}
+
+/** Shared FFI-first parse with an napi fallback (one encode, per kind). */
+function parseVia(
+  kind: 'query' | 'cookie' | 'form',
+  input: Uint8Array,
+): Record<string, string | string[]> {
+  const fast = parsePackedInto(kind, input)
+  if (fast) return fast
+  const packed =
+    kind === 'query'
+      ? addon.queryParsePacked(input)
+      : kind === 'cookie'
+        ? addon.cookieParsePacked(input)
+        : addon.formParsePacked(input)
+  return pairsToObject(readPairsPacked(packed))
+}
+
 /** Parse a query string (`a=1&b=2`) into an object via the native parser. */
 export function parseQueryString(query: string): Record<string, string | string[]> {
-  const packed = addon.queryParsePacked(encoder.encode(query))
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('query', encoder.encode(query))
 }
 
 /** Parse a cookie header (`a=1; b=2`) into an object via the native parser. */
 export function parseCookieHeader(header: string): Record<string, string | string[]> {
-  const packed = addon.cookieParsePacked(encoder.encode(header))
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('cookie', encoder.encode(header))
 }
 
 /** Parse an application/x-www-form-urlencoded body into a key/value object. */
 export function parseFormBody(body: Uint8Array): Record<string, string | string[]> {
-  const packed = addon.formParsePacked(body)
-  return pairsToObject(readPairsPacked(packed))
+  return parseVia('form', body)
 }

package/src/shared/runtime.ts

@@ -7,6 +7,7 @@
 
 import {
   detectedRuntime,
+  forceGc as forceGcDetected,
   isBunRuntime,
   isNodeRuntime,
   nodeMajorVersion as nodeMajorVersionDetected,
@@ -27,3 +28,9 @@ export const runtimeName: () => RuntimeName = () => detectedRuntime
 
 /** The Node.js major version when running under Node, otherwise `null`. */
 export const nodeMajorVersion: () => number | null = nodeMajorVersionDetected
+
+/**
+ * Request a synchronous full GC when the runtime exposes one (`Bun.gc(true)` on
+ * Bun, `globalThis.gc?.()` under Node `--expose-gc`). A no-op otherwise.
+ */
+export const forceGc: () => void = forceGcDetected

package/src/task/runtime.ts

@@ -75,11 +75,7 @@ export interface TaskRuntime {
   /** gzip-compress `data` on a pool thread. */
   gzipCompress(data: Uint8Array, options?: TaskRunOptions): Promise<Uint8Array>
   /** Verify a password against a PHC string on a pool thread (10-200 ms CPU). */
-  argon2Verify(
-    password: Uint8Array,
-    phc: Uint8Array,
-    options?: TaskRunOptions,
-  ): Promise<boolean>
+  argon2Verify(password: Uint8Array, phc: Uint8Array, options?: TaskRunOptions): Promise<boolean>
   /** PBKDF2-HMAC-SHA256 on a pool thread (10-200 ms CPU, 1-64 B output). */
   pbkdf2Sha256(
     password: Uint8Array,
@@ -156,6 +152,37 @@ function cancelledError(): Error {
   return err
 }
 
+/** Native `taskSubmit*` return: the task was accepted onto the pool. */
+const TASK_SUBMIT_ACCEPTED = 1
+/** Native `taskSubmit*` return: the bounded work queue is full (overload). */
+const TASK_SUBMIT_OVERLOADED = 2
+
+/** Error raised when the bounded native task queue is at its admission bound. */
+interface TaskOverloadedError extends Error {
+  /** Stable discriminant so callers can branch on overload. */
+  code: 'OVERLOADED'
+}
+
+/**
+ * Map a native `taskSubmit*` return code to the reason a task promise should
+ * reject with, or `null` when the submission was accepted. Pure and exported
+ * for tests, so the rejection mapping can be checked without driving the native
+ * pool into a real overload.
+ *
+ * @param code Native submit return: `1` accepted, `2` overloaded, else rejected.
+ * @returns The typed overload error, the generic rejection, or `null`.
+ */
+export function taskSubmitError(code: number): Error | null {
+  if (code === TASK_SUBMIT_ACCEPTED) return null
+  if (code === TASK_SUBMIT_OVERLOADED) {
+    const err = new Error('task rejected: native work queue is full') as TaskOverloadedError
+    err.name = 'TaskOverloadedError'
+    err.code = 'OVERLOADED'
+    return err
+  }
+  return new Error('task rejected by the native runtime')
+}
+
 /** Bunny-shaped doorbell handle (structural, so it needs no bun-types dep). */
 interface Doorbell {
   ptr: number | null
@@ -345,9 +372,7 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
         } else if (status === TASK_STATUS_CANCELLED) {
           deferred.reject(cancelledError())
         } else {
-          deferred.reject(
-            new Error(decodeUtf8(bodyOf(buf, bodyOff, len, pooled)) || 'task failed'),
-          )
+          deferred.reject(new Error(decodeUtf8(bodyOf(buf, bodyOff, len, pooled)) || 'task failed'))
         }
         completed++
       }
@@ -361,19 +386,20 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     queueMicrotask(drainNow)
   }
 
-  function submit(
-    op: number,
-    args: Uint8Array,
-    runOptions?: TaskRunOptions,
-  ): Promise<Uint8Array> {
+  function submit(op: number, args: Uint8Array, runOptions?: TaskRunOptions): Promise<Uint8Array> {
+    ensureDoorbell()
     const id = nextId++
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: null, keep: null, resolve, reject })
       retain()
-      if (ffi.taskSubmit(op, args, id) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmit(op, args, id))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal
@@ -398,14 +424,19 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     output: Uint8Array,
     runOptions?: TaskRunOptions,
   ): Promise<Uint8Array> {
+    ensureDoorbell()
     const id = nextId++
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: output, keep: null, resolve, reject })
       retain()
-      if (ffi.taskSubmitOut(op, args, id, output) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmitOut(op, args, id, output))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal
@@ -431,14 +462,19 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     data: Uint8Array,
     runOptions?: TaskRunOptions,
   ): Promise<Uint8Array> {
+    ensureDoorbell()
     const id = nextId++
     return new Promise<Uint8Array>((resolve, reject) => {
       inflight.set(id, { out: null, keep: data, resolve, reject })
       retain()
-      if (ffi.taskSubmitSlice(op, hdr, data, id) === 0) {
+      const rejected = taskSubmitError(ffi.taskSubmitSlice(op, hdr, data, id))
+      if (rejected) {
         inflight.delete(id)
-        release()
-        reject(new Error('task rejected by the native runtime'))
+        // Release the keep-alive only when this was the last in-flight task.
+        // An overload/invalid rejection must not tear down the interval (and
+        // its polling safety net) while other tasks are still pending.
+        if (inflight.size === 0) release()
+        reject(rejected)
         return
       }
       const signal = runOptions?.signal
@@ -453,19 +489,26 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
   }
 
   // One process-wide trampoline; Bun marshals calls from pool threads onto the
-  // JS thread. Rust coalesces so a burst rings it once.
+  // JS thread. Rust coalesces so a burst rings it once. Created lazily (and
+  // re-created after a shutdown) so the native side NEVER holds the address of
+  // a closed `JSCallback` — calling a freed trampoline is a use-after-free.
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   const { JSCallback } = require('bun:ffi') as typeof import('bun:ffi')
-  const cb = new JSCallback(
-    () => {
-      drainNow()
-    },
-    { args: [], returns: 'void', threadsafe: true } as unknown as ConstructorParameters<
-      typeof JSCallback
-    >[1],
-  )
-  doorbell = cb
-  ffi.taskSetDoorbell(Number(cb.ptr))
+  function ensureDoorbell(): void {
+    if (doorbell !== null) return
+    const cb = new JSCallback(
+      () => {
+        drainNow()
+      },
+      { args: [], returns: 'void', threadsafe: true } as unknown as ConstructorParameters<
+        typeof JSCallback
+      >[1],
+    )
+    doorbell = cb
+    ffi.taskSetDoorbell(Number(cb.ptr))
+  }
+
+  ensureDoorbell()
 
   // A zero-copy result handoff via `toArrayBuffer(ptr, 0, len, dealloc)` was
   // prototyped here and REVERTED: Bun 1.4.2's deallocator hook segfaults
@@ -492,8 +535,7 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
       // UNSUPPORTED from an older addon) fall back, so behavior can't regress.
       // Args are re-submitted on the retry step, so they own their memory.
       const args = encodeGzipDecompressArgs(data, runOptions?.maxDecompressed)
-      const copyPath = (): Promise<Uint8Array> =>
-        submit(TASK_OP.gzipDecompress, args, runOptions)
+      const copyPath = (): Promise<Uint8Array> => submit(TASK_OP.gzipDecompress, args, runOptions)
       const zeroCopyOnce = (cap: number): Promise<Uint8Array> =>
         submitInto(TASK_OP.gzipDecompressInto, args, Buffer.allocUnsafe(cap), runOptions)
       return zeroCopyOnce(size)
@@ -521,8 +563,7 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
     },
     brotliDecompress(data, runOptions) {
       const args = encodeBrotliDecompressArgs(data, runOptions?.maxDecompressed)
-      const copyPath = (): Promise<Uint8Array> =>
-        submit(TASK_OP.brotliDecompress, args, runOptions)
+      const copyPath = (): Promise<Uint8Array> => submit(TASK_OP.brotliDecompress, args, runOptions)
       // Brotli has no ISIZE trailer, so there is no exact size hint: start from
       // a ratio guess and let the needed-size retry land it exactly (at most
       // one extra pass; on anything but TOO_SMALL, fall back to the copy op).
@@ -557,6 +598,9 @@ export function createTaskRuntime(options: TaskRuntimeOptions = {}): TaskRuntime
         deferred.reject(cancelledError())
       }
       inflight.clear()
+      // Zero the native doorbell BEFORE closing the JS trampoline: a worker
+      // completing after this point must never call a freed callback.
+      ffi.taskSetDoorbell(0)
       ffi.taskShutdown()
       release()
       doorbell?.close()