@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/src/adapters/compress-module.ts

@@ -1,101 +1,36 @@
-// Generated compression module template for self-hosted deployments.
+// Compiles server/compress.ts into a standalone ESM module (_compress.mjs)
+// for self-hosted deployments. The adapter writes this to the build output
+// during buildOutput(). It's imported by the Nitro entry and preview server
+// at runtime.
 //
-// This file generates a standalone ESM module (_compress.mjs) that is
-// written to the build output during adapter buildOutput(). It's imported
-// by the Nitro entry and preview server at runtime.
-//
-// 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.
-// Cloudflare Workers don't need this — the edge auto-compresses.
-//
-// See design/25-production-deployments.md.
+// By compiling the actual TypeScript source rather than maintaining a
+// hand-written string template, any fix to server/compress.ts automatically
+// flows to the production module. See design/18-build-system.md ("entry
+// modules are real TypeScript files, not codegen strings").
+
+import { transformWithOxc } from 'vite';
+// Vite's ?raw import embeds the file as a string at build time — works
+// in both dev (Vite resolves the TS source) and the published package
+// (the string is inlined into the compiled adapter entry).
+import compressSource from '../server/compress.ts?raw';
 
 /**
- * Generate a standalone ESM module that exports compressResponse().
+ * Compile server/compress.ts into a standalone ESM module.
  *
- * Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
- * and preview server.
+ * Uses Vite's OXC transform to strip TypeScript types from the
+ * embedded source. The result is written to `_compress.mjs` during
+ * buildOutput.
  *
  * @internal Exported for testing.
  */
