@timber-js/app 0.2.0-alpha.163 → 0.2.0-alpha.165

package/docs/learn/13-configuration.mdx

@@ -122,14 +122,33 @@ Server actions still work — HTML forms submit natively via POST without JavaSc
 
 ## All Options
 
-| Option             | Type                    | Default                      | Description               |
-| ------------------ | ----------------------- | ---------------------------- | ------------------------- |
-| `output`           | `'server' \| 'static'` | `'server'`                   | Output mode               |
-| `adapter`          | `TimberPlatformAdapter` | —                            | Deployment adapter        |
-| `cacheHandler`     | `CacheHandler`          | `MemoryCacheHandler`         | Cache backend             |
-| `clientJavascript` | `boolean \| object`     | `true`                       | Control client-side JS    |
-| `pageExtensions`   | `string[]`              | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages |
-| `mdx`              | `object`                | —                            | MDX remark/rehype plugins |
+| Option              | Type                        | Default                      | Description                              |
+| ------------------- | --------------------------- | ---------------------------- | ---------------------------------------- |
+| `output`            | `'server' \| 'static'`     | `'server'`                   | Output mode                              |
+| `debug`             | `boolean`                   | `false`                      | Enable timber debug logging in prod      |
+| `buildDir`          | `string`                    | `'.timber/dist'`             | Build output directory                   |
+| `clientJavascript`  | `boolean \| object`         | `true`                       | Control client-side JS                   |
+| `adapter`           | `TimberPlatformAdapter`     | —                            | Deployment adapter                       |
+| `cacheHandler`      | `CacheHandler`              | `MemoryCacheHandler`         | Cache backend                            |
+| `cdnPurge`          | `CdnPurgeHandler`           | —                            | CDN purge on revalidation                |
+| `serverTiming`      | `'detailed' \| 'total' \| false` | `'detailed'` / `'total'` | Server-Timing header                     |
+| `allowedOrigins`    | `string[]`                  | —                            | CORS / CSRF allowed origins              |
+| `csrf`              | `boolean`                   | `true`                       | CSRF protection                          |
+| `limits`            | `object`                    | —                            | Request body size limits                 |
+| `actions`           | `object`                    | —                            | Server action behavior                   |
+| `forms`             | `object`                    | —                            | Form handling (sensitive field stripping) |
+| `pageExtensions`    | `string[]`                  | `['tsx', 'ts', 'jsx', 'js']` | File extensions for pages                |
+| `slowRequestMs`     | `number`                    | `3000`                       | Slow request warning threshold (ms)      |
+| `renderTimeoutMs`   | `number`                    | `30000`                      | Render abort timeout (ms)                |
+| `devBrowserLogs`    | `string`                    | `'warn'`                     | Forward browser console to server in dev |
+| `dev`               | `object`                    | —                            | Dev-mode options                         |
+| `budget`            | `object`                    | —                            | Build-time performance budgets           |
+| `appDir`            | `string`                    | auto-detected                | Override app directory location          |
+| `mdx`               | `object`                    | —                            | MDX remark/rehype plugins                |
+| `actionEncryption`  | `object`                    | —                            | Server action bound args encryption      |
+| `reactCompiler`     | `boolean \| object`         | `false`                      | React Compiler auto-memoization          |
+| `sitemap`           | `object`                    | —                            | Auto-generated sitemap.xml               |
+| `topLoader`         | `object`                    | enabled                      | Navigation progress bar                  |
 
 For the full type definition, see the [Config API Reference](/docs/api-config).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.163",
+  "version": "0.2.0-alpha.165",
   "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",
@@ -156,7 +156,8 @@
     "@opentelemetry/sdk-trace-base": "^2.8.0",
     "cookie": "^1.1.1",
     "magic-string": "^0.30.21",
-    "nitro": "3.0.260610-beta"
+    "nitro": "3.0.260610-beta",
+    "srvx": "^0.11.17"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",

