@ultimat3/cache 27.6.1 → 27.7.0

package/CLAUDE.md

@@ -42,6 +42,9 @@ Tier 1. Tagged caching + THE invalidation graph.
   `TIER_ORDER` alias (`X_HELPER_COPY` refuses a value of core's under a second name). Adding a
   rung is an edit to `packages/core/src/cache-vocabulary.ts` plus a factory here; `scripts/render-modes.ts` refuses a second declaration of the set. **`isr` is
   not a tier** — the `'isr'` in `invalidate.ts` is an ISR route (`DependentKind = 'isr-route'`).
+- **`flushProcessTiers(source)` is for a process that cannot name what it missed** (its bus was
+  away): `CacheTier.clear()` on in-process tiers only, tagged ISR pages stale, fills fenced out
+  (`markAllInvalidated`). Never re-emits. A shared tier must NOT implement `clear`.
 - **`bestEffort()` is the only sanctioned way to swallow a cache refusal.** Its label is `TierLabel`
   (`TierName` plus `'query-read'`), deliberately not a widening of `TierName`.
 - **A refusal is rendered with `renderThrowable()`, never `error.message`** — at all five absorbing

package/README.md

@@ -304,8 +304,17 @@ bus.subscribe('cache.invalidate', (wireTags) => receiveInvalidationBroadcast(wir
 The inbound half **cannot** re-emit, and that is structural rather than a flag: `emit` lives on the
 private fan-out options and `receiveInvalidationBroadcast` is the only caller that passes `false`.
 A receiver that re-broadcast would be a storm bounded by nothing. A failed send lands in
-`report.errors` under `tier: "broadcast"` — the other pods then clear on TTL, and the write that
-triggered the bust still succeeds. An inbound tag this process has not declared is dropped and
+`report.errors` under `tier: "broadcast"` and the write that triggered the bust still succeeds.
+What happens to that bust is the sender's (`@ultimat3/cli` keeps the refused tags, bounded, and
+publishes them when the bus returns); with no such sender the other pods clear on TTL.
+
+**`flushProcessTiers(source)` is the repair for a process that cannot know what it missed** — its
+bus connection was down for a window, or a peer says it had more refused busts than it could keep.
+It calls `CacheTier.clear()` on every tier that has one (only a tier whose store is this process's
+heap implements it: `lruTier` does, `redisTier` and `cdnTier` do not), marks every ISR page that
+depends on a tag stale through the registered revalidator, and fences out every fill in flight
+(`markAllInvalidated`). It never re-emits and never throws; its report and its `/_x` event carry
+`tags: ['*']` (`FLUSH_ALL_TAG`). An inbound tag this process has not declared is dropped and
 reported rather than thrown, because mid-deploy the new pods know an entity the old ones do not and
 a throw would kill the subscriber loop that delivered it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "27.6.1",
+  "version": "27.7.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.6.1"
+    "@ultimat3/core": "27.7.0"
   }
 }

package/src/fence.ts

@@ -70,6 +70,17 @@ export function markInvalidated(scope: FenceScope): void {
   }
 }
 
+/**
+ * Everything, invalidated: every fence sampled before this call answers `false`. For a process
+ * that cannot name what it missed (`flushProcessTiers`) — the same "older than the ring remembers:
+ * unprovable, so refused" rule, reached on purpose. One refetch per in-flight fill.
+ */
+export function markAllInvalidated(): void {
+  generation += 1;
+  forgottenThrough = generation;
+  marks.length = 0;
+}
+
 function hits(mark: Mark, scope: FenceScope): boolean {
   if (mark.key !== undefined) return scope.key !== undefined && mark.key === scope.key;
   const owned = mark.tag;

package/src/index.ts

@@ -41,6 +41,8 @@ export type {
   Revalidator,
 } from './invalidate';
 export {
+  FLUSH_ALL_TAG,
+  flushProcessTiers,
   invalidateTags,
   invalidateWireTags,
   isolateTiers,

package/src/invalidate.ts

@@ -12,8 +12,8 @@ import {
   systemClock,
   withSpan,
 } from '@ultimat3/core';
-import { markInvalidated } from './fence';
-import { dependentsOfKind } from './graph';
+import { markAllInvalidated, markInvalidated } from './fence';
+import { dependentsOfKind, graphSnapshot } from './graph';
 import type { CacheTag } from './tags';
 import { assertKnownTags, knownTags, parseTag, serializeTags } from './tags';
 import { isolateTierFailures, resetTierFailures } from './tier-failures';
@@ -292,6 +292,70 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva
   });
 }
 
