@aiquants/daily-report 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/daily-report",
-  "version": "0.9.0",
+  "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"

package/src/client/contexts/daily-report-action-context.spec.tsx

@@ -276,3 +276,61 @@ describe("initialItems の既定値 (無限レンダー防止)", () => {
         expect(contextRef.current?.items).toEqual([])
     })
 })
+
+describe("SSE 自動接続の遅延 (初回描画へ接続枠を譲る)", () => {
+    // isSseEnabled は render 時点で読む (effect 経由の contextRef はタイマー flush と 1 ティックずれる)
+    const renderState: { current: DailyReportActionContextType | null } = { current: null }
+    const RenderCapture = () => {
+        renderState.current = useDailyReportActionContext()
+        return null
+    }
+
+    it("初期は未接続で、遅延後に自動接続する", async () => {
+        vi.useFakeTimers()
+        try {
+            // セッションは張らない (このテストは SSE 遅延だけを見る)。userId ありで自動接続対象
+            render(
+                <DailyReportActionProvider user={{ id: "a", displayName: "User A" }} userId="ENC_A">
+                    <RenderCapture />
+                </DailyReportActionProvider>,
+            )
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(0)
+            })
+            // 初回描画時点では未接続 (HTTP/1.1 の接続枠を初回の中身フェッチへ譲る)
+            expect(renderState.current?.isSseEnabled).toBe(false)
+            // 遅延経過で自動接続する
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(1000)
+            })
+            expect(renderState.current?.isSseEnabled).toBe(true)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+
+    it("手動トグルは自動接続タイマーに上書きされない", async () => {
+        vi.useFakeTimers()
+        try {
+            render(
+                <DailyReportActionProvider user={{ id: "a", displayName: "User A" }} userId="ENC_A">
+                    <RenderCapture />
+                </DailyReportActionProvider>,
+            )
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(0)
+            })
+            // ユーザーが手動で ON → OFF した後、遅延タイマーが発火しても手動 OFF を尊重する
+            act(() => renderState.current?.toggleSse())
+            expect(renderState.current?.isSseEnabled).toBe(true)
+            act(() => renderState.current?.toggleSse())
+            expect(renderState.current?.isSseEnabled).toBe(false)
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(1000)
+            })
+            expect(renderState.current?.isSseEnabled).toBe(false)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+})

package/src/client/contexts/daily-report-action-context.tsx

@@ -24,6 +24,7 @@ import {
 } from "../hooks/use-daily-report"
 import { useDailyReportSseConnection } from "../hooks/use-daily-report-sse-connection"
 import { getDailyReportIdsStreamSessionUserKey, refreshDailyReportIdsStream, removeDailyReportIdsStreamItem, upsertDailyReportIdsStreamItem, useDailyReportIdsStream } from "../streaming/daily-report-ids-stream-session"
+import { SSE_INITIAL_CONNECT_DEFER_MS } from "../utils/constants"
 import { useDailyReportErrorSurface } from "./daily-report-error-context"
 
 const logger = createLogger(LogLevel.INFO, "daily-report-action-context")
@@ -181,7 +182,10 @@ export const DailyReportActionProvider = ({ children, user, initialItems = EMPTY
     const resolvedIdMap = useRef<Map<number, number>>(new Map())
     const [version, setVersion] = useState(0)
     const [items, setItems] = useState<DailyReportItem[]>(initialItems)
-    const [isSseEnabled, setIsSseEnabled] = useState(!!userId)
+    // SSE は初回描画とその最初の中身フェッチに接続枠を譲るため、少し遅らせて自動接続する
+    // (HTTP/1.1 の 6 接続のうち 1 枠を初回描画へ回す)。手動トグル済みなら自動接続しない
+    const [isSseEnabled, setIsSseEnabled] = useState(false)
+    const hasManualSseToggleRef = useRef(false)
     const pendingAddPromises = useRef<Map<number, Promise<number>>>(new Map())
     const manuallyTrackingIds = useRef<Set<number>>(new Set())
     /** 削除済み ID を記録し、マージロジックでの復活を防止する */
@@ -369,9 +373,27 @@ export const DailyReportActionProvider = ({ children, user, initialItems = EMPTY
     // 未登録ユーザーは SSE を有効化できない
     const toggleSse = () => {
         if (!userId) return
+        // 手動操作後は自動接続タイマーに上書きさせない
+        hasManualSseToggleRef.current = true
         setIsSseEnabled((prev) => !prev)
     }
 
+    /**
+     * Defers the initial SSE auto-connect until just after first paint.
+     * 初回 SSE 自動接続を初回描画直後まで遅らせる副作用。
+     *
+     * 依存配列: userId (ユーザーごとに provider が key リマウントされるため、切替で張り直す)。
+     * クリーンアップ: タイマー解除 (アンマウント/再マウントでのリークと二重発火を防ぐ)。
+     */
+    useEffect(() => {
+        if (!userId) return
+        const timer = setTimeout(() => {
+            // 手動でトグルされていなければ自動接続する
+            if (!hasManualSseToggleRef.current) setIsSseEnabled(true)
+        }, SSE_INITIAL_CONNECT_DEFER_MS)
+        return () => clearTimeout(timer)
+    }, [userId])
+
     /**
      * Remove a stale item from the list as a safety net.
      * フェッチ後にレポートが見つからなかった場合の安全弁としてアイテムを除去する。

package/src/client/hooks/use-daily-report.spec.ts

@@ -201,3 +201,60 @@ describe("getGlobal behavior (window グローバル変数の読み取り)", ()
         expect(mod.getCachedReport(1)).toBeNull()
     })
 })
+
+describe("useDailyReportDetail の初回フェッチ (デバウンス適用範囲)", () => {
+    let mod: typeof import("./use-daily-report")
+
+    beforeEach(async () => {
+        vi.resetModules()
+        mod = await import("./use-daily-report")
+        vi.useFakeTimers()
+    })
+
+    afterEach(() => {
+        vi.useRealTimers()
+        vi.unstubAllGlobals()
+    })
+
+    /** business-date 応答を 1 件返す fetch スタブ。呼び出し回数を記録する。 */
+    const stubFetch = () => {
+        const calls: string[] = []
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: RequestInfo | URL) => {
+                calls.push(String(input))
+                return new Response(JSON.stringify({ reports: [makeMockReport({ reportHubId: 7, date: "2026-01-01" })] }), { status: 200, headers: { "Content-Type": "application/json" } })
+            }),
+        )
+        return calls
+    }
+
+    it("未キャッシュの初回は即フェッチする (120ms のデバウンスを掛けない)", async () => {
+        const { renderHook, act } = await import("@testing-library/react")
+        const calls = stubFetch()
+        renderHook(() => mod.useDailyReportDetail(7, "2026-01-01"))
+        // タイマーを進めずマイクロタスクだけ流す → 即時 (0ms) 発火の検証
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(0)
+        })
+        expect(calls.length).toBe(1)
+        expect(calls[0]).toContain("business-date?businessDate=2026-01-01")
+    })
+
+    it("キャッシュ済み (stale) の再取得はデバウンスされる", async () => {
+        const { renderHook, act } = await import("@testing-library/react")
+        const calls = stubFetch()
+        // 期限切れのキャッシュを用意 → 表示は即、再取得はデバウンス対象
+        mod.writeCache(makeMockReport({ reportHubId: 7, date: "2026-01-01" }), Date.now() - 1)
+        renderHook(() => mod.useDailyReportDetail(7, "2026-01-01"))
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(0)
+        })
+        // 0ms 時点では発火しない (スクロール churn 吸収のためのデバウンス)
+        expect(calls.length).toBe(0)
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(120)
+        })
+        expect(calls.length).toBe(1)
+    })
+})