-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.
-
-const COMPRESSIBLE_TYPES = new Set([
-  'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
-  'text/x-component', 'application/json', 'application/javascript',
-  'application/xml', 'application/xhtml+xml', 'application/rss+xml',
-  'application/atom+xml', 'image/svg+xml',
-]);
-
-const NO_COMPRESS_STATUSES = new Set([204, 304]);
-
-function negotiateEncoding(acceptEncoding) {
-  if (!acceptEncoding) return null;
-  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
-  // "not acceptable" — the client explicitly rejects that encoding.
-  // Brotli (br) is intentionally not handled at the application level.
-  const parts = acceptEncoding.split(',');
-  for (const part of parts) {
-    const [token, ...params] = part.split(';');
-    const name = token.trim().toLowerCase();
-    if (name !== 'gzip') continue;
-    let qValue = 1;
-    for (const param of params) {
-      const trimmed = param.trim().toLowerCase();
-      if (trimmed.startsWith('q=')) {
-        qValue = parseFloat(trimmed.slice(2));
-        if (Number.isNaN(qValue)) qValue = 1;
-        break;
-      }
-    }
-    if (qValue > 0) return 'gzip';
-  }
-  return null;
-}
-
-function shouldCompress(response) {
-  if (!response.body) return false;
-  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
-  if (response.headers.has('Content-Encoding')) return false;
-  const contentType = response.headers.get('Content-Type');
-  if (!contentType) return false;
-  const mimeType = contentType.split(';')[0].trim().toLowerCase();
-  if (mimeType === 'text/event-stream') return false;
-  return COMPRESSIBLE_TYPES.has(mimeType);
-}
-
-function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
-}
-
-export function compressResponse(request, response) {
-  if (!shouldCompress(response)) return response;
-  const acceptEncoding = request.headers.get('Accept-Encoding') || '';
-  const encoding = negotiateEncoding(acceptEncoding);
-  if (!encoding) return response;
-  const compressedBody = compressWithGzip(response.body);
-  const headers = new Headers(response.headers);
-  headers.set('Content-Encoding', encoding);
-  headers.delete('Content-Length');
-  const existingVary = headers.get('Vary');
-  if (existingVary) {
-    if (!existingVary.toLowerCase().includes('accept-encoding')) {
-      headers.set('Vary', existingVary + ', Accept-Encoding');
-    }
-  } else {
-    headers.set('Vary', 'Accept-Encoding');
-  }
-  return new Response(compressedBody, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
+export async function generateCompressModule(): Promise<string> {
+  const result = await transformWithOxc(compressSource, 'compress.ts', {
+    lang: 'ts',
   });
-}
-`;
+
+  return (
+    '// Generated by @timber-js/app — compiled from server/compress.ts.\n' +
+    '// Do not edit — this file is regenerated on each build.\n' +
+    result.code
+  );
 }

package/src/adapters/nitro.ts

@@ -5,28 +5,13 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, mkdir, cp } from 'node:fs/promises';
+import { writeFile, readFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
 import { generateCompressModule } from './compress-module.js';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
+import { IMMUTABLE_CACHE } from './shared.js';
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
 
@@ -149,6 +134,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 +178,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>[] = [];
 
@@ -184,39 +187,20 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'nitro');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to public directory.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      const clientDir = join(buildDir, 'client');
-      const publicDir = join(outDir, 'public');
-      await mkdir(publicDir, { recursive: true });
-      await cp(clientDir, publicDir, {
-        recursive: true,
-        filter: config.clientJavascriptDisabled ? (src: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
-
-      // Write _headers file for platforms that support it (Netlify, etc.).
-      // See design/25-production-deployments.md §"CDN / Edge Cache"
-      await writeFile(join(publicDir, '_headers'), generateHeadersFile());
 
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'public',
+      });
 
       // Write the compression helper module for runtime use.
       // 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'), generateCompressModule());
-
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+      await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
@@ -229,7 +213,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,7 +257,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  hasManifestInit = false
+  compress = true
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
   // rsc/ is copied into the nitro dir so the import is local.
@@ -330,20 +314,17 @@ export function generateNitroEntry(
     handlerCall = `  const webResponse = await handler(webRequest)`;
   }
 
-  // Build manifest init must be imported before the handler so that
-  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.
-  // ESM guarantees imports are evaluated in order.
-  const manifestImport = hasManifestInit ? "import './_timber-manifest-init.js'\n" : '';
-
   // 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'
-
+import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
@@ -357,39 +338,8 @@ 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}
 }
-
-/** @internal Exported for testing. */
-export function generateNitroConfig(
-  preset: NitroPreset,
-  userConfig?: Record<string, unknown>
-): string {
-  const presetConfig = PRESET_CONFIGS[preset];
-
-  const config: Record<string, unknown> = {
-    preset: presetConfig.nitroPreset,
-    entry: './entry.ts',
-    output: { dir: presetConfig.outputDir },
-    // Static asset cache headers — hashed assets are immutable, others get 1h.
-    // See design/25-production-deployments.md §"CDN / Edge Cache"
-    routeRules: {
-      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-    },
-    ...presetConfig.extraConfig,
-    ...userConfig,
-  };
-
-  const configJson = JSON.stringify(config, null, 2);
-
-  return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-import { defineNitroConfig } from 'nitro/config'
-
-export default defineNitroConfig(${configJson})
 `;
 }
 
@@ -465,11 +415,32 @@ const MIME_TYPES = {
 };
 
 const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
+
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+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';
 
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
+
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -482,7 +453,9 @@ const server = createServer(async (req, res) => {
         const contentType = MIME_TYPES[ext] || 'application/octet-stream';
         const body = await readFile(filePath);
         // Hashed assets get immutable cache, others get short cache.
-        const cacheControl = url.pathname.startsWith('/assets/')
+        const isImmutable =
+          url.pathname.startsWith('/assets/') || url.pathname.startsWith('/_timber/fonts/');
+        const cacheControl = isImmutable
           ? 'public, max-age=31536000, immutable'
           : 'public, max-age=3600, must-revalidate';
         res.writeHead(200, {
@@ -540,18 +513,64 @@ const server = createServer(async (req, res) => {
     const webResponse = compressResponse(webRequest, rawResponse);
 
     // Write the response back to the Node response.
-    res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
+    //
+    // 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();
-      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();
     }
@@ -564,13 +583,49 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+function listenWithBump(port, attempt = 0) {
+  return new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+      server.removeListener('listening', onListening);
+      if (err && err.code === 'EADDRINUSE' && !portIsExplicit && attempt < 100) {
+        if (attempt === 0) {
+          console.log(\`  [timber] Port \${port} in use, trying \${port + 1}...\`);
+        }
+        listenWithBump(port + 1, attempt + 1).then(resolveListen, rejectListen);
+        return;
+      }
+      rejectListen(err);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolveListen(port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+try {
+  boundPort = await listenWithBump(startPort);
+  if (boundPort !== startPort) {
+    console.log();
+    console.log(\`  [timber] Port \${startPort} in use, using \${boundPort}\`);
+  }
   console.log();
   console.log('  ⚡ timber preview server running at:');
   console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
+  console.log(\`    ➜  http://\${host}:\${boundPort}\`);
   console.log();
-});
+} catch (err) {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(\`[timber] Port \${startPort} is already in use. \` +
+      'Set PORT to a free port, or unset PORT to auto-pick.');
+  } else {
+    console.error('[timber] Failed to start preview server:', err);
+  }
+  process.exit(1);
+}
 `;
 }
 
@@ -628,6 +683,7 @@ async function runNitroBuild(
     output: { dir: join(nitroDir, presetConfig.outputDir) },
     routeRules: {
       '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
+      '/_timber/fonts/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
     },
     // Don't bundle the timber RSC/SSR build output — it has its own
     // internal file references that nitro's bundler can't follow.

package/src/adapters/raw-imports.d.ts

@@ -0,0 +1,5 @@
+// Vite ?raw import — embeds a file as a string at build time.
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/adapters/shared.ts

@@ -0,0 +1,40 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Vite places all hashed chunks under `/assets/` — these get immutable caching.
+ * Everything else (favicon.ico, robots.txt, etc.) gets a shorter cache.
+ */
+export function generateHeadersFile(): string {
+  return `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/*
+  Cache-Control: ${STATIC_CACHE}
+`;
+}

package/src/adapters/wrangler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type stub for the optional `wrangler` peer dependency.
+ * Prevents TS2307 during declaration emit when wrangler is not installed.
+ */
+declare module 'wrangler' {
+  export function getPlatformProxy(opts?: any): Promise<any>;
+}

package/src/cache/cache-api.ts

@@ -0,0 +1,47 @@
+import type { CacheOptions } from './index';
+import { createCache } from './timber-cache';
+import { getCacheHandler } from './handler-store';
+import { recordInvalidation } from './invalidation-epoch';
+
+/**
+ * Public caching API: `cache(fn, opts)`.
+ *
+ * Wraps an async function with cross-request caching. Uses the configured
+ * cache handler (defaults to MemoryCacheHandler, overridable via timber.config.ts).
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function cache<Fn extends (...args: any[]) => Promise<any>>(
+  fn: Fn,
+  opts: CacheOptions<Fn>,
+  stableId?: string
+): Fn {
+  // Pass the getter, not a resolved handler: the wrapper re-resolves it on
+  // every call, so module-scope wrappers created before the framework's boot
+  // wiring calls setCacheHandler() still pick up the configured handler
+  // instead of permanently binding the in-memory fallback (TIM-1029).
+  return createCache(fn, opts, getCacheHandler, stableId);
+}
+
+/**
+ * Invalidate cache entries by tag or key.
+ *
+ * ```ts
+ * cache.invalidate({ tag: 'products' });
+ * cache.invalidate({ key: 'user:abc' });
+ * ```
+ */
+cache.invalidate = async function invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+  // Record before the handler delete so a cached fn in flight skips its
+  // post-resolve set instead of resurrecting the invalidated value (TIM-1028).
+  recordInvalidation(opts);
+  await getCacheHandler().invalidate(opts);
+};

package/src/cache/handler-store.ts

@@ -0,0 +1,68 @@
+/**
+ * Module-level cache handler singleton.
+ *
+ * Lazily initialized to MemoryCacheHandler on first access. The framework
+ * replaces this at boot from timber.config.ts via setCacheHandler().
+ *
+ * This module avoids importing from ./index to prevent circular dependencies.
+ */
+
+// Inline the interface to avoid circular import with index.ts
+interface CacheHandlerLike {
+  get(key: string): Promise<{ value: unknown; stale: boolean } | null>;
+  set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void>;
+  invalidate(opts: { key?: string; tag?: string }): Promise<void>;
+}
+
+let handler: CacheHandlerLike | null = null;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+}
+
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export function getCacheHandler(): CacheHandlerLike {
+  if (!handler) {
+    // Inline a minimal LRU cache to avoid circular dep with index.ts.
+    // In production, the framework always calls setCacheHandler() at boot.
+    handler = createDefaultHandler();
+  }
+  return handler;
+}
+
+function createDefaultHandler(): CacheHandlerLike {
+  const store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
+  const maxEntries = 1000;
+
+  return {
+    async get(key) {
+      const entry = store.get(key);
+      if (!entry) return null;
+      store.delete(key);
+      store.set(key, entry);
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    },
+    async set(key, value, opts) {
+      if (store.has(key)) store.delete(key);
+      while (store.size >= maxEntries) {
+        const oldest = store.keys().next().value;
+        if (oldest !== undefined) store.delete(oldest);
+        else break;
+      }
+      store.set(key, { value, expiresAt: Date.now() + opts.ttl * 1000, tags: opts.tags });
+    },
+    async invalidate(opts) {
+      if (opts.key) store.delete(opts.key);
+      if (opts.tag) {
+        for (const [key, entry] of store) {
+          if (entry.tags.includes(opts.tag)) store.delete(key);
+        }
+      }
+    },
+  };
+}