@aiquants/daily-report 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/daily-report",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Reusable daily-report feature package: shared types/schemas, React (Router v7) UI with virtual scrolling + optimistic updates + SSE sync, and a drizzle (mssql) server layer with DI ports (auth, user resolution, redis, external sources).",
   "sideEffects": [
     "**/*.css"
@@ -81,8 +81,8 @@
     "react-dom": ">=18",
     "react-router": "^7.0.0",
     "zod": ">=3.25.0 <5.0.0",
-    "@aiquants/virtualscroll": "^1.23.0",
-    "@aiquants/swipe-overlay": "^1.2.4"
+    "@aiquants/swipe-overlay": "^1.2.4",
+    "@aiquants/virtualscroll": "^1.23.0"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {

package/src/server/cache.spec.ts

@@ -11,7 +11,7 @@ describe("SqlResultCache Memory Cleanup", () => {
 
         // 1. 期限切れのキャッシュを 500 件作成 (expireAt を過去に設定)
         // 直接プライベートフィールド buckets に流し込むことでモック状態を作る
-        const buckets = (cache as any).buckets
+        const buckets = (cache as unknown as { buckets: Map<string, { records: readonly unknown[]; expireAt: number; epoch: number }> }).buckets
         for (let i = 0; i < 505; i++) {
             buckets.set(`expired-key-${i}`, {
                 records: [i],
@@ -45,3 +45,367 @@ describe("SqlResultCache Memory Cleanup", () => {
         expect(buckets.has("expired-key-0")).toBe(false)
     })
 })
+
+describe("SqlResultCache refresh-ahead", () => {
+    /** テスト用のキャッシュと覗き穴 (プライベート buckets / inFlight) を組み立てるヘルパー。 */
+    const makeCache = (ttlMs = 200_000, epochValue: { value: number } = { value: 0 }) => {
+        const epochStore = createEpochStore(undefined)
+        // 可変 epoch: フェッチ中の他ワーカー更新 (incrementEpoch) を模擬できるようにする
+        vi.spyOn(epochStore, "getEpoch").mockImplementation(async () => epochValue.value)
+        const cache = new SqlResultCache({ defaultTtlMs: ttlMs }, epochStore)
+        const buckets = (cache as unknown as { buckets: Map<string, { records: readonly unknown[]; expireAt: number; epoch: number }> }).buckets
+        const inFlight = (cache as unknown as { inFlight: Map<string, Promise<readonly unknown[]>> }).inFlight
+        return { cache, buckets, inFlight }
+    }
+
+    /**
+     * バケットの残余 TTL を書き換えて「年齢」を偽装する (expireAt = now + remainingMs)。
+     * CI ストール耐性のため残余は大きく取る (残余が小さいとテスト中に本当に失効し、
+     * 手動解決フェッチへ相乗りしてデッドロックする)。
+     */
+    const ageBucket = (buckets: Map<string, { expireAt: number }>, key: string, remainingMs: number) => {
+        const bucket = buckets.get(key)
+        if (!bucket) throw new Error(`bucket not found: ${key}`)
+        bucket.expireAt = Date.now() + remainingMs
+    }
+
+    it("refreshAheadRatio 未指定なら、老化したヒットでも裏フェッチは走らない (従来動作)", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        const fetcher = vi.fn().mockResolvedValue(["v1"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher })
+        ageBucket(buckets, "k", 60_000) // 年齢 140 秒相当 (ratio 0.5 なら発火する老化度)
+
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher })
+        expect(hit).toEqual(["v1"])
+        expect(fetcher).toHaveBeenCalledTimes(1)
+        expect(inFlight.size).toBe(0)
+    })
+
+    it("若いヒット (年齢 < ttl × ratio) では裏フェッチは走らない", async () => {
+        const { cache, inFlight } = makeCache()
+        const fetcher = vi.fn().mockResolvedValue(["v1"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+
+        // 直後のヒット = 年齢ほぼ 0
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hit).toEqual(["v1"])
+        expect(fetcher).toHaveBeenCalledTimes(1)
+        expect(inFlight.size).toBe(0)
+    })
+
+    it("refreshAheadRatio 0 は毎ヒット裏更新 (undefined との区別 = falsy 判定への退行を検知)", async () => {
+        const { cache, inFlight } = makeCache()
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockResolvedValue(["v2"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0 })
+
+        // 年齢 0 でも ratio 0 なら発火する (`if (!ratio)` へ書き換えると発火せず失敗する)
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0 })
+        expect(hit).toEqual(["v1"])
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(fetcher).toHaveBeenCalledTimes(2)
+    })
+
+    it("老化したヒットは旧値を即返しつつ、裏フェッチはちょうど 1 本だけ走ってバケットを差し替える", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        // 2 回目以降のフェッチは手動解決 (裏フェッチ進行中の並行ヒットを再現するため)
+        let releaseSecond!: (v: readonly unknown[]) => void
+        const second = new Promise<readonly unknown[]>((resolve) => {
+            releaseSecond = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValue(second)
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        ageBucket(buckets, "k", 60_000)
+
+        // ヒット A: 旧値を即返し + 裏フェッチ起動
+        const hitA = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hitA).toEqual(["v1"])
+        expect(inFlight.has("k")).toBe(true)
+
+        // ヒット B: 裏フェッチ進行中でも旧値を即返し、2 本目は起動しない (in-flight ガード)
+        const hitB = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hitB).toEqual(["v1"])
+        expect(fetcher).toHaveBeenCalledTimes(2) // 初回 + 裏フェッチ 1 本のみ
+
+        // 裏フェッチ完了 → バケットが新値へ差し替わり、inFlight は掃除される
+        const backgroundPromise = inFlight.get("k")
+        releaseSecond(["v2"])
+        await backgroundPromise
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(buckets.get("k")?.records).toEqual(["v2"])
+        const hitC = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hitC).toEqual(["v2"])
+        expect(fetcher).toHaveBeenCalledTimes(2)
+    })
+
+    it("ttl は ttlMsOverride を優先する: 発火閾値も差し替え後の expireAt も override 基準 (本番構成)", async () => {
+        // 本番は defaultTtlMs より大きい ttlMsOverride を渡す構成 (60s default / 180s override)。
+        // ここでは逆向きの大小関係 (default 200s ≫ override 1s) にして、defaultTtlMs へ
+        // 退行すると (a) 発火せず (b) 寿命が伸びる、の両方を検知できるようにする
+        const { cache, buckets, inFlight } = makeCache(200_000)
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockResolvedValue(["v2"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher, ttlMsOverride: 1000, refreshAheadRatio: 0.5 })
+
+        // 残余 300ms = override 基準の年齢 700ms (> 500ms 閾値)。default 基準なら年齢は負で発火しない
+        ageBucket(buckets, "k", 300)
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, ttlMsOverride: 1000, refreshAheadRatio: 0.5 })
+        expect(hit).toEqual(["v1"])
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(fetcher).toHaveBeenCalledTimes(2)
+        // 差し替え後の寿命は override 基準 (default の 200 秒ではない)
+        const bucket = buckets.get("k")
+        expect(bucket?.records).toEqual(["v2"])
+        expect((bucket?.expireAt ?? 0) - Date.now()).toBeLessThanOrEqual(1000)
+    })
+
+    it("裏フェッチが失敗しても、バケットが有効な間は旧値で即答し続ける (safe 方向)", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockRejectedValue(new Error("db down"))
+        await cache.getOrFetch({ cacheKey: "k", fetcher })
+        ageBucket(buckets, "k", 60_000)
+
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hit).toEqual(["v1"])
+        // 裏フェッチの失敗を消化させる (unhandled rejection にならないことも暗黙に検証)
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(buckets.get("k")?.records).toEqual(["v1"])
+        const hitAfterFailure = await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        expect(hitAfterFailure).toEqual(["v1"])
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+    })
+
+    it("裏フェッチ進行中に invalidate されたら結果を書き込まない (前面経路と同じ無効化レース規約)", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        let releaseSecond!: (v: readonly unknown[]) => void
+        const second = new Promise<readonly unknown[]>((resolve) => {
+            releaseSecond = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValue(second)
+        await cache.getOrFetch({ cacheKey: "daily-report:ids", fetcher, refreshAheadRatio: 0.5 })
+        ageBucket(buckets, "daily-report:ids", 60_000)
+
+        await cache.getOrFetch({ cacheKey: "daily-report:ids", fetcher, refreshAheadRatio: 0.5 })
+        const backgroundPromise = inFlight.get("daily-report:ids")
+        expect(backgroundPromise).toBeDefined()
+
+        // 進行中に SSE 由来の無効化が走ったと想定
+        cache.invalidatePrefix("daily-report:ids")
+        releaseSecond(["stale-write"])
+        await backgroundPromise
+
+        // 無効化後のバケットへ古い結果を書き戻さないこと
+        expect(buckets.has("daily-report:ids")).toBe(false)
+    })
+
+    it("epochKey 併用 (本番構成) でも同様: getEpoch 中に落ちた無効化でも書き込まない", async () => {
+        // 本番の ids 経路は必ず epochKey 併用。ガード判定と書き込みの間に epoch の Redis await が
+        // 挟まると、その間の invalidate を取りこぼしてバケットを復活させてしまう退行を検知する
+        const { cache, buckets, inFlight } = makeCache(200_000, { value: 0 })
+        let releaseSecond!: (v: readonly unknown[]) => void
+        const second = new Promise<readonly unknown[]>((resolve) => {
+            releaseSecond = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValue(second)
+        await cache.getOrFetch({ cacheKey: "daily-report:ids", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        ageBucket(buckets, "daily-report:ids", 60_000)
+
+        await cache.getOrFetch({ cacheKey: "daily-report:ids", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        expect(inFlight.has("daily-report:ids")).toBe(true)
+        const backgroundPromise = inFlight.get("daily-report:ids")
+        cache.invalidatePrefix("daily-report:ids")
+        releaseSecond(["stale-write"])
+        await backgroundPromise
+        expect(buckets.has("daily-report:ids")).toBe(false)
+    })
+
+    it("epoch はフェッチ開始前に採取する: フェッチ中の他ワーカー更新を新 epoch で偽装しない", async () => {
+        const epochValue = { value: 7 }
+        const { cache, buckets, inFlight } = makeCache(200_000, epochValue)
+        let releaseSecond!: (v: readonly unknown[]) => void
+        const second = new Promise<readonly unknown[]>((resolve) => {
+            releaseSecond = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValue(second)
+        await cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        expect(buckets.get("k")?.epoch).toBe(7)
+        ageBucket(buckets, "k", 60_000)
+
+        // 老化ヒット → 裏フェッチ起動 (epoch 7 を開始前に採取)
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        expect(hit).toEqual(["v1"])
+        // フェッチ中に他ワーカーが更新 → epoch 9 へ (incrementEpoch 相当)
+        epochValue.value = 9
+        releaseSecond(["pre-mutation-data"])
+        await inFlight.get("k")
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+
+        // ❗ 差し替えバケットの epoch は「開始前」の 7 であること。完了後採取 (9) だと
+        // 旧データが新 epoch を纏い、次のヒットの epoch 照合をすり抜けて stale を配ってしまう
+        expect(buckets.get("k")?.epoch).toBe(7)
+        // 次のヒットは epoch 不一致 (7 ≠ 9) を検出して再フェッチする (自己回復)
+        const fetcherAfter = vi.fn().mockResolvedValue(["post-mutation-data"])
+        const healed = await cache.getOrFetch({ cacheKey: "k", fetcher: fetcherAfter, epochKey: "e", refreshAheadRatio: 0.5 })
+        expect(healed).toEqual(["post-mutation-data"])
+        expect(fetcherAfter).toHaveBeenCalledTimes(1)
+    })
+
+    it("epochKey 併用のヒット経路でも老化ヒットで裏フェッチが起動する", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockResolvedValue(["v2"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "epoch:k", refreshAheadRatio: 0.5 })
+        ageBucket(buckets, "k", 60_000)
+
+        const hit = await cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "epoch:k", refreshAheadRatio: 0.5 })
+        expect(hit).toEqual(["v1"])
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(buckets.get("k")?.records).toEqual(["v2"])
+        expect(fetcher).toHaveBeenCalledTimes(2)
+    })
+
+    it("裏フェッチ進行中に TTL が切れた前面リクエストは裏フェッチへ相乗りする (二重クエリ防止)", async () => {
+        const { cache, buckets, inFlight } = makeCache()
+        let releaseSecond!: (v: readonly unknown[]) => void
+        const second = new Promise<readonly unknown[]>((resolve) => {
+            releaseSecond = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValue(second)
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        ageBucket(buckets, "k", 60_000)
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 }) // 裏フェッチ起動
+
+        // 裏フェッチ完了前に TTL が完全に切れる (意図的な失効。相乗りするので手動解決とデッドロックしない)
+        ageBucket(buckets, "k", -1)
+        const ridePromise = cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        releaseSecond(["v2"])
+        expect(await ridePromise).toEqual(["v2"])
+        expect(fetcher).toHaveBeenCalledTimes(2) // 相乗りできており 3 本目は走らない
+        await vi.waitFor(() => expect(inFlight.size).toBe(0))
+        expect(buckets.get("k")?.records).toEqual(["v2"])
+    })
+})
+
+describe("SqlResultCache foreground write-guard integrity", () => {
+    it("前面 finally の inFlight 掃除は identity チェック付き: 先行フェッチの完了が後続の登録を壊さない", async () => {
+        // シーケンス: F1 コールド開始 → 無効化 (F1 の登録を正しく削除) → F2 開始 (登録)
+        // → F1 完了 (finally が F2 の登録を消してはならない) → F2 完了 (バケット保存成功)
+        const epochStore = createEpochStore(undefined)
+        vi.spyOn(epochStore, "getEpoch").mockResolvedValue(0)
+        const cache = new SqlResultCache({ defaultTtlMs: 200_000 }, epochStore)
+        const buckets = (cache as unknown as { buckets: Map<string, { records: readonly unknown[] }> }).buckets
+
+        let releaseF1!: (v: readonly unknown[]) => void
+        const f1Gate = new Promise<readonly unknown[]>((resolve) => {
+            releaseF1 = resolve
+        })
+        let releaseF2!: (v: readonly unknown[]) => void
+        const f2Gate = new Promise<readonly unknown[]>((resolve) => {
+            releaseF2 = resolve
+        })
+        const fetcher = vi.fn().mockReturnValueOnce(f1Gate).mockReturnValueOnce(f2Gate)
+
+        const p1 = cache.getOrFetch({ cacheKey: "k", fetcher })
+        cache.invalidatePrefix("k") // F1 進行中に SSE 由来の無効化
+        const p2 = cache.getOrFetch({ cacheKey: "k", fetcher }) // 後続 F2 が登録し直す
+        releaseF1(["f1-stale"])
+        await p1 // F1 完了 (旧実装: ここで無条件 delete が F2 の登録を clobber していた)
+        releaseF2(["f2-fresh"])
+        expect(await p2).toEqual(["f2-fresh"])
+
+        // F2 の結果が正しくバケットへ保存されていること (毒殺されていないこと)
+        expect(buckets.get("k")?.records).toEqual(["f2-fresh"])
+    })
+
+    it("前面経路も epoch はフェッチ開始前に採取する (フェッチ中の他ワーカー更新を新 epoch で偽装しない)", async () => {
+        const epochValue = { value: 7 }
+        const epochStore = createEpochStore(undefined)
+        vi.spyOn(epochStore, "getEpoch").mockImplementation(async () => epochValue.value)
+        const cache = new SqlResultCache({ defaultTtlMs: 200_000 }, epochStore)
+        const buckets = (cache as unknown as { buckets: Map<string, { epoch: number }> }).buckets
+
+        let release!: (v: readonly unknown[]) => void
+        const gate = new Promise<readonly unknown[]>((resolve) => {
+            release = resolve
+        })
+        const fetchPromise = cache.getOrFetch({ cacheKey: "k", fetcher: () => gate, epochKey: "e" })
+        // コールドフェッチ中に他ワーカーが更新 → epoch 9 へ
+        epochValue.value = 9
+        release(["v1"])
+        await fetchPromise
+        // 開始前の 7 で刻まれていること (9 だと次ヒットの照合をすり抜けて stale を配る)
+        expect(buckets.get("k")?.epoch).toBe(7)
+    })
+
+    it("裏フェッチ finally の掃除も identity チェック付き: 無効化後に登録し直した後続を壊さない", async () => {
+        // 前面テストの鏡像。裏フェッチ (refresh-ahead) の finally が無条件 delete へ退行すると、
+        // 無効化 → 後続コールド F2 登録 → 裏フェッチ完了、の順で F2 の登録が消え書き込みガードが壊れる
+        const epochStore = createEpochStore(undefined)
+        vi.spyOn(epochStore, "getEpoch").mockResolvedValue(0)
+        const cache = new SqlResultCache({ defaultTtlMs: 200_000 }, epochStore)
+        const buckets = (cache as unknown as { buckets: Map<string, { records: readonly unknown[]; expireAt: number }> }).buckets
+        const inFlight = (cache as unknown as { inFlight: Map<string, Promise<readonly unknown[]>> }).inFlight
+
+        let releaseBg!: (v: readonly unknown[]) => void
+        const bgGate = new Promise<readonly unknown[]>((resolve) => {
+            releaseBg = resolve
+        })
+        let releaseF2!: (v: readonly unknown[]) => void
+        const f2Gate = new Promise<readonly unknown[]>((resolve) => {
+            releaseF2 = resolve
+        })
+        const fetcher = vi.fn().mockResolvedValueOnce(["v1"]).mockReturnValueOnce(bgGate).mockReturnValueOnce(f2Gate)
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 })
+        const bucket = buckets.get("k")
+        if (!bucket) throw new Error("bucket not found")
+        bucket.expireAt = Date.now() + 60_000 // 老化偽装
+
+        await cache.getOrFetch({ cacheKey: "k", fetcher, refreshAheadRatio: 0.5 }) // 裏フェッチ起動 (bgGate)
+        cache.invalidatePrefix("k") // 裏フェッチの登録を正しく削除
+        const p2 = cache.getOrFetch({ cacheKey: "k", fetcher }) // 後続コールド F2 が登録し直す
+        const f2Promise = inFlight.get("k")
+        expect(f2Promise).toBeDefined()
+
+        releaseBg(["bg-stale"])
+        await bgGate
+        await new Promise((resolve) => setImmediate(resolve))
+        // 裏フェッチの finally が F2 の登録を消していないこと
+        expect(inFlight.get("k")).toBe(f2Promise)
+
+        releaseF2(["f2-fresh"])
+        expect(await p2).toEqual(["f2-fresh"])
+        expect(buckets.get("k")?.records).toEqual(["f2-fresh"])
+    })
+
+    it("epoch 照合の await 中にバケットが無効化されたら refresh-ahead は静かに何もしない (生きバケット再読)", async () => {
+        // ヒット判定はエントリ時点のバケット参照で行われるが、epoch 照合の Redis await 中に
+        // invalidatePrefix が落ちるとバケットは消えている。maybeRefreshAhead が呼び出し元の
+        // スナップショットに触れると TypeError や不要な裏フェッチになるため、生きバケットの
+        // 再読 + null ガードで無反応になることを固定する
+        const epochStore = createEpochStore(undefined)
+        let releaseEpoch!: (v: number) => void
+        const epochGate = new Promise<number>((resolve) => {
+            releaseEpoch = resolve
+        })
+        const getEpoch = vi.spyOn(epochStore, "getEpoch")
+        getEpoch.mockResolvedValueOnce(0) // 初回保存時
+        getEpoch.mockReturnValueOnce(epochGate) // ヒット時の照合 (ゲート)
+        const cache = new SqlResultCache({ defaultTtlMs: 200_000 }, epochStore)
+        const buckets = (cache as unknown as { buckets: Map<string, { records: readonly unknown[]; expireAt: number }> }).buckets
+        const inFlight = (cache as unknown as { inFlight: Map<string, Promise<readonly unknown[]>> }).inFlight
+
+        const fetcher = vi.fn().mockResolvedValue(["v1"])
+        await cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        const bucket = buckets.get("k")
+        if (!bucket) throw new Error("bucket not found")
+        bucket.expireAt = Date.now() + 60_000 // 老化偽装
+
+        const hitPromise = cache.getOrFetch({ cacheKey: "k", fetcher, epochKey: "e", refreshAheadRatio: 0.5 })
+        cache.invalidatePrefix("k") // 照合 await 中の無効化
+        releaseEpoch(0) // epoch は一致 → ヒット継続 → maybeRefreshAhead 到達
+        const hit = await hitPromise
+        // エントリ時点の参照から旧値は返る (この挙動は従来どおり)
+        expect(hit).toEqual(["v1"])
+        // 消えたバケットに対して裏フェッチを起動しない (TypeError にもならない)
+        expect(fetcher).toHaveBeenCalledTimes(1)
+        expect(inFlight.size).toBe(0)
+        expect(buckets.has("k")).toBe(false)
+    })
+})

package/src/server/cache.ts

@@ -11,6 +11,14 @@ export type SqlResultCacheQueryOptions = {
     snapshot?: boolean
     ttlMsOverride?: number
     epochKey?: string
+    /**
+     * ヒット時にバケット年齢が ttl × ratio を超えていたら、キャッシュ値を即返しつつ
+     * 裏で 1 本だけ再フェッチして置き換える (未指定は従来動作 = 何もしない)。
+     * 有効域は 0 <= ratio < 1: ヒット判定が「未失効」を要求するため年齢は常に ttl 未満であり、
+     * ratio 1 は事実上発火しない。ratio 0 は毎ヒット裏更新 (undefined とは区別される)。
+     * 定期的にアクセスされるキーの「TTL 切れ直後のコールド遭遇」を対話リクエストから排除する。
+     */
+    refreshAheadRatio?: number
 }
 
 /**
@@ -71,6 +79,66 @@ export class SqlResultCache {
         this.inFlight.delete(cacheKey)
     }
 
+    /**
+     * Kicks a single background refetch when the bucket has aged past ttl * ratio.
+     * バケット年齢が ttl × ratio を超えたヒット時に、裏で 1 本だけ再フェッチを起動する処理。
+     *
+     * 応答は誰も待たない。完了までは旧バケットがそのまま生きているため、並行するヒットは
+     * 従来どおりキャッシュから即答する (バケットを先に消す forceRefresh 委譲はスタンピードに
+     * なるため使わない)。バケットが有効な間は失敗しても旧バケットが残るだけ (safe 方向)。
+     * 裏フェッチ中に TTL が完全に切れて in-flight へ相乗りした前面リクエストには、通常の
+     * in-flight 共有と同じく失敗が伝播する (相乗りしなくても自前フェッチが同様に失敗する状況)。
+     * in-flight が既に居れば起動しない (前面リクエストの結果で足りる)。
+     */
+    private maybeRefreshAhead = <T>(opts: { cacheKey: string; fetcher: () => Promise<readonly T[]> } & SqlResultCacheQueryOptions): void => {
+        const ratio = opts.refreshAheadRatio
+        if (ratio === undefined) {
+            return
+        }
+        const { cacheKey } = opts
+        // 年齢は呼び出し元のスナップショットではなく生きているバケットで測る。epoch 照合の
+        // Redis await 中に進行中の裏フェッチが完了していると、古い expireAt のまま余分な
+        // 2 本目を起動してしまう (置換直後のバケットは若く、再フェッチ不要)
+        const bucket = this.buckets.get(cacheKey)
+        if (!bucket) {
+            return
+        }
+        const ttl = opts.ttlMsOverride ?? this.config.defaultTtlMs
+        const age = ttl - (bucket.expireAt - Date.now())
+        if (age < ttl * ratio) {
+            return
+        }
+        if (this.inFlight.has(cacheKey)) {
+            return
+        }
+
+        // 旧バケットを残したまま裏で取得し、完了時に差し替える。無効化レースの規約は
+        // 前面経路と同一: 進行中に invalidate されたら (inFlight の同一性が崩れたら) 書かない
+        let promise!: Promise<readonly T[]>
+        promise = (async () => {
+            // ❗ epoch はフェッチ「開始前」に採取する。完了後に採取すると、フェッチ中に他ワーカーが
+            // 更新 (incrementEpoch) した後の値で旧データに新 epoch を刻んでしまい、epoch 照合
+            // (staleness の主防御線) が丸ごと無効化される。開始前採取なら不一致 → 再フェッチで自己回復
+            const epoch = opts.epochKey ? await this.epochStore.getEpoch(opts.epochKey) : 0
+            const records = await opts.fetcher()
+            // ガード判定と書き込みの間に await を挟まない (この間に落ちた invalidate の取りこぼし防止)
+            if (this.inFlight.get(cacheKey) === promise) {
+                this.buckets.set(cacheKey, { records, expireAt: Date.now() + ttl, epoch })
+            }
+            return records
+        })()
+        // 登録することで、裏フェッチ中に TTL 切れした前面リクエストは相乗りできる
+        this.inFlight.set(cacheKey, promise as Promise<readonly unknown[]>)
+        promise
+            .catch(() => {})
+            .finally(() => {
+                // 無効化で消されたり別の登録に置き換わっていたら触らない
+                if (this.inFlight.get(cacheKey) === promise) {
+                    this.inFlight.delete(cacheKey)
+                }
+            })
+    }
+
     /**
      * Retrieves records from cache or fetches them if expired/missing.
      * キャッシュからレコードを取得するか、期限切れや未存在の場合はフェッチします。
@@ -96,11 +164,13 @@ export class SqlResultCache {
                 // epochKey 指定時は Redis の epoch と比較して stale を検出
                 const currentEpoch = await this.epochStore.getEpoch(opts.epochKey)
                 if (bucket.epoch === currentEpoch) {
+                    this.maybeRefreshAhead(opts)
                     return snapshot ? (bucket.records.map((r) => structuredClone(r)) as T[]) : (bucket.records as T[])
                 }
                 // epoch 不一致 → stale bucket を除去して re-fetch へ
                 this.buckets.delete(cacheKey)
             } else {
+                this.maybeRefreshAhead(opts)
                 return snapshot ? (bucket.records.map((r) => structuredClone(r)) as T[]) : (bucket.records as T[])
             }
         }
@@ -115,13 +185,14 @@ export class SqlResultCache {
         // 自己参照 (this.inFlight.get(cacheKey) === promise) のため、定義前参照を回避する確定代入アサーション
         let promise!: Promise<readonly T[]>
         promise = (async () => {
+            // ❗ epoch はフェッチ「開始前」に採取する (理由は maybeRefreshAhead と同一:
+            // フェッチ中の他ワーカー更新を新 epoch で偽装しない。ガードと書き込みも同期隣接に保つ)
+            const epoch = opts.epochKey ? await this.epochStore.getEpoch(opts.epochKey) : 0
             const records = await opts.fetcher()
             // invalidation 中に完了したリクエストはキャッシュに書き込まない（レース防止）
             // ただし forceRefresh の場合は常に書き込む
             if (forceRefresh || this.inFlight.get(cacheKey) === promise) {
                 const expireAt = Date.now() + (opts.ttlMsOverride ?? this.config.defaultTtlMs)
-                // キャッシュ保存時に現在の epoch を記録
-                const epoch = opts.epochKey ? await this.epochStore.getEpoch(opts.epochKey) : 0
                 this.buckets.set(cacheKey, { records, expireAt, epoch })
                 // 蓄積防止のため、サイズが一定値を超えたら期限切れキャッシュを一括クリーンアップ
                 if (this.buckets.size > 500) {
@@ -137,7 +208,12 @@ export class SqlResultCache {
             const result = await promise
             return snapshot ? result.map((r) => structuredClone(r)) : result
         } finally {
-            this.inFlight.delete(cacheKey)
+            // ❗ identity チェック必須: 無効化が本リクエストの登録を消した後に後続リクエストが
+            // 登録し直していた場合、無条件 delete は「後続」の書き込みガードまで壊してしまう
+            // (2 本のフェッチが完走したのにバケットが空、という毒殺の温床)
+            if (this.inFlight.get(cacheKey) === promise) {
+                this.inFlight.delete(cacheKey)
+            }
         }
     }
 

package/src/server/service.spec.ts

@@ -3,7 +3,7 @@ import { bigint, MsSqlDialect, mssqlSchema, nvarchar, primaryKey } from "drizzle
 import { describe, expect, it } from "vitest"
 import { createEpochStore, SqlResultCache } from "./cache"
 import { defineDailyReportSchema } from "./schema"
-import { createDailyReportService, type DailyReportDb, type DailyReportHubRow } from "./service"
+import { createDailyReportService, type DailyReportDb, type DailyReportHubRow, formatDateValue } from "./service"
 
 /**
  * Security regression tests for audit-actor masking in mapHubRecord.
@@ -437,3 +437,105 @@ describe("コメント操作の整合性チェック", () => {
         expect(add?.recipientRawUserId).toBe(8)
     })
 })
+
+describe("formatDateValue (Intl-free rewrite equivalence)", () => {
+    /**
+     * Reference implementation: the pre-fix Intl-based formatter, copied verbatim.
+     * 参照実装: 修正前の Intl ベース整形処理の逐語コピー。
+     *
+     * 等価性テストの oracle として使う。呼び出しごとに Intl.DateTimeFormat を生成するため
+     * 本体からは根絶済 (227k 行 map で 15〜20 秒の CPU 洪水になる)。テスト内 oracle 用途に限る。
+     */
+    const referenceFormatDateValue = (value: Date | string | null | undefined, pattern: "YYYY-MM-DD HH:mm:ss" | "YYYY-MM-DD"): string | null => {
+        if (!value) {
+            return null
+        }
+        const dateValue = value instanceof Date ? value : new Date(value)
+        if (Number.isNaN(dateValue.getTime())) {
+            return typeof value === "string" ? value : null
+        }
+        const opts: Intl.DateTimeFormatOptions = pattern === "YYYY-MM-DD HH:mm:ss" ? { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" } : { year: "numeric", month: "2-digit", day: "2-digit" }
+        const formatted = pattern === "YYYY-MM-DD HH:mm:ss" ? dateValue.toLocaleString("ja-JP", opts) : dateValue.toLocaleDateString("ja-JP", opts)
+        return formatted.replace(/\//g, "-")
+    }
+
+    /** 再現可能な乱数列 (LCG)。テストを決定的にするため Math.random は使わない。 */
+    const makeLcg = (seed: number) => {
+        let state = seed >>> 0
+        return () => {
+            state = (state * 1664525 + 1013904223) >>> 0
+            return state / 0x1_0000_0000
+        }
+    }
+
+    it("ランダム 500 日時 × 両パターンで旧 Intl 実装と完全一致する (1900-2100 年域)", () => {
+        const rand = makeLcg(20260810)
+        const minMs = Date.UTC(1900, 0, 1)
+        const spanMs = Date.UTC(2100, 0, 1) - minMs
+        for (let i = 0; i < 500; i++) {
+            const d = new Date(minMs + Math.floor(rand() * spanMs))
+            for (const pattern of ["YYYY-MM-DD", "YYYY-MM-DD HH:mm:ss"] as const) {
+                expect(formatDateValue(d, pattern), `${d.toISOString()} / ${pattern}`).toBe(referenceFormatDateValue(d, pattern))
+            }
+        }
+    })
+
+    it("境界値 (月替わり・年跨ぎ・一桁時分秒・真夜中・閏日・秒 59) で旧実装と完全一致する", () => {
+        const edges = [
+            new Date(2026, 0, 1, 0, 0, 0), // 年始・真夜中 (h23 で 00 になること)
+            new Date(2025, 11, 31, 23, 59, 59), // 年末・全フィールド最大
+            new Date(2026, 7, 31, 1, 2, 3), // 一桁時分秒 (ゼロ詰め)
+            new Date(2024, 1, 29, 12, 0, 0), // 閏日
+            new Date(2026, 8, 30, 9, 5, 0), // 月末 30 日
+            new Date(2026, 2, 1, 0, 0, 1), // 月初・秒 1
+        ]
+        for (const d of edges) {
+            for (const pattern of ["YYYY-MM-DD", "YYYY-MM-DD HH:mm:ss"] as const) {
+                expect(formatDateValue(d, pattern), `${d.toISOString()} / ${pattern}`).toBe(referenceFormatDateValue(d, pattern))
+            }
+        }
+    })
+
+    it("文字列入力 (ISO 日付・ISO 日時・スペース区切り) でも旧実装と完全一致する", () => {
+        // "YYYY-MM-DD" 形式は Date 仕様上 UTC 深夜として解釈されローカルへずれるが、
+        // その挙動ごと旧実装と一致していることが等価性の要件 (挙動変更ではないことの証明)
+        const inputs = ["2026-08-10", "2026-08-10T15:30:00", "2026-08-10 15:30:00", "2026-01-01T00:00:00.000Z"]
+        for (const s of inputs) {
+            for (const pattern of ["YYYY-MM-DD", "YYYY-MM-DD HH:mm:ss"] as const) {
+                expect(formatDateValue(s, pattern), `${s} / ${pattern}`).toBe(referenceFormatDateValue(s, pattern))
+            }
+        }
+    })
+
+    it("1000 年未満は旧実装 (年ゼロ詰めなし) から意図的に乖離し、ISO 準拠の 4 桁ゼロ詰めで出力する", () => {
+        // 旧 Intl 実装は "202-08-10" を返す。新実装はより正しい "0202-08-10" に固定する
+        // (仕様 02 §8.1 に明示した意図的乖離。業務ドメイン 1900-2100 年域の等価性とは独立)
+        const ancient = new Date(202, 7, 10, 1, 2, 3)
+        expect(formatDateValue(ancient, "YYYY-MM-DD")).toBe("0202-08-10")
+        expect(formatDateValue(ancient, "YYYY-MM-DD HH:mm:ss")).toBe("0202-08-10 01:02:03")
+        // 負の年 (ISO 拡張表記の文字列入力のみで到達) は符号を除いた絶対値を 4 桁詰め。
+        // 素朴な String(-5).padStart(4, "0") は "00-5" と符号ごと詰める崩壊を起こすため固定する
+        const bce = new Date(Date.UTC(2000, 5, 15, 12))
+        bce.setFullYear(-5)
+        expect(formatDateValue(bce, "YYYY-MM-DD")).toMatch(/^-0005-/)
+    })
+
+    it("不変挙動: null / undefined / 空文字は null、解釈不能文字列は原文、Invalid Date は null を返す", () => {
+        expect(formatDateValue(null, "YYYY-MM-DD")).toBeNull()
+        expect(formatDateValue(undefined, "YYYY-MM-DD")).toBeNull()
+        expect(formatDateValue("", "YYYY-MM-DD HH:mm:ss")).toBeNull()
+        expect(formatDateValue("not-a-date", "YYYY-MM-DD")).toBe("not-a-date")
+        expect(formatDateValue(new Date(Number.NaN), "YYYY-MM-DD HH:mm:ss")).toBeNull()
+    })
+
+    it("性能ガード: 100,000 回の整形が 2 秒未満で完了する (Intl 逆行の煙探知機)", () => {
+        // 手組み実装は約 0.1μs/呼。旧 Intl 実装は約 66μs/呼で 100k 回 ≈ 6.6 秒かかるため、
+        // 2 秒の粗い閾値でも逆行 (toLocale* への差し戻し) を確実に検知できる
+        const d = new Date(2026, 7, 10, 15, 30, 45)
+        const startMs = performance.now()
+        for (let i = 0; i < 100_000; i++) {
+            formatDateValue(d, "YYYY-MM-DD HH:mm:ss")
+        }
+        expect(performance.now() - startMs).toBeLessThan(2000)
+    })
+})