package/src/client/hooks/use-daily-report.ts

@@ -7,6 +7,7 @@ import { normalizeBusinessDateKey } from "../../shared/business-date"
 import { createLogger, LogLevel } from "../../shared/logger"
 import type { DailyReportDetail } from "../../shared/types"
 import { useDailyReportConfig } from "../config-context"
+import { DAILY_REPORT_FETCH_DEBOUNCE_MS } from "../utils/constants"
 
 const logger = createLogger(LogLevel.INFO, "use-daily-report")
 
@@ -22,7 +23,6 @@ const getGlobal = (k: string, d: number): number => {
 }
 const TTL = getGlobal("__DAILY_REPORT_CACHE_TTL__", 300_000)
 const REVIVE_MS = getGlobal("__DAILY_REPORT_CACHE_REVIVE_MS__", 60_000)
-const FETCH_DEBOUNCE_MS = 120
 
 // --- Cache Store (Centralized State) ---
 type CacheEntry<T> = { data: T; expiresAt: number }
@@ -430,6 +430,11 @@ export const useDailyReportDetail = (reportHubId: number, businessDate: string |
         setIsLoading(!cached)
         setIsRefetching(true)
 
+        // 未キャッシュ (骨組み表示中) の初回取得は即時に走らせる。デバウンスはスクロール連打の
+        // 無駄取りを抑える目的なので、スクロール churn の無い初回に効かせると純粋な遅延になる。
+        // キャッシュ済み (内容表示中) の stale 再取得だけデバウンスして churn を吸収する
+        const debounceMs = cached ? DAILY_REPORT_FETCH_DEBOUNCE_MS : 0
+
         const timer = setTimeout(async () => {
             if (reqRef.current.token !== token) return
             try {
@@ -453,7 +458,7 @@ export const useDailyReportDetail = (reportHubId: number, businessDate: string |
                     setIsRefetching(false)
                 }
             }
-        }, FETCH_DEBOUNCE_MS)
+        }, debounceMs)
 
         return () => clearTimeout(timer)
     }, [reportHubId, businessDate, apiBasePath])

package/src/client/utils/constants.ts

@@ -6,7 +6,17 @@ import type { DailyReportDetailResource } from "../hooks/use-daily-report"
  * Shared constants for Daily Report data fetching parameters.
  * 日報データ取得で利用する共通パラメーター。
  */
-export const DAILY_REPORT_FETCH_DEBOUNCE_MS = 180
+export const DAILY_REPORT_FETCH_DEBOUNCE_MS = 120
+
+/**
+ * Delay before the provider auto-connects SSE, freeing a browser connection slot for first paint.
+ * SSE を自動接続するまでの遅延。初回描画とその中身フェッチへ接続枠を譲るための猶予。
+ *
+ * HTTP/1.1 のオリジン当たり 6 接続のうち、ids ストリームと SSE で 2 枠を常時占有する。
+ * SSE 接続を初回描画直後まで遅らせ、その 1 枠を初回の中身フェッチ (`/business-date`) に回す。
+ * リアルタイム更新の初動がこの分だけ遅れるが、その間の状態はストリーム / SWR が担保する。
+ */
+export const SSE_INITIAL_CONNECT_DEFER_MS = 1000
 
 export const DEFAULT_ITEM_HEIGHT = 160
 export const ITEM_VERTICAL_PADDING = 6

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