@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/adapters/nitro.ts

@@ -200,7 +200,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // 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());
+      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.
@@ -257,8 +257,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  compress = true,
-  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.
@@ -315,11 +314,6 @@ 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' : '';
 
@@ -329,7 +323,7 @@ export function generateNitroEntry(
   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 handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 ${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
@@ -349,38 +343,6 @@ ${handlerCall}
 `;
 }
 
-/** @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 } },
-      '/_timber/fonts/**': { 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})
-`;
-}
-
 // ─── Preview ─────────────────────────────────────────────────────────────────
 
 /** Presets that produce a locally-runnable server entry. */

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/cache/cache-api.ts

@@ -1,6 +1,7 @@
 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)`.
@@ -23,7 +24,11 @@ export function cache<Fn extends (...args: any[]) => Promise<any>>(
   opts: CacheOptions<Fn>,
   stableId?: string
 ): Fn {
-  return createCache(fn, opts, getCacheHandler(), stableId);
+  // 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);
 }
 
 /**
@@ -35,5 +40,8 @@ export function cache<Fn extends (...args: any[]) => Promise<any>>(
  * ```
  */
 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/index.ts

@@ -42,12 +42,14 @@ export class MemoryCacheHandler implements CacheHandler {
   private maxBytes: number | undefined;
   private maxEntryBytes: number | undefined;
   private currentBytes = 0;
+  private readonly _trackBytes: boolean;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
     // maxEntries takes precedence over deprecated maxSize
     this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1000;
     this.maxBytes = opts?.maxBytes;
     this.maxEntryBytes = opts?.maxEntryBytes;
+    this._trackBytes = this.maxBytes !== undefined || this.maxEntryBytes !== undefined;
   }
 
   async get(key: string) {
@@ -63,7 +65,7 @@ export class MemoryCacheHandler implements CacheHandler {
   }
 
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    const byteSize = estimateByteSize(value);
+    const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
 
     // Reject entries exceeding per-entry byte limit
     if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
@@ -125,7 +127,7 @@ export class MemoryCacheHandler implements CacheHandler {
     return this.store.size;
   }
 
-  /** Estimated total byte size of all cached values. */
+  /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */
   get bytes(): number {
     return this.currentBytes;
   }
@@ -145,6 +147,7 @@ export { RedisCacheHandler } from './redis-handler';
 export type { RedisClient } from './redis-handler';
 export { cache } from './cache-api';
 export { setCacheHandler, getCacheHandler } from './handler-store';
+export { setDefaultSingleflightTimeout } from './timber-cache';
 // NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
 // Future feature pending design doc. See design/06-caching.md.
 export { estimateByteSize } from './sizeof';

package/src/cache/invalidation-epoch.ts

@@ -0,0 +1,93 @@
+/**
+ * Per-process invalidation epoch tracking for timber.cache (TIM-1028).
+ *
+ * handler.set for a cache miss runs after `fn()` resolves. An explicit
+ * `cache.invalidate({ tag })` / `revalidateTag` that lands while fn is in
+ * flight would otherwise be silently undone — the just-invalidated value
+ * re-stored as fresh for the full TTL, resurrecting pre-mutation data.
+ *
+ * Every invalidation bumps a monotonic epoch and records it against the
+ * invalidated key/tag. Before storing a result, the cache wrapper checks
+ * whether its key or any of its tags were invalidated after fn started and
+ * skips the write if so. Skipping is always safe: the only cost is one
+ * extra cache miss on the next call.
+ *
+ * Scope: per-process, like the singleflight map. An invalidation issued by
+ * another instance against a shared handler (Redis/KV) during fn flight is
+ * not observable here — closing that window fully would require store-level
+ * versioning, which no CacheHandler backend offers.
+ */
+
+let epoch = 0;
+
+/**
+ * Last-invalidated epoch per `key:<k>` / `tag:<t>` entry. Insertion order is
+ * epoch order (entries are re-inserted on update), so the oldest entry is
+ * always first — pruning evicts lowest epochs.
+ */
+const lastInvalidated = new Map<string, number>();
+
+/**
+ * Bound on tracked entries so high-cardinality tag invalidation (e.g.
+ * per-user tags) cannot grow this map without limit.
+ */
+const MAX_TRACKED_ENTRIES = 10_000;
+
+/**
+ * Highest epoch evicted from the map. Any execution that started at or
+ * before this epoch conservatively counts as invalidated — history was
+ * truncated, so we can no longer prove it wasn't.
+ */
+let evictedEpochFloor = 0;
+
+/** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
+export function currentInvalidationEpoch(): number {
+  return epoch;
+}
+
+/**
+ * Record an invalidation. Call BEFORE handler.invalidate() so an execution
+ * whose set-check races the invalidation errs toward skipping the write.
+ */
+export function recordInvalidation(opts: { key?: string; tag?: string }): void {
+  epoch++;
+  if (opts.key) track(`key:${opts.key}`);
+  if (opts.tag) track(`tag:${opts.tag}`);
+}
+
+function track(entry: string): void {
+  lastInvalidated.delete(entry);
+  lastInvalidated.set(entry, epoch);
+  while (lastInvalidated.size > MAX_TRACKED_ENTRIES) {
+    const oldest = lastInvalidated.entries().next().value;
+    if (oldest === undefined) break;
+    evictedEpochFloor = Math.max(evictedEpochFloor, oldest[1]);
+    lastInvalidated.delete(oldest[0]);
+  }
+}
+
+/**
+ * Whether the key or any tag was invalidated after `startEpoch` (the epoch
+ * captured when fn started executing).
+ */
+export function wasInvalidatedSince(startEpoch: number, key: string, tags: string[]): boolean {
+  return lastInvalidationEpochFor(key, tags) > startEpoch;
+}
+
+/**
+ * The highest epoch at which the key or any of the tags was invalidated
+ * (0 if never). Used to scope the singleflight key: callers arriving after
+ * an invalidation must not coalesce onto a flight that started before it —
+ * they would receive the pre-invalidation result the invalidation was
+ * issued to discard.
+ */
+export function lastInvalidationEpochFor(key: string, tags: string[]): number {
+  let last = evictedEpochFloor;
+  const keyEpoch = lastInvalidated.get(`key:${key}`);
+  if (keyEpoch !== undefined && keyEpoch > last) last = keyEpoch;
+  for (const tag of tags) {
+    const tagEpoch = lastInvalidated.get(`tag:${tag}`);
+    if (tagEpoch !== undefined && tagEpoch > last) last = tagEpoch;
+  }
+  return last;
+}

package/src/cache/redis-handler.ts

@@ -23,7 +23,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, ...m),
+ *   srem: (k, ...m) => redis.srem(k, ...m),
  *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  *
