@trieb.work/nextjs-turbo-redis-cache 1.17.0 → 1.18.0

package/test/vitest/unit/cache-components-update-tags.test.ts

@@ -0,0 +1,350 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const hoisted = vi.hoisted(() => {
+  const store = new Map<string, string>();
+  const unlinkedKeys: string[] = [];
+  return { store, unlinkedKeys };
+});
+
+vi.mock('redis', () => {
+  const createClient = () => {
+    const client = {
+      isReady: true,
+      isOpen: true,
+      on: vi.fn(),
+      connect: vi.fn(async () => undefined),
+      disconnect: vi.fn(),
+      quit: vi.fn(),
+      duplicate: vi.fn(() => ({
+        connect: vi.fn(async () => undefined),
+        subscribe: vi.fn(async () => undefined),
+        on: vi.fn(),
+        quit: vi.fn(async () => undefined),
+        configGet: vi.fn(async () => ({ 'notify-keyspace-events': 'Exe' })),
+        isOpen: true,
+        isReady: true,
+      })),
+      get: vi.fn(
+        async (_opts: unknown, key: string) => hoisted.store.get(key) ?? null,
+      ),
+      hScan: vi.fn(async () => ({ cursor: 0, tuples: [] })),
+      scan: vi.fn(async () => ({ cursor: 0, keys: [] })),
+      hSet: vi.fn(async () => 1),
+      hDel: vi.fn(async () => 1),
+      publish: vi.fn(async () => 1),
+      unlink: vi.fn(async (keys: string | string[]) => {
+        const list = Array.isArray(keys) ? keys : [keys];
+        for (const key of list) {
+          hoisted.unlinkedKeys.push(key);
+          hoisted.store.delete(key);
+        }
+        return list.length;
+      }),
+      eval: vi.fn(
+        async (
+          _script: string,
+          options: { keys: string[]; arguments: string[] },
+        ) => {
+          const key = options.keys[0];
+          const expected = options.arguments[0];
+          if (hoisted.store.get(key) === expected) {
+            hoisted.unlinkedKeys.push(key);
+            hoisted.store.delete(key);
+            return 1;
+          }
+          return 0;
+        },
+      ),
+      set: vi.fn(async (key: string, value: string) => {
+        hoisted.store.set(key, value);
+        return 'OK';
+      }),
+    };
+    return client;
+  };
+
+  return {
+    createClient,
+    commandOptions: vi.fn((opts) => opts),
+  };
+});
+
+function cachedEntry(tags: string[], timestamp: number) {
+  return {
+    value: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode('cached'));
+        controller.close();
+      },
+    }),
+    tags,
+    stale: 1,
+    timestamp,
+    expire: 3600,
+    revalidate: 60,
+  };
+}
+
+describe('RedisCacheComponentsHandler.updateTags vs Next.js default handler', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    hoisted.store.clear();
+    hoisted.unlinkedKeys.length = 0;
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  async function createHandler(keyPrefix: string) {
+    const { getRedisCacheComponentsHandler } = await import(
+      '../../../src/CacheComponentsHandler'
+    );
+
+    return getRedisCacheComponentsHandler({
+      keyPrefix,
+      redisGetDeduplication: false,
+    });
+  }
+
+  it('SWR expire keeps the entry and sets revalidate=-1 until the window elapses', async () => {
+    const handler = await createHandler('swr:');
+    const createdAt = Date.now();
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    // Next.js areTagsStale/areTagsExpired require stale/expired > entry.timestamp.
+    await vi.advanceTimersByTimeAsync(1);
+    const revalidatedAt = Date.now();
+    await handler.updateTags(['posts'], { expire: 2 });
+
+    expect(await handler.getExpiration(['posts'])).toBe(revalidatedAt + 2_000);
+
+    const served = await handler.get('page', []);
+    expect(served).toBeDefined();
+    expect(served?.revalidate).toBe(-1);
+    expect(hoisted.unlinkedKeys).toEqual([]);
+
+    await vi.advanceTimersByTimeAsync(2_000);
+    expect(await handler.get('page', [])).toBeUndefined();
+  });
+
+  it('cacheLife max expire (~1y) is SWR, not a delay before staleness', async () => {
+    const handler = await createHandler('max:');
+    const createdAt = Date.now();
+    const oneYear = 60 * 60 * 24 * 365;
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    await vi.advanceTimersByTimeAsync(1);
+    const revalidatedAt = Date.now();
+    await handler.updateTags(['posts'], { expire: oneYear });
+
+    expect(await handler.getExpiration(['posts'])).toBe(
+      revalidatedAt + oneYear * 1000,
+    );
+    const served = await handler.get('page', []);
+    expect(served?.revalidate).toBe(-1);
+    expect(await handler.get('page', [])).toBeDefined();
+  });
+
+  it('omitted durations is a blocking miss (updateTag / deprecated revalidateTag)', async () => {
+    const handler = await createHandler('hard:');
+    const createdAt = Date.now();
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    await vi.advanceTimersByTimeAsync(1);
+    const revalidatedAt = Date.now();
+    await handler.updateTags(['posts']);
+
+    expect(await handler.getExpiration(['posts'])).toBe(revalidatedAt);
+    expect((handler as any).revalidatedTagsMap.get('posts')).toBe(
+      revalidatedAt,
+    );
+    expect(await handler.get('page', [])).toBeUndefined();
+  });
+
+  it('{ expire: 0 } is a blocking miss', async () => {
+    const handler = await createHandler('zero:');
+    const createdAt = Date.now();
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    await vi.advanceTimersByTimeAsync(1);
+    const revalidatedAt = Date.now();
+    await handler.updateTags(['posts'], { expire: 0 });
+
+    expect(await handler.getExpiration(['posts'])).toBe(revalidatedAt);
+    expect((handler as any).revalidatedTagsMap.get('posts')).toBe(
+      revalidatedAt,
+    );
+    expect(await handler.get('page', [])).toBeUndefined();
+  });
+
+  it('persists stale+expired so a later getExpiration still sees the window', async () => {
+    const handler = await createHandler('persist:');
+    const startedAt = Date.now();
+
+    await handler.updateTags(['posts'], { expire: 2 });
+    const stored = (handler as any).revalidatedTagsMap.get('posts');
+
+    expect(stored).toEqual({
+      stale: startedAt,
+      expired: startedAt + 2_000,
+    });
+  });
+
+  it('legacy plain number in Redis hard-expires once the timestamp is in the past', async () => {
+    const handler = await createHandler('legacy-past:');
+    const createdAt = Date.now() - 10_000;
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+
+    // Older package versions stored Date.now() directly (not Next.js).
+    (handler as any).revalidatedTagsMap.set('posts', Date.now() - 5_000);
+
+    expect(await handler.get('page', [])).toBeUndefined();
+  });
+
+  it('legacy plain number ahead of local clock is clamped and hard-expires immediately', async () => {
+    vi.setSystemTime(new Date(1_000_000));
+    const handler = await createHandler('legacy-skew:');
+    const createdAt = 900_000;
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+
+    // Another instance with a faster clock wrote this value to Redis.
+    (handler as any).revalidatedTagsMap.set('posts', 1_005_000);
+
+    expect(await handler.get('page', [])).toBeUndefined();
+  });
+
+  it.each([
+    ['seconds', 60],
+    ['minutes', 60 * 60],
+    ['hours', 60 * 60 * 24],
+    ['days', 60 * 60 * 24 * 7],
+    ['weeks', 60 * 60 * 24 * 30],
+    ['max', 60 * 60 * 24 * 365],
+    ['default', 0xfffffffe],
+  ] as const)(
+    'cacheLife %s expire writes getExpiration=now+expire*1000 and SWR',
+    async (_profile, expireSeconds) => {
+      const handler = await createHandler(`preset-${_profile}:`);
+      const createdAt = Date.now();
+
+      await handler.set(
+        'page',
+        Promise.resolve(cachedEntry(['posts'], createdAt)),
+      );
+      await vi.advanceTimersByTimeAsync(1);
+      const revalidatedAt = Date.now();
+      await handler.updateTags(['posts'], { expire: expireSeconds });
+
+      expect(await handler.getExpiration(['posts'])).toBe(
+        revalidatedAt + expireSeconds * 1000,
+      );
+      const served = await handler.get('page', []);
+      expect(served?.revalidate).toBe(-1);
+      expect(await handler.get('page', [])).toBeDefined();
+    },
+  );
+
+  it('does not UNLINK a Redis replacement after a stale deduped read', async () => {
+    const { getRedisCacheComponentsHandler } = await import(
+      '../../../src/CacheComponentsHandler'
+    );
+    const handler = getRedisCacheComponentsHandler({
+      keyPrefix: 'dedup-unlink:',
+      redisGetDeduplication: true,
+      inMemoryCachingTime: 10_000,
+    });
+
+    const createdAt = Date.now();
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    const redisKey = 'dedup-unlink:page';
+    const oldSerialized = hoisted.store.get(redisKey)!;
+
+    await vi.advanceTimersByTimeAsync(1);
+    await handler.updateTags(['posts']);
+
+    const freshAt = Date.now();
+    hoisted.store.set(
+      redisKey,
+      JSON.stringify({
+        value: Buffer.from('fresh').toString('base64'),
+        tags: ['posts'],
+        stale: 1,
+        timestamp: freshAt,
+        expire: 3600,
+        revalidate: 60,
+      }),
+    );
+    (handler as any).redisDeduplicationHandler.seedRequestReturn(
+      'page',
+      oldSerialized,
+    );
+
+    hoisted.unlinkedKeys.length = 0;
+    const served = await handler.get('page', []);
+
+    expect(hoisted.unlinkedKeys).toEqual([]);
+    expect(served).toBeDefined();
+    expect(hoisted.store.get(redisKey)).toBeTruthy();
+  });
+
+  it('keeps a later stale-only update after a hard expire and replacement', async () => {
+    const handler = await createHandler('stale-after-hard:');
+    const createdAt = Date.now();
+
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], createdAt)),
+    );
+    await vi.advanceTimersByTimeAsync(1);
+    const hardExpiredAt = Date.now();
+    await handler.updateTags(['posts']);
+    expect((handler as any).revalidatedTagsMap.get('posts')).toBe(
+      hardExpiredAt,
+    );
+
+    await vi.advanceTimersByTimeAsync(1);
+    const replacementAt = Date.now();
+    await handler.set(
+      'page',
+      Promise.resolve(cachedEntry(['posts'], replacementAt)),
+    );
+
+    await vi.advanceTimersByTimeAsync(1);
+    const staleAt = Date.now();
+    await handler.updateTags(['posts'], {});
+
+    expect((handler as any).revalidatedTagsMap.get('posts')).toEqual({
+      stale: staleAt,
+      expired: hardExpiredAt,
+    });
+
+    const served = await handler.get('page', []);
+    expect(served).toBeDefined();
+    expect(served?.revalidate).toBe(-1);
+  });
+});