package/src/adapters/cloudflare-kv-cache.ts

@@ -112,7 +112,11 @@ export class CloudflareKVCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const kv = this.getKV();
     const entry: KVCacheEntry = {
       value,

package/src/adapters/nitro.ts

@@ -5,9 +5,9 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile } from 'node:fs/promises';
+import { writeFile, readFile, cp, glob } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join, relative, dirname, basename } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
 import { IMMUTABLE_CACHE } from './shared.js';
@@ -38,6 +38,12 @@ interface PresetConfig {
   nitroPreset: string;
   /** Output directory name within the build dir. */
   outputDir: string;
+  /**
+   * Path to the server bundle directory relative to outputDir.
+   * Nitro places the bundled server entry + _chunks/ here.
+   * Most presets use `server`; Vercel uses `functions/__server.func`.
+   */
+  serverBundleDir: string;
   /** Whether the runtime supports waitUntil. */
   supportsWaitUntil: boolean;
   /** Whether the runtime supports application-level 103 Early Hints. */
@@ -52,6 +58,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel': {
     nitroPreset: 'vercel',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel',
@@ -60,6 +67,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel-edge': {
     nitroPreset: 'vercel-edge',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel-edge',
@@ -67,6 +75,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify': {
     nitroPreset: 'netlify',
     outputDir: '.netlify/functions-internal',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'netlify',
@@ -74,6 +83,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify-edge': {
     nitroPreset: 'netlify-edge',
     outputDir: '.netlify/edge-functions',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'netlify-edge',
@@ -81,6 +91,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'aws-lambda': {
     nitroPreset: 'aws-lambda',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'aws-lambda',
@@ -88,6 +99,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'deno-deploy': {
     nitroPreset: 'deno-deploy',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'deno-deploy',
@@ -95,6 +107,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'azure-functions': {
     nitroPreset: 'azure-functions',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'azure-functions',
@@ -102,6 +115,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'node-server': {
     nitroPreset: 'node-server',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled by default: most node-server deployments sit behind a
     // reverse proxy (nginx, caddy, traefik) that doesn't support 103
@@ -116,6 +130,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'bun': {
     nitroPreset: 'bun',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled for same reason as node-server — reverse proxies choke on 103.
     // Link headers on the 200 response are converted to 103 by CDNs.
@@ -195,11 +210,14 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
         publicDirName: 'public',
       });
 
-      // Write the compression helper module for runtime use.
+      // Write runtime helper modules used by the preview server.
       // See design/25-production-deployments.md — self-hosted deployments
       // need application-level compression (Cloudflare handles it at the edge).
       await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
+      // Web→Node response bridge with backpressure. See TIM-1154.
+      await writeFile(join(outDir, '_send-response.mjs'), generateSendResponseModule());
+
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
       // This must be top-level code, not an import, because rollup tree-shakes
@@ -217,7 +235,29 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // Run the Nitro build to produce a production-ready server bundle.
       // The output goes to dist/nitro/.output/server/index.mjs (for node-server preset).
       // Config is passed programmatically — no nitro.config.ts file needed.
-      await runNitroBuild(outDir, preset, options.nitroConfig);
+      const { serverDir } = await runNitroBuild(outDir, preset, options.nitroConfig);
+
+      // Copy prebuilt flight payloads from the canonical build source
+      // (buildDir/prebuilt, cleaned by the prebuilt plugin each build) into
+      // the Nitro output. The RSC entry resolves `../prebuilt/` relative to
+      // its bundled chunk (<serverDir>/_chunks/), so prebuilt/ must live at
+      // <serverDir>/prebuilt/. serverDir is the resolved path from Nitro
+      // (honors user overrides via nitroConfig.output.serverDir).
+      const prebuiltSrc = join(buildDir, 'prebuilt');
+      await cp(prebuiltSrc, join(serverDir, 'prebuilt'), {
+        recursive: true,
+      }).catch((e: NodeJS.ErrnoException) => {
+        if (e.code !== 'ENOENT') throw e;
+      });
+
+      // Vercel with functionRules clones __server.func to per-route .func
+      // directories during the Nitro build. Copy prebuilt into those clones
+      // so requests routed to them also resolve ../prebuilt correctly.
+      if (preset === 'vercel' || preset === 'vercel-edge') {
+        const functionsDir = dirname(serverDir);
+        const baseFuncName = basename(serverDir);
+        await copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFuncName);
+      }
     },
 
     // Only presets that produce a locally-runnable server get preview().
@@ -378,6 +418,9 @@ const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}'
 // Import compression helper for self-hosted response compression.
 const { compressResponse } = await import('./_compress.mjs');
 
+// Web→Node response bridge with backpressure (TIM-1154).
+const { sendNodeResponse } = await import('./_send-response.mjs');
+
 const MIME_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -414,7 +457,7 @@ const publicDir = join(__dirname, '${publicDir}');
 const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
 const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
 const startPort = portIsExplicit ? envPort : 3000;
-const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
+const host = process.env.HOST || 'localhost';
 
 // Set after listenWithBump() resolves so request handlers can build
 // absolute URLs from the actual bound port (which may differ from
@@ -501,68 +544,11 @@ const server = createServer(async (req, res) => {
     // Compress the response for self-hosted deployments.
     const webResponse = compressResponse(webRequest, rawResponse);
 
-    // Write the response back to the Node response.
-    //
-    // Set-Cookie needs special handling: Headers.entries() joins multiple
-    // Set-Cookie values with ", " into a single entry, but each cookie must
-    // be its own header per RFC 6265 §4.1. Object.fromEntries() would then
-    // collapse them into one malformed Set-Cookie header that browsers reject
-    // (or only honor partially). Use getSetCookie() to preserve individual
-    // values, and pass them as an array — Node's writeHead accepts
-    // Record<string, string | string[]> and emits one header per array entry.
-    //
-    // Without this, EVERY cookie set by the framework on Node—/Nitro deployments
-    // is silently dropped: defineCookie().setCookie() in actions, middleware
-    // cookie writes, the framework's own session cookies, all of it. See
-    // LOCAL-741.
-    const responseHeaders = {};
-    webResponse.headers.forEach((value, key) => {
-      if (key.toLowerCase() !== 'set-cookie') {
-        responseHeaders[key] = value;
-      }
-    });
-    const setCookies = webResponse.headers.getSetCookie();
-    if (setCookies.length > 0) {
-      responseHeaders['set-cookie'] = setCookies;
-    }
-    res.writeHead(webResponse.status, responseHeaders);
-
-    if (webResponse.body) {
-      const reader = webResponse.body.getReader();
-
-      // 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) break;
-          res.write(value);
-        }
-      } 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();
-    }
+    // Write the response to Node's ServerResponse. sendNodeResponse handles
+    // status, headers (including Set-Cookie splitting via [...headers]),
+    // body streaming with backpressure, and client disconnect cleanup.
+    // See TIM-1154.
+    await sendNodeResponse(res, webResponse);
   } catch (err) {
     console.error('[timber preview] Request error:', err);
     if (!res.headersSent) {
@@ -649,11 +635,16 @@ export function generateNitroPreviewCommand(
  * Externalizes the timber RSC/SSR output — those files are pre-built
  * by timber and have internal references that nitro's bundler can't follow.
  */
+interface NitroBuildResult {
+  /** Resolved output.serverDir — where the server bundle + _chunks/ live. */
+  serverDir: string;
+}
+
 async function runNitroBuild(
   nitroDir: string,
   preset: NitroPreset,
   userConfig?: Record<string, unknown>
-): Promise<void> {
+): Promise<NitroBuildResult> {
   const presetConfig = PRESET_CONFIGS[preset];
   const {
     createNitro,
@@ -684,10 +675,18 @@ async function runNitroBuild(
     ...userConfig,
   });
 
+  // Read the resolved serverDir AFTER config merging — userConfig may
+  // override output.dir or output.serverDir. Nitro appends a trailing
+  // slash during resolution; strip it for join() compatibility.
+  const raw = nitro.options.output.serverDir;
+  const serverDir = raw.endsWith('/') ? raw.slice(0, -1) : raw;
+
   await prepare(nitro);
   await copyPublicAssets(nitro);
   await nitroBuild(nitro);
   await nitro.close();
+
+  return { serverDir };
 }
 
 /** Spawn a Nitro preview process and pipe stdio. */
@@ -702,6 +701,75 @@ function spawnNitroPreview(command: string, args: string[], cwd: string): Promis
   });
 }
 