@@ -38,7 +40,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sAdd(k, m),
+ *   srem: (k, ...m) => redis.sRem(k, m),
  *   smembers: (k) => redis.sMembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  *
@@ -54,7 +58,9 @@ import type { CacheHandler } from './index';
  *   expire: (k, s) => redis.expire(k, s),
  *   del: (k) => redis.del(k),
  *   sadd: (k, ...m) => redis.sadd(k, m[0], ...m.slice(1)),
+ *   srem: (k, ...m) => redis.srem(k, m[0], ...m.slice(1)),
  *   smembers: (k) => redis.smembers(k),
+ *   ttl: (k) => redis.ttl(k),
  * };
  * ```
  */
@@ -72,8 +78,15 @@ export interface RedisClient {
   del(key: string): Promise<unknown>;
   /** `SADD key member [member ...]` — add members to a set. */
   sadd(key: string, ...members: string[]): Promise<unknown>;
+  /** `SREM key member [member ...]` — remove members from a set. */
+  srem(key: string, ...members: string[]): Promise<unknown>;
   /** `SMEMBERS key` — all members of a set. */
   smembers(key: string): Promise<string[]>;
+  /**
+   * `TTL key` — remaining time-to-live in seconds. Returns -2 if the key does
+   * not exist, -1 if the key exists but has no expiry.
+   */
+  ttl(key: string): Promise<number>;
 }
 
 const KEY_PREFIX = 'timber:cache:';
@@ -119,7 +132,7 @@ export class RedisCacheHandler implements CacheHandler {
   async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
     const ck = this.cacheKey(key);
     const expiresAt = Date.now() + opts.ttl * 1000;
-    const payload = JSON.stringify({ value, expiresAt });
+    const payload = JSON.stringify({ value, expiresAt, tags: opts.tags });
 
     // Redis TTL with generous margin beyond the logical TTL to allow SWR reads
     // on stale entries. The logical staleness is determined by expiresAt.
@@ -128,14 +141,32 @@ export class RedisCacheHandler implements CacheHandler {
     const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
     await this.client.set(ck, payload, redisTtlSeconds);
 
-    // Track key membership in each tag set
+    // Track key membership in each tag set, and expire the set so it doesn't
+    // outlive all its members. Only extend the TTL, never shorten — a short-TTL
+    // entry must not shrink a tag set that already contains long-TTL entries,
+    // otherwise invalidate({tag}) would miss the long-lived entries.
     for (const tag of opts.tags) {
       await this.client.sadd(this.tagKey(tag), key);
+      const currentTtl = await this.client.ttl(this.tagKey(tag));
+      // Only extend, never shorten. -2 = key doesn't exist (rare race after
+      // sadd), -1 = no expiry (new set or legacy — set initial TTL), positive
+      // but shorter = extend. A longer current TTL means a longer-lived entry
+      // set it first — don't shorten.
+      if (currentTtl < redisTtlSeconds) {
+        await this.client.expire(this.tagKey(tag), redisTtlSeconds);
+      }
     }
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
     if (opts.key) {
+      const raw = await this.client.get(this.cacheKey(opts.key));
+      if (raw !== null) {
+        const entry = JSON.parse(raw) as { tags?: string[] };
+        if (entry.tags) {
+          await Promise.all(entry.tags.map((tag) => this.client.srem(this.tagKey(tag), opts.key!)));
+        }
+      }
       await this.client.del(this.cacheKey(opts.key));
     }
 

package/src/cache/timber-cache.ts

@@ -1,12 +1,27 @@
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
+import {
+  currentInvalidationEpoch,
+  lastInvalidationEpochFor,
+  wasInvalidatedSince,
+} from './invalidation-epoch';
 import { addSpanEventSync } from '../server/tracing.js';
 import { logSwrRefetchFailed } from '../server/logger.js';
 import { getWaitUntil } from '../server/waituntil-bridge.js';
 import { fnv1aHash } from './fast-hash.js';
 
-const defaultSingleflight = createSingleflight();
+let defaultSingleflight = createSingleflight();
+
+/**
+ * Set the timeout for the module-level default singleflight.
+ * Called at framework boot with renderTimeoutMs from timber.config.ts so that
+ * cache calls without a per-call timeoutMs still get deadlock protection.
+ * See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+ */
+export function setDefaultSingleflightTimeout(timeoutMs: number): void {
+  defaultSingleflight = createSingleflight({ timeoutMs });
+}
 
 /**
  * Generate a cache key from function identity and serialized args.
@@ -35,16 +50,59 @@ function resolveTags<Fn extends (...args: any[]) => any>(
   return opts.tags(...args);
 }
 
-let unstableIdCounter = 0;
-let hasWarnedUnstableId = false;
+/** Per-process count of byte-identical fn sources seen by deriveFallbackFnId. */
+const fallbackIdOccurrences = new Map<string, number>();
+let hasWarnedFallbackId = false;
+
+/**
+ * Derive a fallback fnId for callsites the timber-cache-transform Vite plugin
+ * could not statically detect (aliased bindings, user re-export wrappers).
+ *
+ * The base is fnv1a(fn.toString()) — deterministic across instances and cold
+ * starts of the same build, so two *different* functions can never swap fnIds
+ * by module-evaluation order (the TIM-997 poisoning scenario that the old
+ * process-local counter allowed; see TIM-1054). A per-process occurrence
+ * suffix disambiguates byte-identical duplicate sources. That residue is the
+ * one remaining hazard: closures produced by the same factory share source
+ * text but capture different values, and their occurrence order may differ
+ * across instances — such callsites need an explicit `key` option.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function deriveFallbackFnId(fn: (...args: any[]) => any): string {
+  const sourceHash = fnv1aHash(fn.toString());
+  const occurrence = fallbackIdOccurrences.get(sourceHash) ?? 0;
+  fallbackIdOccurrences.set(sourceHash, occurrence + 1);
+
+  if (!hasWarnedFallbackId && typeof process !== 'undefined' && process.env?.NODE_ENV !== 'test') {
+    hasWarnedFallbackId = true;
+    console.warn(
+      '[timber] cache() callsite has no build-time stable ID and no explicit `key` option — ' +
+        'the call is not statically visible to the timber Vite plugin (e.g. an aliased ' +
+        'binding like `const c = cache` or a re-export wrapper module). Falling back to a ' +
+        'function-source hash for the cache key. With a shared CacheHandler (Redis/KV) this ' +
+        'is safe for distinct functions, but byte-identical closures from a factory can swap ' +
+        'cache entries across instances. Provide an explicit `key` option to make the cache ' +
+        'key contract stable and auditable.'
+    );
+  }
+
+  return `timber-cache:fn:${sourceHash}:${occurrence}`;
+}
 
 /**
  * Creates a cached wrapper around an async function.
  *
- * - SHA-256 default keys with normalized JSON args
- * - Singleflight: concurrent misses → single execution
+ * - FNV-1a default keys with normalized JSON args
+ * - Singleflight: concurrent misses → single execution AND single
+ *   handler.set — the write happens inside the coalesced callback (TIM-1028)
+ * - Writes are skipped when the key/tags were invalidated while fn was in
+ *   flight, so explicit invalidation is never silently undone (TIM-1028)
  * - SWR: serve stale immediately, background refetch
  * - Tags as string[] or function of args
+ * - The handler is resolved per invocation via `getHandler`, never captured
+ *   at wrapper-creation time — module-scope cache() wrappers created before
+ *   the framework's boot wiring calls setCacheHandler() still use the
+ *   configured handler once it arrives (TIM-1029)
  * - No ALS dependency for correctness — cache() works outside a request
  *   context. The waitUntil ALS bridge is read optionally so the SWR
  *   background refetch survives handler return on Workers/Lambda.
@@ -56,44 +114,30 @@ let hasWarnedUnstableId = false;
 export function createCache<Fn extends (...args: any[]) => Promise<any>>(
   fn: Fn,
   opts: CacheOptions<Fn>,
-  handler: CacheHandler,
+  getHandler: () => CacheHandler,
   stableId?: string
 ): Fn {
-  let fnId: string;
-  if (stableId) {
-    fnId = stableId;
-  } else if (opts.key) {
-    // Explicit key function — fnId is only used for singleflight, not for
-    // cache keys, so a counter is acceptable here.
-    fnId = `timber-cache:${unstableIdCounter++}`;
-  } else {
-    fnId = `timber-cache:unstable:${unstableIdCounter++}`;
-    if (
-      !hasWarnedUnstableId &&
-      typeof process !== 'undefined' &&
-      process.env?.NODE_ENV !== 'test'
-    ) {
-      hasWarnedUnstableId = true;
-      console.warn(
-        '[timber] cache() called without a stable ID or explicit key function. ' +
-          'Cache keys will use a process-local counter which is unstable across ' +
-          'cold starts. Run through the timber Vite plugin or provide an explicit ' +
-          '`key` option to fix this.'
-      );
-    }
-  }
-  const sf = opts.timeoutMs
-    ? createSingleflight({ timeoutMs: opts.timeoutMs })
-    : defaultSingleflight;
+  // With an explicit `key` option the fnId never reaches key generation, so
+  // no fallback derivation (or warning) is needed in that case.
+  const fnId = stableId ?? (opts.key ? undefined : deriveFallbackFnId(fn));
+
+  // Per-call timeoutMs gets a dedicated singleflight instance. Otherwise
+  // resolve defaultSingleflight per invocation (not captured at creation
+  // time) so wrappers created before boot pick up the timeout once
+  // setDefaultSingleflightTimeout is called (TIM-1032, same rationale as
+  // getCacheHandler for TIM-1029).
+  const perCallSf =
+    opts.timeoutMs !== undefined ? createSingleflight({ timeoutMs: opts.timeoutMs }) : undefined;
 
   // 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 sf = perCallSf ?? defaultSingleflight;
+    const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId as string, args);
 
     const cacheStart = performance.now();
-    const cached = await handler.get(key);
+    const cached = await getHandler().get(key);
 
     if (cached && !cached.stale) {
       // Record as OTEL span event on enclosing span (not a child span).
@@ -105,6 +149,30 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
+    // From here fn() will execute (SWR refetch or miss). Scope the
+    // singleflight key by the last invalidation epoch affecting this
+    // key/tags: a caller arriving after an invalidation must not coalesce
+    // onto a flight that started before it — it would receive the
+    // pre-invalidation result the invalidation was issued to discard.
+    // NUL separator: cannot collide with user-provided key strings.
+    const tags = resolveTags(opts, args);
+    const flightKey = `${key}\u0000${lastInvalidationEpochFor(key, tags)}`;
+
+    /**
+     * Run fn and store the result — exactly once per coalesced execution,
+     * inside the singleflight callback. The write is skipped when the key or
+     * any resolved tag was invalidated after fn started: storing would
+     * resurrect just-invalidated data as fresh for the full TTL.
+     */
+    const executeAndStore = async (): Promise<Awaited<ReturnType<Fn>>> => {
+      const startEpoch = currentInvalidationEpoch();
+      const result = await fn(...args);
+      if (!wasInvalidatedSince(startEpoch, key, tags)) {
+        await getHandler().set(key, result, { ttl: opts.ttl, tags });
+      }
+      return result;
+    };
+
     if (cached && cached.stale && opts.staleWhileRevalidate) {
       // Record stale cache hit as OTEL span event (fire-and-forget).
       addSpanEventSync('timber.cache.hit', {
@@ -114,11 +182,9 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       });
       // Serve stale immediately, trigger background refetch
       const refetch = sf
-        .do(`swr:${key}`, async () => {
+        .do(`swr:${flightKey}`, async () => {
           try {
-            const fresh = await fn(...args);
-            const tags = resolveTags(opts, args);
-            await handler.set(key, fresh, { ttl: opts.ttl, tags });
+            await executeAndStore();
           } catch (err) {
             // Failed refetch — stale entry continues to be served.
             logSwrRefetchFailed({ cacheKey: key, error: err });
@@ -137,10 +203,10 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       return cached.value as Awaited<ReturnType<Fn>>;
     }
 
-    // Cache miss (or stale without SWR) — execute with singleflight
-    const result = await sf.do(key, () => fn(...args));
-    const tags = resolveTags(opts, args);
-    await handler.set(key, result, { ttl: opts.ttl, tags });
+    // Cache miss (or stale without SWR) — execute with singleflight.
+    // The handler.set lives inside the coalesced callback, so N concurrent
+    // misses produce exactly one write (TIM-1028).
+    const result = await sf.do(flightKey, executeAndStore);
 
     // Record cache miss as OTEL span event (fire-and-forget).
     addSpanEventSync('timber.cache.miss', {
@@ -148,16 +214,6 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       duration_ms: Math.round(performance.now() - cacheStart),
     });
 
-    return result as Awaited<ReturnType<Fn>>;
+    return result;
   }) as unknown as Fn;
 }
-
-/**
- * Invalidate cache entries by tag or key.
- */
-createCache.invalidate = async function invalidate(
-  handler: CacheHandler,
-  opts: { key?: string; tag?: string }
-): Promise<void> {
-  await handler.invalidate(opts);
-};