@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/analyze/scan.ts

@@ -0,0 +1,149 @@
+/**
+ * scan — project source-file disk scan shared by the crawl and the
+ * graph cache.
+ *
+ * One walker, one rule set: the crawl uses it to find files no graph
+ * reached (the provisional/pending set) and to bound graph membership,
+ * and the mtime-keyed graph cache fingerprints exactly the same file
+ * set — the three can never disagree about what "the project" is (a
+ * file the crawl classifies but the fingerprint ignores would make the
+ * cache silently stale).
+ *
+ * Skip rules are deliberately shallow: timber's router excludes only
+ * `_`-prefixed directories, so `app/.well-known/page.tsx` and
+ * `app/dist/page.tsx` are REAL routes — a rule that skipped `dist` or
+ * dot-directories at any depth would hide legitimate route files from
+ * the scan while the module graph still reached them (codex review,
+ * PR #1056). Therefore:
+ *
+ * - `node_modules` is skipped at ANY depth (never project source, and
+ *   graph membership excludes it identically)
+ * - dot-prefixed and build-output directories (`dist`, `coverage`, …)
+ *   are skipped only as the FIRST path segment under the root — that
+ *   is where `.git`, `.timber`, `.wrangler`, and real build outputs
+ *   live; deeper occurrences are walked
+ *
+ * Deliberately vite-free: the cache-hit path of `timber graph` reads
+ * this module without booting (or even importing) Vite.
+ *
+ * Design docs: 47-module-environment-tooling.md §2, §Cold-path policy.
+ */
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Slash-normalize a Windows path — Vite's `normalizePath` for the
+ * vite-free callers (the graph cache-hit path must not import Vite).
+ * Same platform guard as Vite's: posix paths pass through untouched,
+ * so a filename containing a literal backslash is never corrupted.
+ */
+export const normalizeSlashes: (path: string) => string =
+  process.platform === 'win32' ? (path) => path.replace(/\\/g, '/') : (path) => path;
+
+/** A scan failure the caller records instead of swallowing. */
+export interface ScanFailure {
+  dir: string;
+  message: string;
+}
+
+/**
+ * Directories never scanned when they are the first path segment under
+ * the root. `node_modules` is additionally skipped at any depth.
+ */
+export const SCAN_IGNORED_DIRS = new Set(['node_modules', 'dist', 'test-results', 'coverage']);
+
+/**
+ * Single source of truth for builtin source extensions. Includes mdx —
+ * timber supports page.mdx via pageExtensions, so an unreferenced MDX
+ * page must not vanish from --all output.
+ */
+const BUILTIN_EXTENSIONS = ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts', 'mdx'] as const;
+
+/** Regex form of BUILTIN_EXTENSIONS for file-basename matching. */
+export const SOURCE_EXTENSIONS = new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join('|')})$`);
+
+/** Set form for O(1) membership checks. */
+const BUILTIN_EXTENSION_SET = new Set<string>(BUILTIN_EXTENSIONS);
+
+/**
+ * Build a regex that matches SOURCE_EXTENSIONS plus any extra
+ * extensions from the user's pageExtensions config. Returns the
+ * builtin regex unchanged when nothing new is added.
+ */
+export function buildSourceExtensions(pageExtensions?: readonly string[]): RegExp {
+  if (!pageExtensions) return SOURCE_EXTENSIONS;
+  const extras = pageExtensions.filter((ext) => !BUILTIN_EXTENSION_SET.has(ext));
+  if (extras.length === 0) return SOURCE_EXTENSIONS;
+  const escaped = extras.map((ext) => ext.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  return new RegExp(`\\.(?:${BUILTIN_EXTENSIONS.join('|')}|${escaped.join('|')})$`);
+}
+
+/** Whether a directory SEGMENT is skipped at the given depth (0 = root child). */
+function isSkippedDirSegment(segment: string, depth: number): boolean {
+  if (segment === 'node_modules') return true;
+  if (depth === 0 && (segment.startsWith('.') || SCAN_IGNORED_DIRS.has(segment))) return true;
+  return false;
+}
+
+/** Whether a file basename is admitted as project source. */
+function isSourceBasename(base: string, depth: number, extensions?: RegExp): boolean {
+  if (depth === 0 && base.startsWith('.')) return false;
+  if (!(extensions ?? SOURCE_EXTENSIONS).test(base)) return false;
+  // Declaration files are types-only — they never run in any environment.
+  if (/\.d\.[mc]?ts$/.test(base)) return false;
+  return true;
+}
+
+/**
+ * Whether an absolute, slash-normalized path is one the scanner WOULD
+ * admit — the same segment rules the walker applies, so a
+ * directly-addressed path (`package.json`, `<root>/dist/generated.js`,
+ * `types.d.ts`, a nested node_modules file) is answered exactly the
+ * way the scan-based sweep would answer it: by exclusion. Existence
+ * and is-a-file checks remain the caller's (this is pure path logic).
+ */
+export function isScannableSourceFile(file: string, root: string, extensions?: RegExp): boolean {
+  if (!file.startsWith(root + '/')) return false;
+  const segments = file.slice(root.length + 1).split('/');
+  const base = segments[segments.length - 1];
+  for (let depth = 0; depth < segments.length - 1; depth++) {
+    if (isSkippedDirSegment(segments[depth], depth)) return false;
+  }
+  return isSourceBasename(base, segments.length - 1, extensions);
+}
+
+/**
+ * Recursively list project source files on disk.
+ *
+ * Unreadable directories are reported through `onFailure`, not thrown
+ * and not swallowed — this walker exists to keep files from silently
+ * vanishing, so a directory it cannot see must be visible too.
+ */
+export async function scanProjectSourceFiles(
+  dir: string,
+  out: string[],
+  onFailure: (failure: ScanFailure) => void,
+  depth = 0,
+  extensions?: RegExp
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    onFailure({
+      dir,
+      message: `directory scan failed: ${error instanceof Error ? error.message : String(error)}`,
+    });
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkippedDirSegment(entry.name, depth)) continue;
+      await scanProjectSourceFiles(full, out, onFailure, depth + 1, extensions);
+    } else if (entry.isFile() && isSourceBasename(entry.name, depth, extensions)) {
+      out.push(full);
+    }
+  }
+}

package/src/cache/cache-api.ts

@@ -0,0 +1,107 @@
+import type { CacheOptions } from './index.ts';
+import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime.ts';
+import { createCache } from './timber-cache.ts';
+import { getCacheHandler } from './handler-store.ts';
+import { recordInvalidation } from './invalidation-epoch.ts';
+import { writeTombstonesForTag } from '../server/prebuilt/overlay.ts';
+import { getCdnPurgeHandler } from '../cdn/purge-store.ts';
+
+const componentFallbackWarned = new WeakSet<object>();
+
+/**
+ * Cache namespace — `cache.data`, `cache.component`, `cache.invalidate`.
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache.data(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+export const cache = {
+  /**
+   * Wrap an async function with cross-request caching.
+   *
+   * The configured cache handler (defaults to MemoryCacheHandler, overridable
+   * via timber.config.ts) is re-resolved on every call, so module-scope
+   * wrappers created before `setCacheHandler()` still pick up the configured
+   * handler (TIM-1029).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data<Fn extends (...args: any[]) => Promise<any>>(
+    fn: Fn,
+    opts: CacheOptions<Fn>,
+    stableId?: string
+  ): Fn {
+    return createCache(fn, opts, getCacheHandler, stableId);
+  },
+
+  /**
+   * Invalidate cache entries by tag or key.
+   *
+   * ```ts
+   * cache.invalidate({ tag: 'products' });
+   * cache.invalidate({ key: 'user:abc' });
+   * ```
+   */
+  async 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);
+    // Write tombstones for build-seed entries carrying the tag (design/45
+    // §ISR mechanics). Runs AFTER handler.invalidate so the tombstone
+    // overwrites the cleared overlay slot. This covers ALL invalidation
+    // paths — actions, webhooks, route handlers — not just executeAction.
+    if (opts.tag) {
+      await writeTombstonesForTag(opts.tag);
+    }
+    // Trigger CDN purge if a handler is configured (design/25 §Layer 2).
+    // Purge is best-effort: a CDN API failure or timeout must not block
+    // cache invalidation. 10s ceiling prevents a hung CDN API from stalling
+    // the entire revalidateTag/action flow.
+    if (opts.tag) {
+      const purgeHandler = getCdnPurgeHandler();
+      if (purgeHandler) {
+        try {
+          await Promise.race([
+            purgeHandler.purgeTags([opts.tag]),
+            new Promise<void>((_, reject) =>
+              setTimeout(() => reject(new Error('CDN purge timed out (10s)')), 10_000)
+            ),
+          ]);
+        } catch (err) {
+          console.error('[timber] CDN purge failed for tag:', err);
+        }
+      }
+    }
+  },
+
+  /**
+   * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+   * transform does not rewrite — nested/computed/argument-position forms (see
+   * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+   * declarations are transformed and eligible for prebuilding; everything else
+   * lands here, warns once per component, and renders dynamically. Same
+   * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+   * an untraceable callsite degrades in performance, never in correctness.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  component<C extends (props: any) => unknown>(
+    componentFn: C,
+    _options?: PrebuiltComponentOptions
+  ): C {
+    if (!componentFallbackWarned.has(componentFn)) {
+      componentFallbackWarned.add(componentFn);
+      const name = componentFn.name || 'anonymous component';
+      console.warn(
+        `[timber] cache.component: "${name}" was not transformed at build time — ` +
+          `rendering dynamically. Only module-scope declarations ` +
+          `(const X = cache.component(...)) are prebuilt.`
+      );
+    }
+    return componentFn;
+  },
+};

package/src/cache/fast-hash.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ *
+ * Server-side only. The `_rsc` payload cache key deliberately does NOT use
+ * this — the origin compares that value, which makes it a check rather than
+ * a cache key, and FNV is solvable for a chosen digest. See
+ * `shared/rsc-cache-key.ts`.
+ *
+ * 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/handler-store.ts

@@ -0,0 +1,76 @@
+/**
+ * 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;
+
+let explicitlyConfigured = false;
+
+/** Replace the active cache handler. Called by the framework at boot. */
+export function setCacheHandler(h: CacheHandlerLike): void {
+  handler = h;
+  explicitlyConfigured = true;
+}
+
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export function isCacheHandlerConfigured(): boolean {
+  return explicitlyConfigured;
+}
+
+/**
+ * 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);
+        }
+      }
+    },
+  };
+}

package/src/cache/index.ts

@@ -1,8 +1,14 @@
 // @timber-js/app/cache — Caching primitives
 
+import { estimateByteSize } from './sizeof.ts';
+
 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>;
 }
 
@@ -12,19 +18,43 @@ 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 {
   /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+  maxEntries?: number;
+  /**
+   * @deprecated Use `maxEntries` instead. Will be removed in a future release.
+   * Alias for `maxEntries` — maximum number of entries (not bytes).
+   */
   maxSize?: number;
+  /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */
+  maxBytes?: number;
+  /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */
+  maxEntryBytes?: number;
 }
 
 export class MemoryCacheHandler implements CacheHandler {
-  private store = new Map<string, { value: unknown; expiresAt: number; tags: string[] }>();
-  private maxSize: number;
+  private store = new Map<
+    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;
+  private currentBytes = 0;
+  private readonly _trackBytes: boolean;
 
   constructor(opts?: MemoryCacheHandlerOptions) {
-    this.maxSize = opts?.maxSize ?? 1000;
+    // 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) {
@@ -39,37 +69,76 @@ export class MemoryCacheHandler implements CacheHandler {
     return { value: entry.value, stale };
   }
 
-  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }) {
-    // If key already exists, delete first to refresh insertion order
+  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
+    if (this.maxEntryBytes !== undefined && byteSize > this.maxEntryBytes) {
+      return;
+    }
+
+    // If key already exists, delete first to refresh insertion order and reclaim bytes
     if (this.store.has(key)) {
+      const existing = this.store.get(key)!;
+      this.currentBytes -= existing.byteSize;
       this.store.delete(key);
     }
 
-    // Evict oldest entries (front of Map) if at capacity
-    while (this.store.size >= this.maxSize) {
-      const oldest = this.store.keys().next().value;
-      if (oldest !== undefined) {
-        this.store.delete(oldest);
-      } else {
-        break;
+    // Evict oldest entries (front of Map) if at entry count capacity
+    while (this.store.size >= this.maxEntries) {
+      this.evictOldest();
+    }
+
+    // Evict oldest entries if byte budget would be exceeded
+    if (this.maxBytes !== undefined) {
+      while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) {
+        this.evictOldest();
+      }
+      // If the single entry exceeds the total byte budget, don't store it
+      if (this.currentBytes + byteSize > this.maxBytes) {
+        return;
       }
     }
 
+    // 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,
       tags: opts.tags,
+      byteSize,
     });
+    this.currentBytes += byteSize;
   }
 
   async invalidate(opts: { key?: string; tag?: string }) {
     if (opts.key) {
-      this.store.delete(opts.key);
+      const entry = this.store.get(opts.key);
+      if (entry) {
+        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);
         }
       }
     }
@@ -79,13 +148,37 @@ export class MemoryCacheHandler implements CacheHandler {
   get size(): number {
     return this.store.size;
   }
+
+  /** 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;
+  }
+
+  /** Evict the oldest entry (front of Map). */
+  private evictOldest(): void {
+    const oldest = this.store.keys().next().value;
+    if (oldest !== undefined) {
+      const entry = this.store.get(oldest)!;
+      this.currentBytes -= entry.byteSize;
+      this.store.delete(oldest);
+      this.generations.delete(oldest);
+    }
+  }
 }
 
-export { RedisCacheHandler } from './redis-handler';
-export type { RedisClient } from './redis-handler';
-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 { RedisCacheHandler } from './redis-handler.ts';
+export type { RedisClient, RedisWriteOp } from './redis-handler.ts';
+export { cache } from './cache-api.ts';
+export { setCacheHandler, getCacheHandler } from './handler-store.ts';
+export { setDefaultSingleflightTimeout } from './timber-cache.ts';
+// NOTE: registerCachedFunction (runtime for 'use cache' directive) removed.
+// Future feature pending design doc. See design/06-caching.md.
+export { estimateByteSize } from './sizeof.ts';
+
+// --- Cache Store layering (design/46) ---
+export { TagAwareCacheHandler } from './tag-aware-handler.ts';
+export type { CacheStore } from './store.ts';
+// stableStringify, createSingleflight, and SingleflightTimeoutError are
+// internal utilities used by the cache implementation. They are not
+// re-exported here — import directly from the source files if needed
+// within the package. See TIM-720.

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;
+}