package/test/vitest/unit/cache-ttl.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { resolveCacheEntryTtlSeconds } from '../../../src/utils/cacheTtl';
+
+const estimateExpireAge = (staleAge: number) => staleAge * 1.2;
+const defaultStaleAge = 60 * 60 * 24 * 14;
+
+describe('resolveCacheEntryTtlSeconds', () => {
+  it('prefers cacheControl.expire over revalidate (SWR-safe TTL)', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      { cacheControl: { revalidate: 60, expire: 3600 } },
+      { kind: 'APP_PAGE' },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBe(3600);
+  });
+
+  it('falls back to estimateExpireAge(revalidate) when expire is omitted', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      { cacheControl: { revalidate: 60, expire: undefined } },
+      { kind: 'PAGES' },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBe(72);
+  });
+
+  it('uses FETCH data.revalidate when cacheControl is absent', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      {},
+      { kind: 'FETCH', revalidate: 30 },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBe(36);
+  });
+
+  it('uses defaultStaleAge when revalidate is false', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      { cacheControl: { revalidate: false, expire: undefined } },
+      { kind: 'PAGES' },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBe(estimateExpireAge(defaultStaleAge));
+  });
+
+  it('returns undefined when no expire or revalidate is provided', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      { cacheControl: { revalidate: undefined, expire: undefined } },
+      { kind: 'APP_ROUTE' },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBeUndefined();
+  });
+
+  it('supports legacy ctx.revalidate (Next.js 15.0.3)', () => {
+    const ttl = resolveCacheEntryTtlSeconds(
+      { revalidate: 60 },
+      { kind: 'PAGES' },
+      { estimateExpireAge, defaultStaleAge },
+    );
+
+    expect(ttl).toBe(72);
+  });
+});

