@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.50

package/dist/utils/state-machine.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Tiny typed state machine utility.
+ *
+ * Enforces discriminated-union states, typed transitions with runtime
+ * guards, subscribe for external store integration, and assertPhase
+ * for function entry guards.
+ *
+ * Designed for 3–5 state consumers (stream transforms, client navigation,
+ * build phase sequencing). No async, no hierarchy, no history.
+ *
+ * Performance: send() is one object lookup + one function call.
+ * Equivalent cost to a boolean check after V8 inlining.
+ */
+/** A state machine instance with typed state and events. */
+export interface Machine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    /** Current state (discriminated union — narrowed by phase). */
+    readonly state: TState;
+    /** Transition with runtime guard. Throws on invalid source+event pair. */
+    send(event: TEvent): void;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: (state: TState) => void): () => void;
+    /** Throw if not in the expected phase. Entry guard for functions. */
+    assertPhase<P extends TState['phase']>(phase: P): void;
+}
+/**
+ * Transition map: `transitions[phase][eventType]` returns the next state.
+ *
+ * Each handler receives the current state (narrowed by phase context)
+ * and the event, returning the new state.
+ */
+export type TransitionMap<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> = {
+    [P in TState['phase']]?: {
+        [E in TEvent['type']]?: (state: Extract<TState, {
+            phase: P;
+        }>, event: Extract<TEvent, {
+            type: E;
+        }>) => TState;
+    };
+};
+export interface MachineConfig<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}> {
+    initial: TState;
+    transitions: TransitionMap<TState, TEvent>;
+    /** Fires after every valid transition. Use for side effects. */
+    onTransition?: (prev: TState, next: TState, event: TEvent) => void;
+}
+/**
+ * Create a state machine from a config.
+ *
+ * @example
+ * ```ts
+ * type State = { phase: 'idle' } | { phase: 'running'; pid: number };
+ * type Event = { type: 'START'; pid: number } | { type: 'STOP' };
+ *
+ * const m = createMachine<State, Event>({
+ *   initial: { phase: 'idle' },
+ *   transitions: {
+ *     idle: { START: (_s, e) => ({ phase: 'running', pid: e.pid }) },
+ *     running: { STOP: () => ({ phase: 'idle' }) },
+ *   },
+ * });
+ * ```
+ */
+export declare function createMachine<TState extends {
+    phase: string;
+}, TEvent extends {
+    type: string;
+}>(config: MachineConfig<TState, TEvent>): Machine<TState, TEvent>;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/utils/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/utils/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,OAAO,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IACxF,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,0EAA0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEzD,qEAAqE;IACrE,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI;KAC5F,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;SACtB,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACtB,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,KAAK,EAAE,CAAC,CAAA;SAAE,CAAC,EACpC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,KAChC,MAAM;KACZ;CACF,CAAC;AAEF,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,gEAAgE;IAChE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAC7F,MAAM,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCzB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.5",
-  "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
+  "version": "0.2.0-alpha.50",
+  "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
     "framework",
@@ -58,6 +58,10 @@
       "types": "./dist/cookies/index.d.ts",
       "import": "./dist/cookies/index.js"
     },
+    "./params": {
+      "types": "./dist/params/index.d.ts",
+      "import": "./dist/params/index.js"
+    },
     "./search-params": {
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
@@ -79,15 +83,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.6.1",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
     "nitro": "3.0.260311-beta"
   },
   "peerDependencies": {
@@ -98,8 +97,8 @@
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.21",
     "nuqs": "^2.0.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "19.3.0-canary-ed69815c-20260323",
+    "react-dom": "19.3.0-canary-ed69815c-20260323",
     "vite": "^8.0.1",
     "zod": "^3.22.0 || ^4.0.0"
   },
@@ -121,6 +120,10 @@
     }
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/adapters/compress-module.ts