+// ─── Send Response Module ───────────────────────────────────────────────────
+
+/**
+ * Generate a standalone ESM module that exports sendNodeResponse.
+ *
+ * Mirrors srvx/node's sendNodeResponse: status + headers via writeHead,
+ * body streaming with backpressure (waits for drain on write() === false),
+ * and client disconnect cleanup. Written to `_send-response.mjs` during
+ * buildOutput for use by the preview server script. See TIM-1154.
+ *
+ * @internal Exported for testing.
+ */
+export function generateSendResponseModule(): string {
+  return `// Generated by @timber-js/app — Web→Node response bridge.
+// Do not edit — this file is regenerated on each build.
+// Mirrors srvx/node's sendNodeResponse with backpressure support.
+
+export function sendNodeResponse(nodeRes, webRes) {
+  if (!webRes) {
+    nodeRes.statusCode = 500;
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  const rawHeaders = [...webRes.headers];
+  const writeHeaders = rawHeaders.flat();
+  if (!nodeRes.headersSent) {
+    if (nodeRes.req?.httpVersion === '2.0') {
+      nodeRes.writeHead(webRes.status, writeHeaders);
+    } else {
+      nodeRes.writeHead(webRes.status, webRes.statusText, writeHeaders);
+    }
+  }
+  if (!webRes.body) {
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  // Stream with backpressure: pause reading when the kernel buffer is
+  // full (write() returns false) and resume on 'drain'.
+  if (nodeRes.destroyed) {
+    webRes.body.cancel();
+    return;
+  }
+  const reader = webRes.body.getReader();
+  function streamCancel(error) {
+    reader.cancel(error).catch(() => {});
+    if (error) nodeRes.destroy(error);
+  }
+  function streamHandle({ done, value }) {
+    try {
+      if (done) {
+        nodeRes.end();
+      } else if (nodeRes.write(value)) {
+        reader.read().then(streamHandle, streamCancel);
+      } else {
+        nodeRes.once('drain', () => reader.read().then(streamHandle, streamCancel));
+      }
+    } catch (error) {
+      streamCancel(error instanceof Error ? error : undefined);
+    }
+  }
+  nodeRes.on('close', streamCancel);
+  nodeRes.on('error', streamCancel);
+  reader.read().then(streamHandle, streamCancel);
+  return reader.closed.catch(streamCancel).finally(() => {
+    nodeRes.off('close', streamCancel);
+    nodeRes.off('error', streamCancel);
+  });
+}
+`;
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
@@ -711,3 +779,55 @@ function spawnNitroPreview(command: string, args: string[], cwd: string): Promis
 export function getPresetConfig(preset: NitroPreset): PresetConfig {
   return PRESET_CONFIGS[preset];
 }
+
+/**
+ * Resolve the destination path for prebuilt flight payloads in the Nitro
+ * output directory. The RSC entry resolves `../prebuilt/` relative to its
+ * bundled chunk location (`<serverBundleDir>/_chunks/`), so prebuilt/ must
+ * live at `<serverBundleDir>/prebuilt/`.
+ *
+ * The serverBundleDir varies by preset — Nitro's Vercel preset uses
+ * `functions/__server.func` while most others use `server`.
+ *
+ * @internal Exported for testing.
+ */
+export function resolvePrebuiltOutputPath(outDir: string, preset: NitroPreset): string {
+  const presetConfig = PRESET_CONFIGS[preset];
+  return join(outDir, presetConfig.outputDir, presetConfig.serverBundleDir, 'prebuilt');
+}
+
+/**
+ * Copy prebuilt payloads into cloned Vercel function directories.
+ *
+ * When users configure `vercel.functionRules`, Nitro's compiled hook clones
+ * the base __server.func to per-route .func directories. These clones are
+ * created during `runNitroBuild()` — before our post-build prebuilt copy.
+ * Each clone resolves `../prebuilt` independently, so they each need a copy.
+ *
+ * @internal Exported for testing.
+ */
+export async function copyPrebuiltToVercelFuncClones(
+  functionsDir: string,
+  prebuiltSrc: string,
+  baseFuncName: string
+): Promise<void> {
+  const funcDirs: string[] = [];
+  try {
+    for await (const match of glob('**/*.func', { cwd: functionsDir })) {
+      if (!match.endsWith(baseFuncName)) {
+        funcDirs.push(join(functionsDir, match));
+      }
+    }
+  } catch {
+    return;
+  }
+  await Promise.all(
+    funcDirs.map((dir) =>
+      cp(prebuiltSrc, join(dir, 'prebuilt'), { recursive: true }).catch(
+        (e: NodeJS.ErrnoException) => {
+          if (e.code !== 'ENOENT') throw e;
+        }
+      )
+    )
+  );
+}

package/src/cache/index.ts

@@ -4,7 +4,11 @@ import { estimateByteSize } from './sizeof.js';
 
 export interface CacheHandler {
   get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
-  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
+  set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void>;
   invalidate(opts: { key?: string; tag?: string }): Promise<void>;
 }
 
@@ -38,6 +42,7 @@ export class MemoryCacheHandler implements CacheHandler {
     string,
     { value: unknown; expiresAt: number; tags: string[]; byteSize: number }
   >();
+  private generations = new Map<string, number>();
   private maxEntries: number;
   private maxBytes: number | undefined;
   private maxEntryBytes: number | undefined;
@@ -64,7 +69,17 @@ export class MemoryCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ) {
+    // CAS guard: skip write if a newer generation has already been written
+    if (opts.generation !== undefined) {
+      const current = this.generations.get(key) ?? 0;
+      if (opts.generation < current) return;
+    }
+
     const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
 
     // Reject entries exceeding per-entry byte limit
@@ -95,6 +110,11 @@ export class MemoryCacheHandler implements CacheHandler {
       }
     }
 
+    // Record generation only after all admission checks pass
+    if (opts.generation !== undefined) {
+      this.generations.set(key, opts.generation);
+    }
+
     this.store.set(key, {
       value,
       expiresAt: Date.now() + opts.ttl * 1000,
@@ -111,12 +131,14 @@ export class MemoryCacheHandler implements CacheHandler {
         this.currentBytes -= entry.byteSize;
         this.store.delete(opts.key);
       }
+      this.generations.delete(opts.key);
     }
     if (opts.tag) {
       for (const [key, entry] of this.store) {
         if (entry.tags.includes(opts.tag)) {
           this.currentBytes -= entry.byteSize;
           this.store.delete(key);
+          this.generations.delete(key);
         }
       }
     }
@@ -139,6 +161,7 @@ export class MemoryCacheHandler implements CacheHandler {
       const entry = this.store.get(oldest)!;
       this.currentBytes -= entry.byteSize;
       this.store.delete(oldest);
+      this.generations.delete(oldest);
     }
   }
 }