package/test/vitest/unit/compare-and-unlink.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect, vi } from 'vitest';
+import { compareAndUnlink } from '../../../src/utils/compareAndUnlink';
+
+describe('compareAndUnlink', () => {
+  it('evals GET+UNLINK and reports whether the key was removed', async () => {
+    const evalFn = vi.fn(async () => 1);
+    await expect(compareAndUnlink({ eval: evalFn }, 'k', 'old')).resolves.toBe(
+      true,
+    );
+    expect(evalFn).toHaveBeenCalledWith(
+      expect.stringContaining("redis.call('UNLINK'"),
+      { keys: ['k'], arguments: ['old'] },
+    );
+  });
+
+  it('returns false when the value no longer matches', async () => {
+    const evalFn = vi.fn(async () => 0);
+    await expect(compareAndUnlink({ eval: evalFn }, 'k', 'old')).resolves.toBe(
+      false,
+    );
+  });
+});

package/test/vitest/unit/index.test.ts

@@ -113,6 +113,23 @@ describe('RedisStringsHandler', () => {
       vi.useRealTimers();
     }
   });
+
+  it('skips Redis work in revalidateTag during next build', async () => {
+    vi.stubEnv('NEXT_PHASE', 'phase-production-build');
+    const { default: Handler } = await import(
+      '../../../src/RedisStringsHandler'
+    );
+    const handler = new Handler({
+      redisUrl: 'redis://localhost:6379',
+      keyPrefix: 'build:',
+      database: 0,
+      redisGetDeduplication: false,
+    });
+    const unlink = (handler as any).client.unlink as ReturnType<typeof vi.fn>;
+
+    await expect(handler.revalidateTag('posts')).resolves.toBeUndefined();
+    expect(unlink).not.toHaveBeenCalled();
+  });
 });
 
 describe('Public exports', () => {

package/test/vitest/unit/pages-router-kinds.test.ts

@@ -145,6 +145,17 @@ describe('RedisStringsHandler Pages Router kinds', () => {
       expect(ex).toBe(expireAge(DEFAULT_STALE_AGE));
     });
 
+    it('set() prefers cacheControl.expire over revalidate for the Redis TTL', async () => {
+      const handler = createHandler();
+      await handler.set('/blog/post-swr', pagesData, {
+        ...baseCtx,
+        cacheControl: { revalidate: 60, expire: 3600 },
+      });
+
+      const { ex } = storedEntry('/blog/post-swr');
+      expect(ex).toBe(3600);
+    });
+
     it('set() derives the TTL from the legacy ctx.revalidate argument (Next.js 15.0.3)', async () => {
       const handler = createHandler();
       await handler.set('/blog/post-legacy', pagesData, {

package/test/vitest/unit/redis-connection.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  PHASE_PRODUCTION_BUILD,
+  shouldDeferRedisConnection,
+} from '../../../src/utils/redisConnection';
+
+describe('shouldDeferRedisConnection', () => {
+  const originalPhase = process.env.NEXT_PHASE;
+
+  beforeEach(() => {
+    delete process.env.NEXT_PHASE;
+  });
+
+  afterEach(() => {
+    if (originalPhase === undefined) {
+      delete process.env.NEXT_PHASE;
+    } else {
+      process.env.NEXT_PHASE = originalPhase;
+    }
+  });
+
+  it('returns false when NEXT_PHASE is not set', () => {
+    expect(shouldDeferRedisConnection()).toBe(false);
+  });
+
+  it('returns true when NEXT_PHASE is phase-production-build', () => {
+    process.env.NEXT_PHASE = 'phase-production-build';
+    expect(shouldDeferRedisConnection()).toBe(true);
+  });
+
+  it('returns false for other Next.js phases', () => {
+    process.env.NEXT_PHASE = 'phase-production-server';
+    expect(shouldDeferRedisConnection()).toBe(false);
+  });
+
+  it('uses the Next.js PHASE_PRODUCTION_BUILD string', () => {
+    expect(PHASE_PRODUCTION_BUILD).toBe('phase-production-build');
+  });
+});

package/test/vitest/unit/tag-revalidation.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from 'vitest';
+import {
+  applyTagUpdate,
+  areTagsExpired,
+  areTagsStale,
+  maxExpiredTimestamp,
+  normalizeTagManifest,
+  persistableTagManifest,
+  type TagManifestEntry,
+} from '../../../src/utils/tagRevalidation';
+
+// Expire seconds from next/dist/server/config-shared.js cacheLife presets
+// (identical in Next.js 16.0.11, 16.2.6, 16.3.0).
+const CACHE_LIFE_EXPIRE_SECONDS = {
+  default: 0xfffffffe, // INFINITE_CACHE in next/dist/lib/constants.js
+  seconds: 60,
+  minutes: 60 * 60,
+  hours: 60 * 60 * 24,
+  days: 60 * 60 * 24 * 7,
+  weeks: 60 * 60 * 24 * 30,
+  max: 60 * 60 * 24 * 365,
+};
+
+describe('applyTagUpdate (Next.js DefaultCacheHandler.updateTags)', () => {
+  const now = 1_000_000;
+
+  it('with no durations sets expired=now and does not set stale', () => {
+    expect(applyTagUpdate({ stale: 9 }, undefined, now)).toEqual({
+      stale: 9,
+      expired: now,
+    });
+  });
+
+  it('with { expire: 0 } sets stale=now and expired=now (blocking miss)', () => {
+    expect(applyTagUpdate({}, { expire: 0 }, now)).toEqual({
+      stale: now,
+      expired: now,
+    });
+  });
+
+  it('with { expire: N } sets stale=now and expired=now+N*1000 (SWR window)', () => {
+    expect(applyTagUpdate({}, { expire: 2 }, now)).toEqual({
+      stale: now,
+      expired: now + 2_000,
+    });
+  });
+
+  it('uses each built-in cacheLife expire for revalidateTag(tag, profile)', () => {
+    for (const [profile, expire] of Object.entries(CACHE_LIFE_EXPIRE_SECONDS)) {
+      const result = applyTagUpdate({}, { expire }, now);
+      expect(result.stale, profile).toBe(now);
+      expect(result.expired, profile).toBe(now + expire * 1000);
+    }
+  });
+
+  it('with durations but expire undefined only marks stale (keeps prior expired)', () => {
+    expect(applyTagUpdate({ expired: 50 }, { expire: undefined }, now)).toEqual(
+      { stale: now, expired: 50 },
+    );
+  });
+});
+
+describe('areTagsExpired / areTagsStale (Next.js tags-manifest.external)', () => {
+  const lookup = (entry: { stale?: number; expired?: number }) => () => entry;
+
+  it('hard-expires when expired has elapsed and is newer than the entry', () => {
+    expect(areTagsExpired(['t'], 100, 1_000, lookup({ expired: 500 }))).toBe(
+      true,
+    );
+  });
+
+  it('does not hard-expire while expired is still in the future', () => {
+    expect(areTagsExpired(['t'], 100, 1_000, lookup({ expired: 2_000 }))).toBe(
+      false,
+    );
+  });
+
+  it('does not hard-expire when expiredAt equals the entry timestamp', () => {
+    expect(areTagsExpired(['t'], 500, 1_000, lookup({ expired: 500 }))).toBe(
+      false,
+    );
+  });
+
+  it('does not hard-expire entries created after the expired timestamp', () => {
+    expect(
+      areTagsExpired(['t'], 2_000, 3_000, lookup({ expired: 1_000 })),
+    ).toBe(false);
+  });
+
+  it('is stale when stale is newer than the entry timestamp', () => {
+    expect(areTagsStale(['t'], 100, lookup({ stale: 500 }))).toBe(true);
+  });
+
+  it('is not stale when stale is older than the entry', () => {
+    expect(areTagsStale(['t'], 1_000, lookup({ stale: 500 }))).toBe(false);
+  });
+});
+
+describe('maxExpiredTimestamp (Next.js getExpiration)', () => {
+  it('returns 0 when no tag was expired', () => {
+    expect(maxExpiredTimestamp(['a'], () => ({}))).toBe(0);
+  });
+
+  it('returns a future expired timestamp (SWR window has not elapsed)', () => {
+    expect(
+      maxExpiredTimestamp(['a'], () => ({ stale: 1, expired: 9_000 })),
+    ).toBe(9_000);
+  });
+});
+
+describe('normalizeTagManifest', () => {
+  it('reads Next.js { stale, expired } records', () => {
+    expect(normalizeTagManifest({ stale: 1, expired: 2 })).toEqual({
+      stale: 1,
+      expired: 2,
+    });
+  });
+
+  it('maps a legacy numeric timestamp to expired', () => {
+    expect(normalizeTagManifest(1_234)).toEqual({ expired: 1_234 });
+  });
+});
+
+describe('legacy plain numbers (rolling upgrade, not Next.js)', () => {
+  const lookup = (entry: TagManifestEntry | undefined) => (tag: string) =>
+    tag === 't' ? entry : undefined;
+
+  it('past plain number hard-expires entries older than the revalidation', () => {
+    const revalidatedAt = 500;
+    const manifest = normalizeTagManifest(revalidatedAt);
+
+    expect(areTagsExpired(['t'], 100, 1_000, lookup(manifest))).toBe(true);
+    expect(areTagsStale(['t'], 100, lookup(manifest))).toBe(false);
+  });
+
+  it('clamps future plain numbers to now (cross-instance clock skew)', () => {
+    // Instance A (clock ahead) wrote Date.now() = 1_005_000 into Redis.
+    // This reader's clock is still at 1_000_000 — clamp treats it as now.
+    const manifest = normalizeTagManifest(1_005_000, 1_000_000);
+
+    expect(manifest).toEqual({ expired: 1_000_000 });
+    expect(areTagsExpired(['t'], 900_000, 1_000_000, lookup(manifest))).toBe(
+      true,
+    );
+  });
+
+  it('intentional SWR uses stale + future expired, not a plain number', () => {
+    const now = 1_000_000;
+    const swr = applyTagUpdate({}, { expire: 2 }, now);
+
+    expect(swr).toEqual({ stale: now, expired: now + 2_000 });
+    expect(areTagsStale(['t'], 900_000, lookup(swr))).toBe(true);
+    expect(areTagsExpired(['t'], 900_000, now + 500, lookup(swr))).toBe(false);
+  });
+});
+
+describe('persistableTagManifest', () => {
+  const now = 1_000_000;
+
+  it('writes a plain number for immediate hard-expires (rolling-upgrade readers)', () => {
+    expect(persistableTagManifest({ expired: now }, now)).toBe(now);
+    expect(persistableTagManifest({ stale: now, expired: now }, now)).toBe(now);
+  });
+
+  it('keeps { stale, expired } objects for SWR windows', () => {
+    const swr = { stale: now, expired: now + 2_000 };
+    expect(persistableTagManifest(swr, now)).toEqual(swr);
+  });
+
+  it('keeps the object when a newer stale-only update outruns a past expired', () => {
+    const expired = now - 5_000;
+    const stale = now;
+    expect(persistableTagManifest({ stale, expired }, now)).toEqual({
+      stale,
+      expired,
+    });
+  });
+});