@@ -22,9 +22,11 @@
 export function generateCompressModule(): string {
   return `// Generated by @timber-js/app — response compression for self-hosted deployments.
 // Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
+// Uses node:zlib createGzip() (C++ native) on Node.js, falls back to
+// CompressionStream (Web API) on other runtimes. Brotli is left to CDNs/reverse
+// proxies — at streaming quality levels its ratio advantage is marginal.
+import { Readable } from 'node:stream';
+import { createGzip, constants } from 'node:zlib';
 
 const COMPRESSIBLE_TYPES = new Set([
   'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
@@ -71,7 +73,25 @@ function shouldCompress(response) {
 }
 
 function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
+  // Use node:zlib (C++ native) for gzip compression. The Web Streams
+  // CompressionStream works but every chunk crosses the JS/Promise boundary.
+  // node:zlib.createGzip() compresses entirely in C++ with zero per-chunk
+  // Promise overhead.
+  //
+  // Convert: Web ReadableStream → Node Readable → pipe through gzip →
+  //          Node Readable → Readable.toWeb() → Web ReadableStream
+  try {
+    const nodeReadable = Readable.fromWeb(body);
+    // Z_SYNC_FLUSH ensures each chunk is flushed immediately so the browser
+    // receives the HTML shell before Suspense boundaries resolve. Without it,
+    // gzip buffers internally and breaks streaming.
+    const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+    const compressed = nodeReadable.pipe(gzip);
+    return Readable.toWeb(compressed);
+  } catch {
+    // Fallback: CompressionStream (CF Workers, or if node:stream unavailable)
+    return body.pipeThrough(new CompressionStream('gzip'));
+  }
 }
 
 export function compressResponse(request, response) {

package/src/adapters/nitro.ts

@@ -149,6 +149,23 @@ export interface NitroAdapterOptions {
    */
   preset?: NitroPreset;
 
+  /**
+   * Enable application-level gzip compression for HTML and RSC responses.
+   *
+   * When `true` (default), the origin compresses responses using the Web
+   * `CompressionStream` API. This is useful for self-hosted deployments
+   * where no reverse proxy or CDN handles compression.
+   *
+   * Set to `false` when deploying behind a reverse proxy (nginx, caddy)
+   * or CDN (Cloudflare, Fastly, Vercel) that compresses at the edge.
+   * Disabling origin compression saves CPU on the Node.js event loop —
+   * compressing 1MB+ streaming HTML responses takes 10-15ms of main
+   * thread time per request, directly reducing throughput under load.
+   *
+   * @default true
+   */
+  compress?: boolean;
+
   /**
    * Additional Nitro configuration to merge into the generated config.
    * Overrides default values for the selected preset.
@@ -176,6 +193,7 @@ export interface NitroAdapterOptions {
  */
 export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter {
   const preset = options.preset ?? 'node-server';
+  const compress = options.compress ?? true;
   const presetConfig = PRESET_CONFIGS[preset];
   const pendingPromises: Promise<unknown>[] = [];
 
@@ -229,7 +247,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       }
 
       // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
-      const entry = generateNitroEntry(buildDir, outDir, preset);
+      const entry = generateNitroEntry(buildDir, outDir, preset, compress);
       await writeFile(join(outDir, 'entry.ts'), entry);
 
       // Run the Nitro build to produce a production-ready server bundle.
@@ -273,6 +291,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
+  compress = true,
   hasManifestInit = false
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
@@ -338,12 +357,14 @@ export function generateNitroEntry(
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
+  const compressImport = compress ? "import { compressResponse } from './_compress.mjs'\n" : '';
+  const compressCall = compress ? 'compressResponse(webRequest, webResponse)' : 'webResponse';
+
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
 ${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
-import { compressResponse } from './_compress.mjs'
-
+${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
@@ -357,7 +378,7 @@ export default async function timberHandler(event) {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
-  return compressResponse(webRequest, webResponse)
+  return ${compressCall}
 }
 `;
 }
