@aiquants/daily-report 0.7.0 → 0.9.0

package/src/client/streaming/daily-report-ids-stream-client.spec.ts

@@ -0,0 +1,704 @@
+/**
+ * Resilience tests for the ids NDJSON stream client.
+ * ids NDJSON ストリームクライアントの耐障害テスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **受信済みデータはどの失敗経路でも失われない** (retryable / failed / auth-required)。
+ * - **カーソル再開 URL の契約**: `cursor_report_hub_id` は常に付与、`cursor_business_date` は
+ *   NULL 営業日領域では省略する。
+ * - **前進があった時点で連続失敗カウンタが 0 に戻る** (断続的不調で failed へ落とさない)。
+ * - **バックオフは 1s → 2s → 4s ... 上限 30s、6 連続失敗で failed** (手動 retry 待ち)。
+ * - **complete 後の refresh は phase を complete のまま保つ** (SWR: UI を後退させない)。
+ */
+import { describe, expect, it, vi } from "vitest"
+import { DailyReportIdsStreamClient, type DailyReportIdsStreamState } from "./daily-report-ids-stream-client"
+
+/** NDJSON 行群を 1 本のストリーム Response に組み立てる。chunks 単位で enqueue が割れる。 */
+const streamResponse = (chunks: string[], init: { status?: number } = {}): Response => {
+    const encoder = new TextEncoder()
+    const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+            for (const chunk of chunks) {
+                controller.enqueue(encoder.encode(chunk))
+            }
+            controller.close()
+        },
+    })
+    return new Response(stream, { status: init.status ?? 200, headers: { "Content-Type": "application/x-ndjson" } })
+}
+
+/** JSON 行の配列を改行区切りテキストへ変換する。 */
+const ndjson = (lines: unknown[]): string => lines.map((line) => `${JSON.stringify(line)}\n`).join("")
+
+/** アイテムの略記生成。 */
+const item = (reportHubId: number, businessDate: string | null = "2026-08-01") => ({ reportHubId, businessDate, sourceType: "Internal" })
+
+/** テストハーネス: 応答キュー + 手動タイマー + クライアント組み立て。 */
+const makeHarness = (factories: Array<(init: { signal: AbortSignal }) => Response | Promise<Response>>, options: { publishCoalesceMs?: number; readStallTimeoutMs?: number } = {}) => {
+    const fetchUrls: string[] = []
+    const fetchFn = vi.fn(async (input: string, init: { signal: AbortSignal }) => {
+        fetchUrls.push(input)
+        const factory = factories[Math.min(fetchUrls.length - 1, factories.length - 1)]
+        return factory(init)
+    })
+    /** 記録された待機 (ms)。waitForState が随時発火させる。 */
+    const recordedDelays: number[] = []
+    const pendingTimers: Array<() => void> = []
+    const client = new DailyReportIdsStreamClient({
+        apiBasePath: "/daily_report/api",
+        fetchFn,
+        setTimeoutFn: (handler, ms) => {
+            recordedDelays.push(ms)
+            pendingTimers.push(handler)
+            return pendingTimers.length as unknown as ReturnType<typeof setTimeout>
+        },
+        clearTimeoutFn: () => {},
+        warn: () => {},
+        // 既存テストは publish タイミングの決定性を優先して合体を無効化する
+        // (合体挙動そのものは専用テストで publishCoalesceMs を指定して検証する)
+        publishCoalesceMs: options.publishCoalesceMs ?? 0,
+        // stall ウォッチドッグも既定で無効化する (recordedDelays に混ざらないよう)。
+        // stall 検知そのものは専用テストで readStallTimeoutMs を指定して検証する
+        readStallTimeoutMs: options.readStallTimeoutMs ?? 0,
+    })
+
+    /** 状態が条件を満たすまでマイクロタスクを回し、保留タイマーを逐次発火する。 */
+    const waitForState = async (predicate: (state: DailyReportIdsStreamState) => boolean): Promise<void> => {
+        for (let i = 0; i < 200; i++) {
+            if (predicate(client.getState())) return
+            await new Promise((resolve) => setTimeout(resolve, 0))
+            const timer = pendingTimers.shift()
+            timer?.()
+        }
+        throw new Error(`state not reached: ${JSON.stringify(client.getState())}`)
+    }
+
+    return { client, fetchFn, fetchUrls, recordedDelays, pendingTimers, waitForState }
+}
+
+describe("DailyReportIdsStreamClient / 正常系", () => {
+    it("複数チャンクを蓄積して complete へ到達し、total と件数を反映する", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(3), item(2)], nextCursor: { businessDate: "2026-08-01", reportHubId: 2 }, isLast: false, total: 3 }]), ndjson([{ items: [item(1)], nextCursor: null, isLast: true }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        const state = harness.client.getState()
+        expect(state.items.map((i) => i.reportHubId)).toEqual([3, 2, 1])
+        expect(state.loadedCount).toBe(3)
+        expect(state.totalCount).toBe(3)
+        expect(state.hasCompletedOnce).toBe(true)
+        expect(state.error).toBeNull()
+        expect(harness.fetchUrls).toEqual(["/daily_report/api/ids-stream"])
+    })
+
+    it("行境界と無関係に割れたネットワークチャンクを正しく結合する", async () => {
+        const full = ndjson([{ items: [item(10), item(9)], nextCursor: null, isLast: true, total: 2 }])
+        const mid = Math.floor(full.length / 2)
+        const harness = makeHarness([() => streamResponse([full.slice(0, mid), full.slice(mid)])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([10, 9])
+    })
+
+    it("start は冪等 (二重呼び出しで接続は 1 本)", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])])
+        harness.client.start()
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+    })
+
+    it("重複アイテムは reportHubId で一意化され、内容変化は上書きされる", async () => {
+        const harness = makeHarness([
+            () =>
+                streamResponse([
+                    ndjson([
+                        { items: [item(5, "2026-08-01"), item(4)], nextCursor: { businessDate: "2026-08-01", reportHubId: 4 }, isLast: false, total: 3 },
+                        // 再開重複 (5 の内容変化) + 新規 3
+                        { items: [item(5, "2026-08-02"), item(3)], nextCursor: null, isLast: true },
+                    ]),
+                ]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        const state = harness.client.getState()
+        expect(state.loadedCount).toBe(3)
+        expect(state.items.find((i) => i.reportHubId === 5)?.businessDate).toBe("2026-08-02")
+    })
+
+    it("壊れた 1 行はスキップし、残りで完走する", async () => {
+        const harness = makeHarness([() => streamResponse([`{"broken":\n${ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])}`])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.client.getState().loadedCount).toBe(1)
+    })
+
+    it("getState のスナップショット参照は publish 間で安定している", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])])
+        const before = harness.client.getState()
+        expect(harness.client.getState()).toBe(before)
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        const after = harness.client.getState()
+        expect(after).not.toBe(before)
+        expect(harness.client.getState()).toBe(after)
+    })
+})
+
+describe("DailyReportIdsStreamClient / 再開と復旧", () => {
+    it("エラー行を受けた接続は受信済みカーソルから再開する", async () => {
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(9), item(8)], nextCursor: { businessDate: "2026-08-01", reportHubId: 8 }, isLast: false, total: 3 }, { error: "stream interrupted by server error" }])]),
+            () => streamResponse([ndjson([{ items: [item(7)], nextCursor: null, isLast: true, total: 3 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream?cursor_report_hub_id=8&cursor_business_date=2026-08-01")
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([9, 8, 7])
+    })
+
+    it("isLast 無しの終端 (サーバー再起動等) はカーソル再開する", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(9)], nextCursor: { businessDate: "2026-08-01", reportHubId: 9 }, isLast: false, total: 2 }])]), () => streamResponse([ndjson([{ items: [item(8)], nextCursor: null, isLast: true, total: 2 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchUrls[1]).toContain("cursor_report_hub_id=9")
+        expect(harness.client.getState().loadedCount).toBe(2)
+    })
+
+    it("NULL 営業日領域の再開は cursor_business_date を省略する", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(9, null)], nextCursor: { businessDate: null, reportHubId: 9 }, isLast: false, total: 2 }])]), () => streamResponse([ndjson([{ items: [item(8, null)], nextCursor: null, isLast: true, total: 2 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream?cursor_report_hub_id=9")
+    })
+
+    it("HTTP 失敗は指数バックオフし、6 連続失敗で failed へ落ちる (データは保持)", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(9)], nextCursor: { businessDate: "2026-08-01", reportHubId: 9 }, isLast: false, total: 5 }])]), () => new Response("err", { status: 500 })])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "failed")
+
+        // 初回接続は前進ありだが isLast 無し終端なので失敗 1 回目として数え、その後 500 が 5 連続で計 6
+        expect(harness.fetchFn).toHaveBeenCalledTimes(6)
+        expect(harness.recordedDelays).toEqual([1000, 2000, 4000, 8000, 16000])
+        const state = harness.client.getState()
+        expect(state.items.map((i) => i.reportHubId)).toEqual([9])
+        expect(state.error?.message).toContain("HTTP 500")
+    })
+
+    it("前進があると連続失敗カウンタが 0 へ戻る", async () => {
+        const harness = makeHarness([
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            // 前進あり (ただし未完) → カウンタリセット
+            () => streamResponse([ndjson([{ items: [item(9)], nextCursor: { businessDate: "2026-08-01", reportHubId: 9 }, isLast: false, total: 2 }])]),
+            () => streamResponse([ndjson([{ items: [item(8)], nextCursor: null, isLast: true, total: 2 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 1000 (失敗1) → 2000 (失敗2) → 前進でリセット → 1000 (失敗1 相当)
+        expect(harness.recordedDelays).toEqual([1000, 2000, 1000])
+    })
+
+    it("401 は auth-required で停止し、リトライしない", async () => {
+        const harness = makeHarness([() => new Response("{}", { status: 401 })])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "auth-required")
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+        expect(harness.recordedDelays).toEqual([])
+    })
+
+    it("retry は failed からのみ再開し、それ以外では何もしない", async () => {
+        const harness = makeHarness([
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "failed")
+        expect(harness.fetchFn).toHaveBeenCalledTimes(6)
+
+        harness.client.retry()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchFn).toHaveBeenCalledTimes(7)
+
+        // complete 中の retry は無視される
+        harness.client.retry()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.fetchFn).toHaveBeenCalledTimes(7)
+    })
+})
+
+describe("DailyReportIdsStreamClient / SWR 再検証", () => {
+    it("refresh は complete を保ったまま先頭から再読込し、差分を上書きする", async () => {
+        const phases: Array<{ phase: string; isRevalidating: boolean }> = []
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(2, "2026-08-01"), item(1)], nextCursor: null, isLast: true, total: 2 }])]),
+            () => streamResponse([ndjson([{ items: [item(3), item(2, "2026-08-02"), item(1)], nextCursor: null, isLast: true, total: 3 }])]),
+        ])
+        harness.client.subscribe(() => {
+            const s = harness.client.getState()
+            phases.push({ phase: s.phase, isRevalidating: s.isRevalidating })
+        })
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete" && s.loadedCount === 2)
+
+        harness.client.refresh()
+        await harness.waitForState((s) => s.loadedCount === 3 && !s.isRevalidating)
+
+        const state = harness.client.getState()
+        expect(state.phase).toBe("complete")
+        expect(state.totalCount).toBe(3)
+        expect(state.items.find((i) => i.reportHubId === 2)?.businessDate).toBe("2026-08-02")
+        // 再検証 URL はカーソル無しの先頭から
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream")
+        // 再検証中に streaming/retrying へ後退した publish が存在しない
+        expect(phases.filter((p) => p.isRevalidating).every((p) => p.phase === "complete")).toBe(true)
+    })
+
+    it("refresh({forceRefresh}) はサーバーキャッシュバイパスのクエリを付ける", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]), () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        harness.client.refresh({ forceRefresh: true })
+        await harness.waitForState((s) => !s.isRevalidating)
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream?forceRefresh=true")
+    })
+
+    it("streaming 中の refresh は無視される", async () => {
+        let release: (() => void) | null = null
+        const harness = makeHarness([
+            (init) =>
+                new Promise<Response>((resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                    release = () => resolve(streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]))
+                }),
+        ])
+        harness.client.start()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+        release?.()
+        await harness.waitForState((s) => s.phase === "complete")
+    })
+})
+
+describe("DailyReportIdsStreamClient / レビュー回帰 (確定所見の再発防止)", () => {
+    it("total 単独の変化でも購読者へ通知される (無通知のスナップショット置換をしない)", async () => {
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+            // 同一アイテム (内容変化なし) だが total だけ変わる再検証応答
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 5 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        let notified = 0
+        harness.client.subscribe(() => {
+            notified += 1
+        })
+        harness.client.refresh()
+        await harness.waitForState((s) => s.totalCount === 5 && !s.isRevalidating)
+        expect(notified).toBeGreaterThan(0)
+    })
+
+    it("再検証の完走はサーバーから消えた行を剪定する (削除日報の亡霊を残さない)", async () => {
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(3), item(2), item(1)], nextCursor: null, isLast: true, total: 3 }])]),
+            // 2 が削除された世界の再検証応答
+            () => streamResponse([ndjson([{ items: [item(3), item(1)], nextCursor: null, isLast: true, total: 2 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.loadedCount === 3)
+        harness.client.refresh()
+        await harness.waitForState((s) => s.loadedCount === 2 && !s.isRevalidating)
+        const state = harness.client.getState()
+        expect(state.items.map((i) => i.reportHubId)).toEqual([3, 1])
+        expect(state.totalCount).toBe(2)
+    })
+
+    it("forceRefresh はループ内の全リトライで維持される (サーバー未到達の失敗で脱落しない)", async () => {
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+            // 強制再検証の初回試行はネットワーク断で失敗
+            () => Promise.reject(new Error("network down")),
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        harness.client.refresh({ forceRefresh: true })
+        await harness.waitForState((s) => !s.isRevalidating)
+        expect(harness.fetchUrls[1]).toContain("forceRefresh=true")
+        expect(harness.fetchUrls[2]).toContain("forceRefresh=true")
+    })
+
+    it("failed からの refresh({forceRefresh}) はフラグを失わない", async () => {
+        const harness = makeHarness([
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "failed")
+        harness.client.refresh({ forceRefresh: true })
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.fetchUrls[6]).toContain("forceRefresh=true")
+    })
+
+    it("バックオフ待機中に新しい refresh が始まっても後続ループのタイマーは消されない (追い越し競合)", async () => {
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+            () => new Response("err", { status: 500 }),
+            () => new Response("err", { status: 500 }),
+            () => streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        // 再検証 #1 → 500 → バックオフ待機に入る
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.recordedDelays.length).toBeGreaterThan(0)
+
+        // 待機中に再検証 #2 を重ねる (旧ループは即時解放され、新ループが独立に完走できること)
+        harness.client.refresh()
+        await harness.waitForState((s) => s.loadedCount === 2 && !s.isRevalidating)
+        expect(harness.client.getState().phase).toBe("complete")
+    })
+
+    it("契約外の営業日を持つ nextCursor は採用せず、直前の正当な位置から再開する", async () => {
+        const harness = makeHarness([
+            // 年 3 桁の混入データ: このカーソルを id 単独で送ると NULL 領域へスキップして欠落する
+            () => streamResponse([ndjson([{ items: [item(9, "999-01-01")], nextCursor: { businessDate: "999-01-01", reportHubId: 9 }, isLast: false, total: 2 }])]),
+            () => streamResponse([ndjson([{ items: [item(8, "999-01-01")], nextCursor: null, isLast: true, total: 2 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 再開 URL にカーソルが載らない (先頭から読み直し、Map の重複排除が吸収する)
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream")
+        expect(harness.client.getState().loadedCount).toBe(2)
+    })
+
+    it("完走の publish が completedAt を刻み、再検証の諦めでは据え置く", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]), () => new Response("err", { status: 500 })])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        const completedAt = harness.client.getState().completedAt
+        expect(completedAt).not.toBeNull()
+
+        // 再検証は 500 連発で力尽きる — completedAt は完走時のまま
+        harness.client.refresh()
+        await harness.waitForState((s) => !s.isRevalidating && s.error !== null)
+        expect(harness.client.getState().phase).toBe("complete")
+        expect(harness.client.getState().completedAt).toBe(completedAt)
+    })
+})
+
+describe("DailyReportIdsStreamClient / 再検証多重起動防止と外部ミューテーション", () => {
+    it("走行中の再検証がある間の refresh は無視される (中断・再開始しない)", async () => {
+        let release: (() => void) | null = null
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+            (init) =>
+                new Promise<Response>((resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                    release = () => resolve(streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])]))
+                }),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.client.getState().isRevalidating).toBe(true)
+
+        // 再訪の多重 ensure 相当: 走行中の再検証を中断してはならない
+        harness.client.refresh()
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.fetchFn).toHaveBeenCalledTimes(2)
+
+        release?.()
+        await harness.waitForState((s) => s.loadedCount === 2 && !s.isRevalidating)
+    })
+
+    it("applyExternalUpsert は常駐データへ反映され、走査中の観測集合にも刻まれて剪定を免れる", async () => {
+        let release: (() => void) | null = null
+        const harness = makeHarness([
+            (init) =>
+                new Promise<Response>((resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                    // サーバー一覧には 3,2 のみ (99 は走査中に SSE で作成された想定)
+                    release = () => resolve(streamResponse([ndjson([{ items: [item(3), item(2)], nextCursor: null, isLast: true, total: 2 }])]))
+                }),
+        ])
+        harness.client.start()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+
+        // 走査中の外部 upsert (作成直後の SSE 相当)
+        harness.client.applyExternalUpsert({ reportHubId: 99, businessDate: "2026-08-04" })
+        expect(harness.client.getState().items.some((i) => i.reportHubId === 99)).toBe(true)
+
+        release?.()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 完走剪定でも 99 は「生きていると分かっている」ため残る
+        expect(harness.client.getState().items.some((i) => i.reportHubId === 99)).toBe(true)
+    })
+
+    it("走査外の外部 upsert は次の再検証完走で (サーバーに無ければ) 剪定される", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]), () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        harness.client.applyExternalUpsert({ reportHubId: 99, businessDate: "2026-08-04" })
+        expect(harness.client.getState().loadedCount).toBe(2)
+
+        harness.client.refresh()
+        await harness.waitForState((s) => s.loadedCount === 1 && !s.isRevalidating)
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([1])
+    })
+
+    it("applyExternalRemoval は常駐データから即時除去し、購読者へ通知する", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.loadedCount === 2)
+
+        let notified = 0
+        harness.client.subscribe(() => {
+            notified += 1
+        })
+        harness.client.applyExternalRemoval(2)
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([1])
+        expect(notified).toBeGreaterThan(0)
+
+        // 既に無い ID の除去は通知しない
+        const before = notified
+        harness.client.applyExternalRemoval(2)
+        expect(notified).toBe(before)
+    })
+
+    it("外部 upsert は sourceType 未指定のとき既存値を保持し、同一内容の再適用では通知しない", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        let notified = 0
+        harness.client.subscribe(() => {
+            notified += 1
+        })
+        // 同一 businessDate + sourceType 未指定: 既存 sourceType (Internal) を保持し、変化なし
+        harness.client.applyExternalUpsert({ reportHubId: 1, businessDate: "2026-08-01" })
+        expect(notified).toBe(0)
+        expect(harness.client.getState().items[0].sourceType).toBe("Internal")
+
+        // businessDate 変化は反映 + 通知
+        harness.client.applyExternalUpsert({ reportHubId: 1, businessDate: "2026-08-02" })
+        expect(notified).toBeGreaterThan(0)
+        expect(harness.client.getState().items[0]).toEqual({ reportHubId: 1, businessDate: "2026-08-02", sourceType: "Internal" })
+    })
+})
+
+describe("DailyReportIdsStreamClient / 第 3 ラウンド回帰 (トゥームストーンと forceRefresh 持ち越し)", () => {
+    it("走査中の外部削除は、同一スナップショット後続チャンクの再配送でも蘇らない", async () => {
+        let release: (() => void) | null = null
+        const harness = makeHarness([
+            (init) =>
+                new Promise<Response>((resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                    // チャンク 1: [5,4] / チャンク 2 (削除前スナップショットの再配送): [3] + 5 を再配送
+                    release = () => resolve(streamResponse([ndjson([{ items: [item(5), item(4)], nextCursor: { businessDate: "2026-08-01", reportHubId: 4 }, isLast: false, total: 4 }]), ndjson([{ items: [item(5), item(3)], nextCursor: null, isLast: true }])]))
+                }),
+        ])
+        harness.client.start()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+
+        // 走査開始直後に 5 が外部削除される
+        harness.client.applyExternalRemoval(5)
+        release?.()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 再配送された 5 は受け入れられず、完走後も存在しない
+        expect(
+            harness.client
+                .getState()
+                .items.map((i) => i.reportHubId)
+                .sort(),
+        ).toEqual([3, 4])
+    })
+
+    it("トゥームストーンは新しい走査の開始でクリアされる (削除コミット後のスナップショットが権威)", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])]), () => streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])])])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        harness.client.applyExternalRemoval(2)
+        expect(harness.client.getState().loadedCount).toBe(1)
+
+        // 新しい走査 (サーバーの新スナップショット) が 2 を含むなら、それが権威として復元される
+        harness.client.refresh()
+        await harness.waitForState((s) => s.loadedCount === 2 && !s.isRevalidating)
+        expect(
+            harness.client
+                .getState()
+                .items.map((i) => i.reportHubId)
+                .sort(),
+        ).toEqual([1, 2])
+    })
+
+    it("走行中の再検証中に届いた forceRefresh 要求は捨てられず、完走後に連結実行される", async () => {
+        let release: (() => void) | null = null
+        const harness = makeHarness([
+            () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]),
+            (init) =>
+                new Promise<Response>((resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                    release = () => resolve(streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])]))
+                }),
+            () => streamResponse([ndjson([{ items: [item(2), item(1)], nextCursor: null, isLast: true, total: 2 }])]),
+        ])
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        // 再検証 #1 (通常) が走行中に、キャッシュクリア (forceRefresh) 要求が届く
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        harness.client.refresh({ forceRefresh: true })
+        expect(harness.fetchFn).toHaveBeenCalledTimes(2)
+
+        // #1 完走後、持ち越された forceRefresh 付き再検証が自動連結される
+        release?.()
+        await harness.waitForState((s) => s.loadedCount === 2 && !s.isRevalidating)
+        expect(harness.fetchFn).toHaveBeenCalledTimes(3)
+        expect(harness.fetchUrls[2]).toContain("forceRefresh=true")
+    })
+})
+
+describe("DailyReportIdsStreamClient / publish 合体スロットル", () => {
+    it("先頭チャンクは即時 publish され、窓内に密集した後続チャンクは 1 回へ合体する", async () => {
+        const harness = makeHarness(
+            [
+                () =>
+                    streamResponse([
+                        // 3 つのネットワーク read に分けて届く 3 チャンク (密集到着の再現)
+                        ndjson([{ items: [item(9)], nextCursor: { businessDate: "2026-08-01", reportHubId: 9 }, isLast: false, total: 3 }]),
+                        ndjson([{ items: [item(8)], nextCursor: { businessDate: "2026-08-01", reportHubId: 8 }, isLast: false }]),
+                        ndjson([{ items: [item(7)], nextCursor: null, isLast: true }]),
+                    ]),
+            ],
+            { publishCoalesceMs: 50 },
+        )
+        const itemCountsPerPublish: number[] = []
+        harness.client.subscribe(() => {
+            itemCountsPerPublish.push(harness.client.getState().loadedCount)
+        })
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        // 先頭チャンク (1 件) は即時、密集した残りは合体または完走 publish で届く。
+        // 「チャンクごとに 3 回のアイテム publish」にはならない
+        expect(itemCountsPerPublish[0]).toBeLessThanOrEqual(2)
+        expect(harness.client.getState().loadedCount).toBe(3)
+        // 合体窓のトレーリングタイマー (50ms 以下) が記録されるか、完走 publish が吸収している
+        expect(harness.recordedDelays.every((ms) => ms <= 50)).toBe(true)
+    })
+
+    it("完走 publish は保留中のトレーリング publish を吸収して全量を運ぶ", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(2)], nextCursor: { businessDate: "2026-08-01", reportHubId: 2 }, isLast: false, total: 2 }]), ndjson([{ items: [item(1)], nextCursor: null, isLast: true }])])], { publishCoalesceMs: 5_000 })
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 巨大な合体窓でも完走時には全量が state に載っている (トレーリング待ちで欠けない)
+        expect(harness.client.getState().loadedCount).toBe(2)
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([2, 1])
+    })
+})
+
+describe("DailyReportIdsStreamClient / 破棄", () => {
+    it("dispose は進行中の接続を中断し、以後の活動を止める", async () => {
+        const harness = makeHarness([
+            (init) =>
+                new Promise<Response>((_resolve, reject) => {
+                    init.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
+                }),
+        ])
+        harness.client.start()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        harness.client.dispose()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+        // dispose 後は start/retry/refresh のいずれも接続を作らない
+        harness.client.start()
+        harness.client.retry()
+        harness.client.refresh()
+        await new Promise((resolve) => setTimeout(resolve, 0))
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+    })
+})
+
+describe("DailyReportIdsStreamClient / stall ウォッチドッグ", () => {
+    /** 初期チャンクを流した後、close せず read を永久保留にする (half-open 接続の模擬)。 */
+    const hangingResponse = (chunks: string[]): Response => {
+        const encoder = new TextEncoder()
+        const stream = new ReadableStream<Uint8Array>({
+            start(controller) {
+                for (const chunk of chunks) {
+                    controller.enqueue(encoder.encode(chunk))
+                }
+                // 意図的に close しない → 後続 read は解決も reject もしない
+            },
+        })
+        return new Response(stream, { status: 200, headers: { "Content-Type": "application/x-ndjson" } })
+    }
+
+    it("無音が続く half-open 接続を検知し、カーソル再開で自己回復する", async () => {
+        const harness = makeHarness(
+            [
+                // 1 本目: 先頭ページを届けた後ハング (isLast 無し・close 無し)
+                () => hangingResponse([ndjson([{ items: [item(2)], nextCursor: { businessDate: "2026-08-01", reportHubId: 2 }, isLast: false, total: 2 }])]),
+                // 2 本目 (再開): 残りを届けて complete
+                () => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true }])]),
+            ],
+            { readStallTimeoutMs: 30_000 },
+        )
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+
+        const state = harness.client.getState()
+        // 受信済みデータは保持され、再開で全量に到達する
+        expect(state.items.map((i) => i.reportHubId)).toEqual([2, 1])
+        expect(state.error).toBeNull()
+        // 2 本目はカーソル再開 (先頭ページの nextCursor を採用)
+        expect(harness.fetchFn).toHaveBeenCalledTimes(2)
+        expect(harness.fetchUrls[1]).toBe("/daily_report/api/ids-stream?cursor_report_hub_id=2&cursor_business_date=2026-08-01")
+        // stall タイマー (30s) が実際に登録されている
+        expect(harness.recordedDelays).toContain(30_000)
+    })
+
+    it("readStallTimeoutMs=0 では stall タイマーを張らない (正常系は素の read)", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(1)], nextCursor: null, isLast: true, total: 1 }])])], { readStallTimeoutMs: 0 })
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        expect(harness.client.getState().loadedCount).toBe(1)
+        // 無効化時は read 監視タイマーを一切登録しない
+        expect(harness.recordedDelays).not.toContain(30_000)
+    })
+
+    it("データが流れている間は誤検知しない (read 勝利でタイマーは解除される)", async () => {
+        const harness = makeHarness([() => streamResponse([ndjson([{ items: [item(3), item(2)], nextCursor: { businessDate: "2026-08-01", reportHubId: 2 }, isLast: false, total: 3 }]), ndjson([{ items: [item(1)], nextCursor: null, isLast: true }])])], {
+            readStallTimeoutMs: 30_000,
+        })
+        harness.client.start()
+        await harness.waitForState((s) => s.phase === "complete")
+        // 正常完走: 再接続は発生しない (stall 誤検知なし)
+        expect(harness.fetchFn).toHaveBeenCalledTimes(1)
+        expect(harness.client.getState().items.map((i) => i.reportHubId)).toEqual([3, 2, 1])
+    })
+})