package/src/cache/redis-handler.ts

@@ -141,7 +141,11 @@ export class RedisCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
     const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
@@ -186,13 +190,29 @@ export class RedisCacheHandler implements CacheHandler {
       const tk = this.tagKey(opts.tag);
       const keys = await this.client.smembers(tk);
 
-      // One del per key: the only multi-key shape every client accepts.
-      // ioredis takes del(...keys), node-redis takes del(key | key[]), and
-      // @upstash/redis takes del(...keys) but breaks on an array argument.
-      await Promise.all(keys.map((k) => this.client.del(this.cacheKey(k))));
+      // Re-check each member before deleting — the tag set can contain stale
+      // memberships from entries whose tags changed since they were added.
+      // Mirrors TagAwareCacheHandler's eager strategy (tag-aware-handler.ts:183-198).
+      await Promise.all(
+        keys.map(async (k) => {
+          const raw = await this.client.get(this.cacheKey(k));
+          if (raw === null) {
+            await this.client.srem(tk, k);
+            return;
+          }
+          const entry = JSON.parse(raw) as { tags?: string[] };
+          if (entry.tags?.includes(opts.tag!)) {
+            await this.client.del(this.cacheKey(k));
+          }
+          await this.client.srem(tk, k);
+        })
+      );
 
-      // Clean up the tag set itself
-      await this.client.del(tk);
+      // Clean up the now-empty tag set so it doesn't consume memory
+      const remaining = await this.client.smembers(tk);
+      if (remaining.length === 0) {
+        await this.client.del(tk);
+      }
     }
   }
 }