@@ -544,14 +565,37 @@ const server = createServer(async (req, res) => {
 
     if (webResponse.body) {
       const reader = webResponse.body.getReader();
-      const pump = async () => {
+
+      // Cancel the reader when the client disconnects. This causes any
+      // pending reader.read() to reject, breaking the pump loop. Critical
+      // for SSE and other infinite streams — without this, disconnected
+      // clients leak readers.
+      let clientDisconnected = false;
+      const onClose = () => {
+        clientDisconnected = true;
+        reader.cancel('Client disconnected').catch(() => {});
+      };
+      res.on('close', onClose);
+
+      try {
         while (true) {
           const { done, value } = await reader.read();
-          if (done) { res.end(); return; }
+          if (done) break;
           res.write(value);
         }
-      };
-      await pump();
+      } catch (err) {
+        // reader.cancel() from the close handler causes read() to reject.
+        // This is expected on client disconnect — not an error.
+        if (!clientDisconnected) {
+          throw err;
+        }
+      } finally {
+        res.off('close', onClose);
+        reader.releaseLock();
+        if (!res.writableEnded) {
+          res.end();
+        }
+      }
     } else {
       res.end();
     }
@@ -611,7 +655,12 @@ async function runNitroBuild(
   userConfig?: Record<string, unknown>
 ): Promise<void> {
   const presetConfig = PRESET_CONFIGS[preset];
-  const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import('nitro/builder');
+  const {
+    createNitro,
+    build: nitroBuild,
+    prepare,
+    copyPublicAssets,
+  } = await import('nitro/builder');
 
   const nitro = await createNitro({
     rootDir: nitroDir,

package/src/cache/fast-hash.ts

@@ -0,0 +1,34 @@
+/**
+ * Fast non-cryptographic hash for cache keys.
+ *
+ * FNV-1a 64-bit produces a well-distributed hash with a collision
+ * probability of ~1 in 5 billion at 77k keys (birthday paradox).
+ * Not suitable for security, but ideal for cache key generation
+ * where we need speed over crypto strength.
+ *
+ * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
+ * including Cloudflare Workers. No node:crypto dependency.
+ *
+ * See TIM-370.
+ */
+
+// FNV-1a constants for 64-bit hash
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = 0xffffffffffffffffn;
+
+/**
+ * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.
+ *
+ * 64 bits gives ~5 billion keys before a 50% collision probability
+ * (birthday paradox), making accidental collisions effectively impossible
+ * for cache key use cases.
+ */
+export function fnv1aHash(input: string): string {
+  let hash = FNV_OFFSET_BASIS;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * FNV_PRIME) & MASK_64;
+  }
+  return hash.toString(16).padStart(16, '0');
+}

package/src/cache/index.ts

@@ -12,6 +12,9 @@ export interface CacheOptions<Fn extends (...args: any[]) => any> {
   key?: (...args: Parameters<Fn>) => string;
   staleWhileRevalidate?: boolean;
   tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+  /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from
+   *  permanently blocking all future callers for the same cache key. See TIM-518. */
+  timeoutMs?: number;
 }
 
 export interface MemoryCacheHandlerOptions {
@@ -87,5 +90,5 @@ export { createCache } from './timber-cache';
 export { registerCachedFunction } from './register-cached-function';
 export type { RegisterCachedFunctionOptions } from './register-cached-function';
 export { stableStringify } from './stable-stringify';
-export { createSingleflight } from './singleflight';
-export type { Singleflight } from './singleflight';
+export { createSingleflight, SingleflightTimeoutError } from './singleflight';
+export type { Singleflight, SingleflightOptions } from './singleflight';

package/src/cache/register-cached-function.ts

@@ -1,7 +1,7 @@
-import { createHash } from 'node:crypto';
 import type { CacheHandler } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
+import { fnv1aHash } from './fast-hash.js';
 
 const singleflight = createSingleflight();
 
@@ -27,11 +27,15 @@ export interface RegisterCachedFunctionOptions<Fn extends (...args: any[]) => an
 }
 
 /**
- * Generate a SHA-256 cache key from a stable function ID and serialized args.
+ * Generate a cache key from a stable function ID and serialized args.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. The id prefix
+ * provides namespace isolation; the hash covers the args.
+ * See TIM-370.
  */
 function generateKey(id: string, args: unknown[]): string {
   const raw = id + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return id + ':' + fnv1aHash(raw);
 }
 
 /**

package/src/cache/singleflight.ts

@@ -3,24 +3,82 @@
  * execution. All callers receive the same result (or error).
  *
  * Per-process, in-memory. Each process coalesces independently.
+ *
+ * An optional `timeoutMs` prevents hung `fn()` calls from permanently
+ * blocking all future callers for that key. When set, `fn()` is raced
+ * against a timeout — if the timeout fires first, the promise rejects
+ * with `SingleflightTimeoutError`, `finally` cleans up the key, and
+ * subsequent callers can retry. See TIM-518.
  */
+
+export interface SingleflightOptions {
+  /** Maximum time (ms) a coalesced call may run before being rejected. */
+  timeoutMs?: number;
+}
+
 export interface Singleflight {
   do<T>(key: string, fn: () => Promise<T>): Promise<T>;
 }
 
-export function createSingleflight(): Singleflight {
+/**
+ * Error thrown when a singleflight call exceeds `timeoutMs`.
+ * Exported so callers can distinguish timeout from other errors.
+ */
+export class SingleflightTimeoutError extends Error {
+  constructor(key: string, timeoutMs: number) {
+    super(`Singleflight timeout: key "${key}" exceeded ${timeoutMs}ms`);
+    this.name = 'SingleflightTimeoutError';
+  }
+}
+
+export function createSingleflight(opts?: SingleflightOptions): Singleflight {
   const inflight = new Map<string, Promise<unknown>>();
+  const timeoutMs = opts?.timeoutMs;
 
   return {
     do<T>(key: string, fn: () => Promise<T>): Promise<T> {
       const existing = inflight.get(key);
       if (existing) return existing as Promise<T>;
 
-      const promise = fn().finally(() => {
+      let promise: Promise<T>;
+
+      if (timeoutMs != null && timeoutMs > 0) {
+        // Race fn() against a timeout to prevent hung calls from
+        // permanently blocking the key. See TIM-518.
+        promise = new Promise<T>((resolve, reject) => {
+          const timer = setTimeout(
+            () => reject(new SingleflightTimeoutError(key, timeoutMs)),
+            timeoutMs
+          );
+          // Wrap in try/catch so a synchronous throw from fn()
+          // (e.g. argument validation) still clears the timer.
+          // Without this, the timer leaks until expiry.
+          try {
+            fn().then(
+              (value) => {
+                clearTimeout(timer);
+                resolve(value);
+              },
+              (err) => {
+                clearTimeout(timer);
+                reject(err);
+              }
+            );
+          } catch (err) {
+            clearTimeout(timer);
+            reject(err);
+          }
+        });
+      } else {
+        promise = fn();
+      }
+
+      const tracked = promise.finally(() => {
         inflight.delete(key);
       });
-      inflight.set(key, promise);
-      return promise;
+
+      inflight.set(key, tracked);
+      return tracked as Promise<T>;
     },
   };
 }

package/src/cache/timber-cache.ts

@@ -1,17 +1,23 @@
-import { createHash } from 'node:crypto';
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEvent } from '#/server/tracing.js';
+import { addSpanEventSync } from '#/server/tracing.js';
+import { fnv1aHash } from './fast-hash.js';
 
-const singleflight = createSingleflight();
+const defaultSingleflight = createSingleflight();
 
 /**
- * Generate a SHA-256 cache key from function identity and serialized args.
+ * Generate a cache key from function identity and serialized args.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
+ * need collision resistance — they need speed. The fnId prefix provides
+ * namespace isolation; the hash covers the args.
+ *
+ * See TIM-370 for perf motivation.
  */
 function defaultKeyGenerator(fnId: string, args: unknown[]): string {
   const raw = fnId + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return fnId + ':' + fnv1aHash(raw);
 }
 
 /**
@@ -47,18 +53,25 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
   handler: CacheHandler
-): (...args: Parameters<Fn>) => Promise<Awaited<ReturnType<Fn>>> {
+): Fn {
   const fnId = `timber-cache:${fnIdCounter++}`;
+  const sf = opts.timeoutMs
+    ? createSingleflight({ timeoutMs: opts.timeoutMs })
+    : defaultSingleflight;
 
-  return async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
+  // Cast to Fn to preserve the original function's generic call signature.
+  // Without this, generic type parameters (e.g. <T> in apiFetch<T>) are
+  // erased and callers lose type safety on the return type.
+  return (async (...args: Parameters<Fn>): Promise<Awaited<ReturnType<Fn>>> => {
     const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
 
     const cacheStart = performance.now();
     const cached = await handler.get(key);
 
     if (cached && !cached.stale) {
-      // Record as OTEL span event on enclosing span (not a child span)
-      await addSpanEvent('timber.cache.hit', {
+      // Record as OTEL span event on enclosing span (not a child span).
+      // Fire-and-forget — no microtask overhead on the cache hot path.
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
       });
@@ -66,43 +79,41 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     }
 
     if (cached && cached.stale && opts.staleWhileRevalidate) {
-      // Record stale cache hit as OTEL span event
-      await addSpanEvent('timber.cache.hit', {
+      // Record stale cache hit as OTEL span event (fire-and-forget).
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
         stale: true,
       });
       // Serve stale immediately, trigger background refetch
-      singleflight
-        .do(`swr:${key}`, async () => {
-          try {
-            const fresh = await fn(...args);
-            const tags = resolveTags(opts, args);
-            await handler.set(key, fresh, { ttl: opts.ttl, tags });
-          } catch {
-            // Failed refetch — stale entry continues to be served.
-            // Error is swallowed per design doc: "Error is logged."
-          }
-        })
-        .catch(() => {
-          // Singleflight promise rejection handled — stale continues.
-        });
+      sf.do(`swr:${key}`, async () => {
+        try {
+          const fresh = await fn(...args);
+          const tags = resolveTags(opts, args);
+          await handler.set(key, fresh, { ttl: opts.ttl, tags });
+        } catch {
+          // Failed refetch — stale entry continues to be served.
+          // Error is swallowed per design doc: "Error is logged."
+        }
+      }).catch(() => {
+        // Singleflight promise rejection handled — stale continues.
+      });
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
     // Cache miss (or stale without SWR) — execute with singleflight
-    const result = await singleflight.do(key, () => fn(...args));
+    const result = await sf.do(key, () => fn(...args));
     const tags = resolveTags(opts, args);
     await handler.set(key, result, { ttl: opts.ttl, tags });
 
-    // Record cache miss as OTEL span event
-    await addSpanEvent('timber.cache.miss', {
+    // Record cache miss as OTEL span event (fire-and-forget).
+    addSpanEventSync('timber.cache.miss', {
       key,
       duration_ms: Math.round(performance.now() - cacheStart),
     });
 
     return result as Awaited<ReturnType<Fn>>;
-  };
+  }) as unknown as Fn;
 }
 
 /**