+/** What a flush reports and records as its tags: not a wire tag, and never parsed as one. */
+export const FLUSH_ALL_TAG = '*';
+
+/**
+ * Drop everything this PROCESS holds, because it cannot know what it missed.
+ *
+ * A peer's bust reaches this process by the broadcast and by nothing else: its in-process tier and
+ * its tag-revalidated ISR pages are cleared by `receiveInvalidationBroadcast`, or they wait for
+ * their TTL — and a `revalidate: { tags }` page has none. So a process whose bus connection was
+ * down for a window, or a sender that had more refused busts than it could keep, has one correct
+ * answer left. Every in-process tier is cleared (`CacheTier.clear`), every ISR page that depends
+ * on a tag is marked stale, and every fill in flight is fenced out. Shared tiers and the CDN are
+ * untouched — the bust's sender cleared those — and nothing is re-emitted: this is local repair.
+ * Never throws; the cost is one cold cache.
+ */
+export function flushProcessTiers(source: string): Promise<InvalidationReport> {
+  return withSpan('cache.flush', async (): Promise<InvalidationReport> => {
+    const startedAt = performance.now();
+    markAllInvalidated();
+    const tiers: TierInvalidation[] = [];
+    const errors: { tier: string; message: string }[] = [];
+    for (const tier of sortTiers(registry)) {
+      if (tier.clear === undefined) continue;
+      try {
+        await tier.clear();
+        tiers.push({ tier: tier.name, keys: [] });
+      } catch (error) {
+        errors.push({ tier: tier.name, message: renderThrowable(error) });
+      }
+    }
+    const isr = dedupe(
+      graphSnapshot().flatMap((entry) =>
+        entry.dependents.filter((dep) => dep.kind === 'isr-route').map((dep) => dep.id),
+      ),
+    );
+    for (const path of isr) {
+      try {
+        await revalidator?.(path);
+      } catch (error) {
+        errors.push({ tier: 'isr', message: renderThrowable(error) });
+      }
+    }
+    const report: InvalidationReport = {
+      tags: [FLUSH_ALL_TAG],
+      tiers,
+      isr,
+      cdn: [],
+      liveQueries: [],
+      durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+      errors,
+    };
+    recordInvalidation({
+      at: systemClock.now().toISOString(),
+      tags: report.tags,
+      busted: [...isr],
+      source,
+      durationMs: report.durationMs,
+      errors,
+    });
+    if (errors.length > 0) logger.warn('cache.flush.partial', { ...report });
+    return report;
+  });
+}
+
 /** First-seen order kept — a union of what actually changed, not a sorted report. */
 function dedupe(values: readonly string[]): readonly string[] {
   return [...new Set(values)];

package/src/lru.ts

@@ -305,5 +305,8 @@ export function lruTier(options: LruOptions = {}): CacheTier & { readonly cache:
     invalidateTags(tags: readonly CacheTag[]): Promise<TierInvalidation> {
       return Promise.resolve({ tier: 'lru', keys: cache.invalidateTags(tags) });
     },
+    clear(): void {
+      cache.clear();
+    },
   };
 }

package/src/tiers.ts

@@ -195,6 +195,12 @@ export interface CacheTier {
    * may never be told about — still stops the fill (`tier-fence.ts`). Omitted by in-process tiers.
    */
   fence?(scope: FenceScope): Promise<TierFence>;
+  /**
+   * Drop every entry — implemented ONLY by a tier whose store is this process's own heap (`lru`).
+   * `flushProcessTiers()` calls it when the process cannot know which busts it missed. A shared
+   * tier omits it: whoever ran a bust cleared that store for everyone.
+   */
+  clear?(): Promise<void> | void;
 }
 
 export interface CacheStack {