package/src/cache/tag-aware-handler.ts

@@ -105,7 +105,11 @@ export class TagAwareCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+  async set(
+    key: string,
+    value: unknown,
+    opts: { ttl: number; tags: string[]; generation?: number }
+  ): Promise<void> {
     const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
 
     if (this.strategy === 'native') {

package/src/cache/timber-cache.ts

@@ -13,6 +13,22 @@ import { fnv1aHash } from './fast-hash.js';
 
 let defaultSingleflight = createSingleflight();
 
+/**
+ * Per-key monotonic generation counter for CAS writes (TIM-1158).
+ *
+ * Unbounded, like the singleflight map — the key space is the same set of
+ * cache keys the handler already tracks. Pruning was removed because it
+ * desyncs from MemoryCacheHandler.generations: a pruned key restarts at 1
+ * while the handler still holds the old higher generation, causing fresh
+ * writes to be rejected as stale.
+ */
+const writeGenerations = new Map<string, number>();
+function nextGeneration(key: string): number {
+  const gen = (writeGenerations.get(key) ?? 0) + 1;
+  writeGenerations.set(key, gen);
+  return gen;
+}
+
 /**
  * Set the timeout for the module-level default singleflight.
  * Called at framework boot with renderTimeoutMs from timber.config.ts so that
@@ -164,21 +180,16 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
      * - the key/tags were invalidated after fn started (TIM-1028), or
      * - the singleflight timed out (signal aborted) — the timed-out
      *   flight's write could overwrite a newer value from a subsequent
-     *   flight (TIM-1092).
-     *
-     * Residual race: if fn() completes within the timeout but
-     * handler.set() is slow enough that the timeout fires during the
-     * set, the write lands with stale data. This window is narrow
-     * (requires set latency to straddle the timeout boundary) and
-     * self-healing (next cache miss triggers a fresh write). Fully
-     * closing it requires CAS/versioned writes on CacheHandler —
-     * tracked in TIM-1158.
+     *   flight (TIM-1092), or
+     * - the handler rejects the write because a newer generation has
+     *   already been stored (TIM-1158 CAS guard).
      */
     const executeAndStore = async (signal: AbortSignal): Promise<Awaited<ReturnType<Fn>>> => {
       const startEpoch = currentInvalidationEpoch();
+      const generation = nextGeneration(key);
       const result = await fn(...args);
       if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
-        await getHandler().set(key, result, { ttl: opts.ttl, tags });
+        await getHandler().set(key, result, { ttl: opts.ttl, tags, generation });
       }
       return result;
     };