@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/dist/_chunks/cache-api-B-lhk9p4.js

@@ -0,0 +1,1202 @@
+import { B as addSpanEventSync, I as getWaitUntil, d as logSwrRefetchFailed, h as swallow } from "./logger-AWfuX-KJ.js";
+import { t as fnv1aHash } from "./fast-hash-D6hIVt1Y.js";
+import { t as estimateByteSize } from "./sizeof-lXffQ1Vr.js";
+import { t as warnLossyJsonValue } from "./json-lossy-check-ClNvBM_3.js";
+//#region src/cache/stable-stringify.ts
+/**
+* Deterministic JSON serialization with sorted object keys.
+* Used for cache key generation — ensures { a: 1, b: 2 } and { b: 2, a: 1 }
+* produce the same string.
+*
+* Matches JSON.stringify semantics for toJSON: Date serializes to its ISO
+* string, URL to its href, and class instances with a custom toJSON use it.
+* Map and Set serialize their entries explicitly (insertion-order
+* independent). Values that would serialize lossily — functions, symbols,
+* and non-plain objects with no enumerable own state (RegExp, class
+* instances holding data behind getters or internal slots) — throw instead:
+* every such value would collapse to the same cache key, silently returning
+* one argument's cached data for another (TIM-1020).
+*/
+function stableStringify(value) {
+	if (value === null || value === void 0) return String(value);
+	const type = typeof value;
+	if (type === "function" || type === "symbol") throw new TypeError(`stableStringify: cannot serialize a ${type} into a stable cache key — all such values would collide. Provide an explicit \`key\` option to cache().`);
+	if (type !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map((item) => stableStringify(item)).join(",") + "]";
+	const withToJSON = value;
+	if (typeof withToJSON.toJSON === "function") {
+		const json = withToJSON.toJSON();
+		if (json !== value) return stableStringify(json);
+	}
+	if (value instanceof Map) return "Map(" + [...value.entries()].map(([k, v]) => stableStringify(k) + "=>" + stableStringify(v)).sort().join(",") + ")";
+	if (value instanceof Set) return "Set(" + [...value].map((member) => stableStringify(member)).sort().join(",") + ")";
+	const obj = value;
+	const keys = Object.keys(obj).sort();
+	const pairs = [];
+	for (const key of keys) {
+		if (obj[key] === void 0) continue;
+		if (key === "toJSON" && typeof obj[key] === "function") continue;
+		pairs.push(JSON.stringify(key) + ":" + stableStringify(obj[key]));
+	}
+	if (pairs.length === 0) {
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== Object.prototype && proto !== null) {
+			const name = value.constructor?.name || "Object";
+			throw new TypeError(`stableStringify: ${name} instance has no serializable own state — all instances would share one cache key. Provide an explicit \`key\` option to cache(), or add a toJSON() method.`);
+		}
+	}
+	return "{" + pairs.join(",") + "}";
+}
+//#endregion
+//#region src/cache/singleflight.ts
+/**
+* Error thrown when a singleflight call exceeds `timeoutMs`.
+* Exported so callers can distinguish timeout from other errors.
+*/
+var SingleflightTimeoutError = class extends Error {
+	constructor(key, timeoutMs) {
+		super(`Singleflight timeout: key "${key}" exceeded ${timeoutMs}ms`);
+		this.name = "SingleflightTimeoutError";
+	}
+};
+function createSingleflight(opts) {
+	const inflight = /* @__PURE__ */ new Map();
+	const timeoutMs = opts?.timeoutMs;
+	return { do(key, fn) {
+		const existing = inflight.get(key);
+		if (existing) return existing;
+		const ac = new AbortController();
+		let promise;
+		if (timeoutMs != null && timeoutMs > 0) promise = new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				ac.abort();
+				reject(new SingleflightTimeoutError(key, timeoutMs));
+			}, timeoutMs);
+			try {
+				fn(ac.signal).then((value) => {
+					clearTimeout(timer);
+					resolve(value);
+				}, (err) => {
+					clearTimeout(timer);
+					reject(err);
+				});
+			} catch (err) {
+				clearTimeout(timer);
+				reject(err);
+			}
+		});
+		else promise = fn(ac.signal);
+		const tracked = promise.finally(() => {
+			inflight.delete(key);
+		});
+		inflight.set(key, tracked);
+		return tracked;
+	} };
+}
+//#endregion
+//#region src/cache/invalidation-epoch.ts
+/**
+* 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.
+*/
+var 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.
+*/
+var lastInvalidated = /* @__PURE__ */ new Map();
+/**
+* Bound on tracked entries so high-cardinality tag invalidation (e.g.
+* per-user tags) cannot grow this map without limit.
+*/
+var MAX_TRACKED_ENTRIES = 1e4;
+/**
+* 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.
+*/
+var evictedEpochFloor = 0;
+/** The current epoch. Capture before running fn(), pass to wasInvalidatedSince. */
+function currentInvalidationEpoch() {
+	return epoch;
+}
+/**
+* Record an invalidation. Call BEFORE handler.invalidate() so an execution
+* whose set-check races the invalidation errs toward skipping the write.
+*/
+function recordInvalidation(opts) {
+	epoch++;
+	if (opts.key) track(`key:${opts.key}`);
+	if (opts.tag) track(`tag:${opts.tag}`);
+}
+function track(entry) {
+	lastInvalidated.delete(entry);
+	lastInvalidated.set(entry, epoch);
+	while (lastInvalidated.size > MAX_TRACKED_ENTRIES) {
+		const oldest = lastInvalidated.entries().next().value;
+		if (oldest === void 0) 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).
+*/
+function wasInvalidatedSince(startEpoch, key, tags) {
+	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.
+*/
+function lastInvalidationEpochFor(key, tags) {
+	let last = evictedEpochFloor;
+	const keyEpoch = lastInvalidated.get(`key:${key}`);
+	if (keyEpoch !== void 0 && keyEpoch > last) last = keyEpoch;
+	for (const tag of tags) {
+		const tagEpoch = lastInvalidated.get(`tag:${tag}`);
+		if (tagEpoch !== void 0 && tagEpoch > last) last = tagEpoch;
+	}
+	return last;
+}
+//#endregion
+//#region src/cache/timber-cache.ts
+var 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.
+*/
+var writeGenerations = /* @__PURE__ */ new Map();
+function nextGeneration(key) {
+	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
+* cache calls without a per-call timeoutMs still get deadlock protection.
+* See design/06-caching.md §"Singleflight Timeout — Deadlock Risk".
+*/
+function setDefaultSingleflightTimeout(timeoutMs) {
+	defaultSingleflight = createSingleflight({ timeoutMs });
+}
+/**
+* Generate a cache key from function identity and serialized args.
+*
+* Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
+* need collision resistance — they need speed. The fnId prefix provides
+* namespace isolation; the hash covers the args.
+*
+* See TIM-370 for perf motivation.
+*/
+function defaultKeyGenerator(fnId, args) {
+	const raw = fnId + ":" + stableStringify(args);
+	return fnId + ":" + fnv1aHash(raw);
+}
+/**
+* Resolve tags from the options — supports static array or function form.
+*/
+function resolveTags(opts, args) {
+	if (!opts.tags) return [];
+	if (Array.isArray(opts.tags)) return opts.tags;
+	return opts.tags(...args);
+}
+/** Per-process count of byte-identical fn sources seen by deriveFallbackFnId. */
+var fallbackIdOccurrences = /* @__PURE__ */ new Map();
+var 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.
+*/
+function deriveFallbackFnId(fn) {
+	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.
+*
+* - 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.
+*
+* Cache hits/misses are recorded as OTEL span events on the enclosing
+* span (not child spans). The DevSpanProcessor reads these for dev log output.
+*/
+function createCache(fn, opts, getHandler, stableId) {
+	const fnId = stableId ?? (opts.key ? void 0 : deriveFallbackFnId(fn));
+	const perCallSf = opts.timeoutMs !== void 0 ? createSingleflight({ timeoutMs: opts.timeoutMs }) : void 0;
+	return (async (...args) => {
+		const sf = perCallSf ?? defaultSingleflight;
+		const key = opts.key ? opts.key(...args) : defaultKeyGenerator(fnId, args);
+		const cacheStart = performance.now();
+		const cached = await getHandler().get(key);
+		if (cached && !cached.stale) {
+			addSpanEventSync("timber.cache.hit", {
+				key,
+				duration_ms: Math.round(performance.now() - cacheStart)
+			});
+			return cached.value;
+		}
+		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/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), or
+		* - the handler rejects the write because a newer generation has
+		*   already been stored (TIM-1158 CAS guard).
+		*/
+		const executeAndStore = async (signal) => {
+			const startEpoch = currentInvalidationEpoch();
+			const generation = nextGeneration(key);
+			const result = await fn(...args);
+			if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) try {
+				await getHandler().set(key, result, {
+					ttl: opts.ttl,
+					tags,
+					generation
+				});
+			} catch (err) {
+				swallow(err, `cache set failed for key "${key}"`);
+			}
+			return result;
+		};
+		if (cached && cached.stale && opts.staleWhileRevalidate) {
+			addSpanEventSync("timber.cache.hit", {
+				key,
+				duration_ms: Math.round(performance.now() - cacheStart),
+				stale: true
+			});
+			const refetch = sf.do(`swr:${flightKey}`, async (signal) => {
+				try {
+					await executeAndStore(signal);
+				} catch (err) {
+					logSwrRefetchFailed({
+						cacheKey: key,
+						error: err
+					});
+				}
+			}).catch(() => {});
+			getWaitUntil()?.(refetch);
+			return cached.value;
+		}
+		const result = await sf.do(flightKey, executeAndStore);
+		addSpanEventSync("timber.cache.miss", {
+			key,
+			duration_ms: Math.round(performance.now() - cacheStart)
+		});
+		return result;
+	});
+}
+//#endregion
+//#region src/cache/handler-store.ts
+var handler$1 = null;
+var explicitlyConfigured = false;
+/** Replace the active cache handler. Called by the framework at boot. */
+function setCacheHandler(h) {
+	handler$1 = h;
+	explicitlyConfigured = true;
+}
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+function isCacheHandlerConfigured() {
+	return explicitlyConfigured;
+}
+/**
+* Get the active cache handler. Creates a default MemoryCacheHandler on
+* first access if none has been set via setCacheHandler().
+*/
+function getCacheHandler() {
+	if (!handler$1) handler$1 = createDefaultHandler();
+	return handler$1;
+}
+function createDefaultHandler() {
+	const store = /* @__PURE__ */ new Map();
+	const maxEntries = 1e3;
+	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 !== void 0) store.delete(oldest);
+				else break;
+			}
+			store.set(key, {
+				value,
+				expiresAt: Date.now() + opts.ttl * 1e3,
+				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);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/cache/redis-handler.ts
+var KEY_PREFIX = "timber:cache:";
+var TAG_PREFIX = "timber:tag:";
+/**
+* Redis-backed CacheHandler for distributed caching.
+*
+* All instances sharing the same Redis see each other's cache entries and
+* invalidations. Tag-based invalidation uses Redis Sets to track which keys
+* belong to which tags.
+*
+* Bring your own Redis client wrapped to the {@link RedisClient} contract —
+* see the adapter examples on the interface for ioredis, node-redis v4, and
+* @upstash/redis.
+*/
+var RedisCacheHandler = class {
+	client;
+	prefix;
+	constructor(client, opts) {
+		this.client = client;
+		this.prefix = opts?.prefix ?? "";
+	}
+	cacheKey(key) {
+		return `${this.prefix}${KEY_PREFIX}${key}`;
+	}
+	tagKey(tag) {
+		return `${this.prefix}${TAG_PREFIX}${tag}`;
+	}
+	async get(key) {
+		const raw = await this.client.get(this.cacheKey(key));
+		if (raw === null) return null;
+		const entry = JSON.parse(raw);
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		warnLossyJsonValue(value, key);
+		const ck = this.cacheKey(key);
+		const expiresAt = Date.now() + opts.ttl * 1e3;
+		const payload = JSON.stringify({
+			value,
+			expiresAt,
+			tags: opts.tags
+		});
+		const redisTtlSeconds = Math.max(opts.ttl * 2 + 60, 120);
+		const writeOps = [];
+		for (const tag of opts.tags) {
+			writeOps.push({
+				op: "sadd",
+				key: this.tagKey(tag),
+				members: [key]
+			});
+			writeOps.push({
+				op: "expireNX",
+				key: this.tagKey(tag),
+				seconds: redisTtlSeconds
+			});
+			writeOps.push({
+				op: "expireGT",
+				key: this.tagKey(tag),
+				seconds: redisTtlSeconds
+			});
+		}
+		writeOps.push({
+			op: "set",
+			key: ck,
+			value: payload,
+			ttlSeconds: redisTtlSeconds
+		});
+		if (this.client.execMulti) await this.client.execMulti(writeOps);
+		else for (const op of writeOps) await this.execOp(op);
+	}
+	async execOp(op) {
+		switch (op.op) {
+			case "set":
+				await this.client.set(op.key, op.value, op.ttlSeconds);
+				break;
+			case "sadd":
+				await this.client.sadd(op.key, ...op.members);
+				break;
+			case "expireNX":
+				await this.client.expireNX(op.key, op.seconds);
+				break;
+			case "expireGT":
+				await this.client.expireGT(op.key, op.seconds);
+				break;
+			case "del":
+				await this.client.del(op.key);
+				break;
+		}
+	}
+	async invalidate(opts) {
+		if (opts.key) {
+			const raw = await this.client.get(this.cacheKey(opts.key));
+			if (raw !== null) {
+				const entry = JSON.parse(raw);
+				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));
+		}
+		if (opts.tag) {
+			const tk = this.tagKey(opts.tag);
+			const keys = await this.client.smembers(tk);
+			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;
+				}
+				if (JSON.parse(raw).tags?.includes(opts.tag)) await this.client.del(this.cacheKey(k));
+				await this.client.srem(tk, k);
+			}));
+			if ((await this.client.smembers(tk)).length === 0) await this.client.del(tk);
+		}
+	}
+};
+//#endregion
+//#region src/cache/tag-aware-handler.ts
+var DATA_PREFIX = "d:";
+var TAG_SET_PREFIX = "ts:";
+var TAG_VERSION_PREFIX = "tv:";
+function detectStrategy(store) {
+	if (store.setWithTags && store.invalidateTag) return "native";
+	if (store.sadd && store.smembers && store.srem && store.sdel) return "eager";
+	return "lazy";
+}
+var TagAwareCacheHandler = class {
+	store;
+	prefix;
+	strategy;
+	constructor(store, opts) {
+		this.store = store;
+		this.prefix = opts?.prefix ?? "timber:";
+		this.strategy = detectStrategy(store);
+	}
+	get consistency() {
+		return this.store.consistency;
+	}
+	dataKey(key) {
+		return `${this.prefix}${DATA_PREFIX}${key}`;
+	}
+	/** Namespace tags for native stores so prefix isolates shared stores. */
+	prefixTags(tags) {
+		return tags.map((t) => `${this.prefix}${t}`);
+	}
+	tagSetKey(tag) {
+		return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
+	}
+	tagVersionKey(tag) {
+		return `${this.prefix}${TAG_VERSION_PREFIX}${tag}`;
+	}
+	async get(key) {
+		const raw = await this.store.get(this.dataKey(key));
+		if (raw === null) return null;
+		if (this.strategy === "native" || this.strategy === "eager") {
+			const entry = JSON.parse(raw);
+			const stale = Date.now() > entry.expiresAt;
+			return {
+				value: entry.value,
+				stale
+			};
+		}
+		const entry = JSON.parse(raw);
+		if (entry.tags.length > 0) {
+			const currentVersions = await this.getTagVersions(entry.tags);
+			for (const tag of entry.tags) {
+				const stored = entry.tagVersions[tag] ?? 0;
+				if ((currentVersions[tag] ?? 0) > stored) return null;
+			}
+		}
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
+		if (this.strategy === "native") {
+			const entry = {
+				value,
+				expiresAt: Date.now() + opts.ttl * 1e3,
+				tags: opts.tags
+			};
+			const payload = JSON.stringify(entry);
+			if (opts.tags.length > 0) await this.store.setWithTags(this.dataKey(key), payload, physicalTtl, this.prefixTags(opts.tags));
+			else await this.store.set(this.dataKey(key), payload, physicalTtl);
+			return;
+		}
+		if (this.strategy === "eager") {
+			const entry = {
+				value,
+				expiresAt: Date.now() + opts.ttl * 1e3,
+				tags: opts.tags
+			};
+			await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+			if (opts.tags.length > 0) await Promise.all(opts.tags.map((tag) => this.store.sadd(this.tagSetKey(tag), [key], physicalTtl)));
+			return;
+		}
+		const tagVersions = opts.tags.length > 0 ? await this.getTagVersions(opts.tags) : {};
+		const entry = {
+			value,
+			expiresAt: Date.now() + opts.ttl * 1e3,
+			tags: opts.tags,
+			tagVersions
+		};
+		await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+	}
+	async invalidate(opts) {
+		if (opts.key) {
+			if (this.strategy === "eager") {
+				const raw = await this.store.get(this.dataKey(opts.key));
+				if (raw !== null) {
+					const entry = JSON.parse(raw);
+					if (entry.tags.length > 0) await Promise.all(entry.tags.map((tag) => this.store.srem(this.tagSetKey(tag), [opts.key])));
+				}
+			}
+			await this.store.del(this.dataKey(opts.key));
+		}
+		if (opts.tag) {
+			const tag = opts.tag;
+			if (this.strategy === "native") await this.store.invalidateTag(`${this.prefix}${tag}`);
+			else if (this.strategy === "eager") {
+				const members = await this.store.smembers(this.tagSetKey(tag));
+				await Promise.all(members.map(async (k) => {
+					const raw = await this.store.get(this.dataKey(k));
+					if (raw === null) {
+						await this.store.srem(this.tagSetKey(tag), [k]);
+						return;
+					}
+					if (JSON.parse(raw).tags.includes(tag)) {
+						await this.store.del(this.dataKey(k));
+						await this.store.srem(this.tagSetKey(tag), [k]);
+					} else await this.store.srem(this.tagSetKey(tag), [k]);
+				}));
+			} else await this.bumpTagVersion(opts.tag);
+		}
+	}
+	async getTagVersions(tags) {
+		const versions = {};
+		await Promise.all(tags.map(async (tag) => {
+			const raw = await this.store.get(this.tagVersionKey(tag));
+			versions[tag] = raw !== null ? parseInt(raw, 10) : 0;
+		}));
+		return versions;
+	}
+	async bumpTagVersion(tag) {
+		const key = this.tagVersionKey(tag);
+		const raw = await this.store.get(key);
+		const version = Math.max(raw !== null ? parseInt(raw, 10) : 0, Date.now()) + 1;
+		await this.store.set(key, String(version), 365 * 86400);
+	}
+};
+//#endregion
+//#region src/cache/index.ts
+var MemoryCacheHandler = class {
+	store = /* @__PURE__ */ new Map();
+	generations = /* @__PURE__ */ new Map();
+	maxEntries;
+	maxBytes;
+	maxEntryBytes;
+	currentBytes = 0;
+	_trackBytes;
+	constructor(opts) {
+		this.maxEntries = opts?.maxEntries ?? opts?.maxSize ?? 1e3;
+		this.maxBytes = opts?.maxBytes;
+		this.maxEntryBytes = opts?.maxEntryBytes;
+		this._trackBytes = this.maxBytes !== void 0 || this.maxEntryBytes !== void 0;
+	}
+	async get(key) {
+		const entry = this.store.get(key);
+		if (!entry) return null;
+		this.store.delete(key);
+		this.store.set(key, entry);
+		const stale = Date.now() > entry.expiresAt;
+		return {
+			value: entry.value,
+			stale
+		};
+	}
+	async set(key, value, opts) {
+		if (opts.generation !== void 0) {
+			const current = this.generations.get(key) ?? 0;
+			if (opts.generation < current) return;
+		}
+		const byteSize = this._trackBytes ? estimateByteSize(value) : 0;
+		if (this.maxEntryBytes !== void 0 && byteSize > this.maxEntryBytes) return;
+		if (this.store.has(key)) {
+			const existing = this.store.get(key);
+			this.currentBytes -= existing.byteSize;
+			this.store.delete(key);
+		}
+		while (this.store.size >= this.maxEntries) this.evictOldest();
+		if (this.maxBytes !== void 0) {
+			while (this.currentBytes + byteSize > this.maxBytes && this.store.size > 0) this.evictOldest();
+			if (this.currentBytes + byteSize > this.maxBytes) return;
+		}
+		if (opts.generation !== void 0) this.generations.set(key, opts.generation);
+		this.store.set(key, {
+			value,
+			expiresAt: Date.now() + opts.ttl * 1e3,
+			tags: opts.tags,
+			byteSize
+		});
+		this.currentBytes += byteSize;
+	}
+	async invalidate(opts) {
+		if (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);
+			}
+		}
+	}
+	/** Number of entries currently in the cache. */
+	get size() {
+		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() {
+		return this.currentBytes;
+	}
+	/** Evict the oldest entry (front of Map). */
+	evictOldest() {
+		const oldest = this.store.keys().next().value;
+		if (oldest !== void 0) {
+			const entry = this.store.get(oldest);
+			this.currentBytes -= entry.byteSize;
+			this.store.delete(oldest);
+			this.generations.delete(oldest);
+		}
+	}
+};
+//#endregion
+//#region src/server/version-skew.ts
+/**
+* Version Skew Detection — graceful recovery when stale clients hit new deployments.
+*
+* When a new version of the app is deployed, clients with open tabs still have
+* the old JavaScript bundle. Without version skew handling, these stale clients
+* will experience:
+*
+* 1. Server action calls that crash (action IDs are content-hashed)
+* 2. Chunk load failures (old filenames gone from CDN)
+* 3. RSC payload mismatches (component references differ between builds)
+*
+* This module implements deployment ID comparison:
+* - A per-build deployment ID is generated at build time (see build-manifest.ts)
+* - The client sends it via `X-Timber-Deployment-Id` header on every RSC/action request
+* - The server compares it against the current build's ID
+* - On mismatch: signal the client to reload (not crash)
+*
+* The deployment ID is always-on in production. Dev mode skips the check
+* (HMR handles code updates without full reloads).
+*
+* See design/25-production-deployments.md, TIM-446
+*/
+/** Header sent by the client with every RSC/action request. */
+var DEPLOYMENT_ID_HEADER = "X-Timber-Deployment-Id";
+/** Response header that signals the client to do a full page reload. */
+var RELOAD_HEADER = "X-Timber-Reload";
+/**
+* The current build's deployment ID. Set at startup from the manifest init
+* module (globalThis.__TIMBER_DEPLOYMENT_ID__). Null in dev mode.
+*/
+var currentDeploymentId = null;
+/**
+* Get the current deployment ID. Returns null in dev mode.
+*/
+function getDeploymentId() {
+	return currentDeploymentId;
+}
+/**
+* Check if a request's deployment ID matches the current build.
+*
+* Returns `{ ok: true }` when:
+* - Dev mode (no deployment ID set — HMR handles updates)
+* - No deployment ID header (initial page load, non-RSC request)
+* - Deployment IDs match
+*
+* Returns `{ ok: false }` when:
+* - Client sends a deployment ID that differs from the current build
+*/
+function checkVersionSkew(req) {
+	if (!currentDeploymentId) return {
+		ok: true,
+		clientId: null
+	};
+	const clientId = req.headers.get(DEPLOYMENT_ID_HEADER);
+	if (!clientId) return {
+		ok: true,
+		clientId: null
+	};
+	if (clientId === currentDeploymentId) return {
+		ok: true,
+		clientId
+	};
+	return {
+		ok: false,
+		clientId
+	};
+}
+/**
+* Apply version skew reload headers to a response.
+* Sets X-Timber-Reload: 1 to signal the client to do a full page reload.
+*/
+function applyReloadHeaders(headers) {
+	headers.set(RELOAD_HEADER, "1");
+}
+//#endregion
+//#region src/server/prebuilt/manifest-tag-index.ts
+/**
+* Build the inverted tag → seed key index from the manifest.
+*
+* Returns a Map where each tag maps to the set of (componentId, cacheKey)
+* pairs whose manifest entries carry that tag. Only entries with non-empty
+* `tags` arrays participate.
+*/
+function buildTagIndex(manifest) {
+	const index = /* @__PURE__ */ new Map();
+	for (const [componentId, component] of Object.entries(manifest)) {
+		if (!component || typeof component !== "object" || !("entries" in component)) continue;
+		for (const [cacheKey, entry] of Object.entries(component.entries)) {
+			if (!entry.tags || entry.tags.length === 0) continue;
+			for (const tag of entry.tags) {
+				let list = index.get(tag);
+				if (!list) {
+					list = [];
+					index.set(tag, list);
+				}
+				list.push({
+					componentId,
+					cacheKey
+				});
+			}
+		}
+	}
+	return index;
+}
+//#endregion
+//#region src/server/prebuilt/payload-source.ts
+/**
+* Prebuilt payload source — the adapter seam through which the runtime
+* reads build-time flight artifacts (`.timber/dist/prebuilt/`).
+*
+* The runtime never touches the filesystem directly: adapters register a
+* source at startup (Node: fs reads; Cloudflare: the assets binding —
+* design/44-render-at-build-time.md §Adapter Integration). Artifacts are
+* produced by the post-build capture pass (TIM-1119, prebuilt-builder.ts);
+* adapter registration of the source is TIM-1122. Until a source is
+* registered (adapter not wired yet, dev mode, no artifacts built), every
+* lookup misses and cache.component wrappers render live — the designed
+* dynamic-fallback behavior.
+*
+* Phase 3 (design/45 runtime tier) inserts the CacheHandler overlay lookup
+* in front of `lookupPrebuiltPayload` — overlay first, then artifact. The
+* single-lookup-function shape here is that seam.
+*/
+var source = null;
+var manifestPromise = null;
+/**
+* Ceiling on the memoized manifest load. Without it, a stalled
+* `loadManifest()` would leave `manifestPromise` pending forever and every
+* subsequent cache.component render would await the same hung promise —
+* the coalesced-promise deadlock class from design/13-security.md (A5).
+* On expiry the load memoizes as null (permanent dynamic fallback, same
+* policy as a failed load) and callers proceed immediately.
+*/
+var MANIFEST_LOAD_TIMEOUT_MS = 5e3;
+/**
+* Per-read ceiling on payload reads. The read is awaited inside a server
+* component render — a stalled adapter promise would otherwise hang the
+* RSC stream until the render timeout kills the whole page, when the
+* correct degradation is a miss → live render (codex review round 4 on
+* PR #835).
+*/
+var PAYLOAD_READ_TIMEOUT_MS = 5e3;
+/** Race a source promise against a timeout that resolves to `fallback`. */
+async function withTimeout(work, timeoutMs, fallback, onTimeout) {
+	let timer;
+	try {
+		return await Promise.race([work, new Promise((resolve) => {
+			timer = setTimeout(() => {
+				onTimeout();
+				resolve(fallback);
+			}, timeoutMs);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function loadManifestWithTimeout(src) {
+	let manifest;
+	try {
+		manifest = await withTimeout(src.loadManifest(), MANIFEST_LOAD_TIMEOUT_MS, null, () => {
+			console.error(`[timber] prebuilt manifest load exceeded ${MANIFEST_LOAD_TIMEOUT_MS}ms — all cache.component lookups will render dynamically`);
+		});
+	} catch (error) {
+		console.error("[timber] failed to load prebuilt manifest — all cache.component lookups will miss:", error);
+		return null;
+	}
+	if (manifest) initTagIndex(manifest);
+	return manifest;
+}
+/**
+* Register the payload source. Called once at server startup by the
+* adapter/entry wiring (TIM-1122); tests inject fakes. Passing null
+* unregisters (and drops the memoized manifest).
+*/
+function setPrebuiltPayloadSource(next) {
+	source = next;
+	manifestPromise = null;
+	if (!next) resetTagIndex();
+}
+/**
+* Whether a source is registered — the gate for both marker emission and
+* splice-transform installation. False means zero prebuilt overhead.
+*/
+function hasPrebuiltPayloadSource() {
+	return source !== null;
+}
+/**
+* Ensure the manifest is loaded (and the tag index initialized). No-op
+* when no source is registered. Used by the tombstone path to avoid
+* skipping tombstones on cold processes where the first request is an
+* action rather than a page render.
+*/
+async function ensureManifestLoaded() {
+	if (source === null) return;
+	manifestPromise ??= loadManifestWithTimeout(source);
+	await manifestPromise;
+}
+/**
+* Look up a manifest entry (metadata only, no payload read).
+* Used by the overlay to check seed existence and freshness.
+*/
+async function isParamIndependent(componentId) {
+	if (source === null) return false;
+	manifestPromise ??= loadManifestWithTimeout(source);
+	return (await manifestPromise)?.[componentId]?.paramIndependent === true;
+}
+async function getManifestEntry(componentId, cacheKey) {
+	if (source === null) return null;
+	manifestPromise ??= loadManifestWithTimeout(source);
+	return (await manifestPromise)?.[componentId]?.entries?.[cacheKey] ?? null;
+}
+/**
+* Look up a cached payload: manifest entry → payload bytes.
+* Null on any miss or read failure — callers fall back to live render.
+*
+* The manifest is loaded once and memoized (design/44 §manifest.json:
+* loaded at startup, held in memory; payloads read on demand). A failed
+* manifest load is memoized as null rather than retried per-request — a
+* broken artifact should degrade to dynamic rendering, not add a failing
+* read to every request.
+*/
+async function lookupPrebuiltPayload(componentId, cacheKey) {
+	if (source === null) return null;
+	manifestPromise ??= loadManifestWithTimeout(source);
+	const entry = (await manifestPromise)?.[componentId]?.entries?.[cacheKey];
+	if (!entry) return null;
+	try {
+		return await withTimeout(source.readPayload(entry.file), PAYLOAD_READ_TIMEOUT_MS, null, () => {
+			console.error(`[timber] prebuilt payload read for "${entry.file}" exceeded ${PAYLOAD_READ_TIMEOUT_MS}ms — rendering dynamically`);
+		});
+	} catch (error) {
+		console.error(`[timber] failed to read prebuilt payload "${entry.file}" for ${componentId} — rendering dynamically:`, error);
+		return null;
+	}
+}
+//#endregion
+//#region src/server/prebuilt/overlay.ts
+/**
+* Component cache overlay — runtime CacheHandler layer for ISR.
+*
+* Sits in front of the immutable build artifact (`.flight` files) and
+* stores replacement payloads and tombstones via the configured
+* CacheHandler. Overlay entries are per-deploy namespaced:
+*   `timber:c:{deploymentId}:{componentId}:{hash}`
+*
+* The CacheHandler contract is untouched — tombstones and the tag index
+* live above the interface as value conventions. Redis, KV, and custom
+* handlers work unmodified.
+*
+* See design/45-cache-lifetimes.md §ISR mechanics.
+*/
+/** Default ceiling TTL for tag-only entries (24 hours), in seconds. */
+var CEILING_TTL_SECONDS = 1440 * 60;
+/** Deploy-long physical TTL for seed-backed overlay records (90 days). */
+var DEPLOY_LONG_TTL_SECONDS = 2160 * 60 * 60;
+function isOverlayRecord(v) {
+	return v !== null && typeof v === "object" && v._t === "co";
+}
+function isTombstone(v) {
+	return v !== null && typeof v === "object" && v._t === "ct";
+}
+function overlayKey(componentId, cacheKey) {
+	return `timber:c:${getDeploymentId() ?? "dev"}:${componentId}:${cacheKey}`;
+}
+/**
+* Look up an overlay entry in the cache handler.
+* Returns null on a clean miss (no overlay entry at all).
+*/
+async function lookupOverlay(componentId, cacheKey) {
+	const handler = getCacheHandler();
+	const key = overlayKey(componentId, cacheKey);
+	const result = await handler.get(key);
+	if (!result) return null;
+	const value = result.value;
+	if (isTombstone(value)) return {
+		kind: "tombstone",
+		record: null,
+		payload: null
+	};
+	if (isOverlayRecord(value)) return {
+		kind: Date.now() > value.fu ? "stale" : "fresh",
+		record: value,
+		payload: base64ToBytes(value.p)
+	};
+	return null;
+}
+/**
+* Resolve the effective TTL for a component's runtime lifetime.
+* Tag-only entries (no explicit ttl) get the ceiling TTL (design/45
+* §Tag-only entries carry a ceiling TTL).
+*/
+function effectiveTtl(ttl) {
+	return ttl ?? CEILING_TTL_SECONDS;
+}
+/**
+* Store a component flight payload in the overlay.
+*/
+async function storeOverlayEntry(componentId, cacheKey, payloadBytes, opts) {
+	const handler = getCacheHandler();
+	const key = overlayKey(componentId, cacheKey);
+	const logicalTtl = effectiveTtl(opts.ttl);
+	const physicalTtl = opts.hasSeed ? DEPLOY_LONG_TTL_SECONDS : logicalTtl;
+	const record = {
+		_t: "co",
+		p: bytesToBase64(payloadBytes),
+		fu: Date.now() + logicalTtl * 1e3,
+		s: opts.hasSeed
+	};
+	await handler.set(key, record, {
+		ttl: physicalTtl,
+		tags: opts.tags
+	});
+}
+var tagIndex = null;
+/**
+* Initialize the tag index from the prebuilt manifest. Called once when the
+* manifest is loaded. Without a manifest (no prebuilt components), this is
+* never called and revalidateTag skips the tombstone path entirely.
+*/
+function initTagIndex(manifest) {
+	tagIndex = buildTagIndex(manifest);
+	emitIsrDiagnosticIfNeeded(manifest);
+}
+/**
+* Reset the tag index (for tests).
+* @internal
+*/
+function resetTagIndex() {
+	tagIndex = null;
+}
+/**
+* Write tombstones for all seed entries carrying the given tag.
+* Called from cache.invalidate (cache-api.ts) AFTER the handler's own
+* invalidation clears overlay entries.
+*
+* The tombstone prevents the immutable seed from being served after
+* invalidation — without it, a handler.invalidate that clears the overlay
+* would expose the (now-stale) build artifact on the next request.
+*
+* Ensures the manifest is loaded first so cold-process actions that
+* invalidate before any page render still write tombstones.
+*/
+async function writeTombstonesForTag(tag) {
+	if (!tagIndex) await ensureManifestLoaded();
+	if (!tagIndex) return;
+	const seeds = tagIndex.get(tag);
+	if (!seeds || seeds.length === 0) return;
+	const handler = getCacheHandler();
+	const tombstone = { _t: "ct" };
+	await Promise.all(seeds.map((seed) => {
+		const key = overlayKey(seed.componentId, seed.cacheKey);
+		return handler.set(key, tombstone, {
+			ttl: DEPLOY_LONG_TTL_SECONDS,
+			tags: [tag]
+		});
+	}));
+}
+var isrDiagnosticEmitted = false;
+function emitIsrDiagnosticIfNeeded(manifest) {
+	if (isrDiagnosticEmitted) return;
+	if (!(getCacheHandler() instanceof MemoryCacheHandler || !isCacheHandlerConfigured())) return;
+	for (const [, component] of Object.entries(manifest)) {
+		if (!component || typeof component !== "object" || !("entries" in component)) continue;
+		for (const [, entry] of Object.entries(component.entries)) if (entry.tags && entry.tags.length > 0) {
+			isrDiagnosticEmitted = true;
+			console.warn("[timber] tag revalidation of prerendered components requires a shared cache handler in multi-instance deployments. The current MemoryCacheHandler is per-process — revalidateTag on one instance will not purge the build seed on others. Configure a shared handler (Redis, KV) for production ISR.");
+			return;
+		}
+	}
+}
+function bytesToBase64(bytes) {
+	return Buffer.from(bytes).toString("base64");
+}
+function base64ToBytes(b64) {
+	return new Uint8Array(Buffer.from(b64, "base64"));
+}
+//#endregion
+//#region src/cdn/purge-store.ts
+var handler;
+/** Get the current CDN purge handler, if configured. */
+function getCdnPurgeHandler() {
+	return handler;
+}
+//#endregion
+//#region src/cache/cache-api.ts
+var componentFallbackWarned = /* @__PURE__ */ new WeakSet();
+/**
+* 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}`] }
+* );
+* ```
+*/
+var 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).
+	*/
+	data(fn, opts, stableId) {
+		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) {
+		recordInvalidation(opts);
+		await getCacheHandler().invalidate(opts);
+		if (opts.tag) await writeTombstonesForTag(opts.tag);
+		if (opts.tag) {
+			const purgeHandler = getCdnPurgeHandler();
+			if (purgeHandler) try {
+				await Promise.race([purgeHandler.purgeTags([opts.tag]), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("CDN purge timed out (10s)")), 1e4))]);
+			} 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.
+	*/
+	component(componentFn, _options) {
+		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;
+	}
+};
+//#endregion
+export { setDefaultSingleflightTimeout as _, getManifestEntry as a, wasInvalidatedSince as b, lookupPrebuiltPayload as c, checkVersionSkew as d, MemoryCacheHandler as f, setCacheHandler as g, getCacheHandler as h, storeOverlayEntry as i, setPrebuiltPayloadSource as l, RedisCacheHandler as m, lookupOverlay as n, hasPrebuiltPayloadSource as o, TagAwareCacheHandler as p, overlayKey as r, isParamIndependent as s, cache as t, applyReloadHeaders as u, currentInvalidationEpoch as v, createSingleflight as x, lastInvalidationEpochFor as y };
+
+//# sourceMappingURL=cache-api-B-lhk9p4.js.map