@aiquants/daily-report 0.6.2 → 0.8.0

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

@@ -0,0 +1,599 @@
+/**
+ * Resilient NDJSON stream client for the daily-report ids feed (React-free).
+ * 日報 ID 一覧 NDJSON フィードの耐障害ストリームクライアント (React 非依存)。
+ *
+ * fetch + ReadableStream で `{apiBasePath}/ids-stream` を読み、チャンク到着ごとに
+ * 蓄積スナップショットを publish する。切断・サーバーエラー行・未完終端は
+ * カーソル再開付きの指数バックオフで自己回復し、受信済みデータは常に保持する。
+ * React へは `subscribe` / `getState` (安定参照スナップショット) だけを公開し、
+ * `useSyncExternalStore` でそのまま束縛できる形にする。
+ */
+import { type DailyReportIdsStreamCursor, type DailyReportIdsStreamLine, isIdsStreamChunkLine } from "../../shared/ids-stream"
+import type { DailyReportItem } from "../../shared/types"
+
+/** ストリームのライフサイクル局面。 */
+export type DailyReportIdsStreamPhase = "idle" | "streaming" | "retrying" | "complete" | "failed" | "auth-required"
+
+/** publish されるスナップショット。publish 間で参照が安定している。 */
+export type DailyReportIdsStreamState = {
+    /** 受信済みアイテム (reportHubId で重複排除済み)。 */
+    items: DailyReportItem[]
+    /** 一意アイテム件数 (`items.length` と同値。表示用の別名)。 */
+    loadedCount: number
+    /** サーバー申告の全体件数。先頭行未着なら null。 */
+    totalCount: number | null
+    /** ライフサイクル局面。 */
+    phase: DailyReportIdsStreamPhase
+    /** complete 後のバックグラウンド再検証が走っているか。 */
+    isRevalidating: boolean
+    /** 一度でも完走したか (再検証中の UI 判定に使う)。 */
+    hasCompletedOnce: boolean
+    /**
+     * 直近の「実際の完走」時刻 (未完走は null)。鮮度判定 (SWR 窓) の唯一の根拠。
+     * 完走の publish でのみ更新される — 再検証の諦めなど phase が complete のままの
+     * publish で更新すると、古いデータが新鮮扱いされ再検証が永久に走らなくなる。
+     */
+    completedAt: number | null
+    /** 直近の失敗 (成功で null に戻る)。 */
+    error: Error | null
+}
+
+/** 1 接続試行の結末。 */
+type StreamAttemptOutcome = { kind: "complete" } | { kind: "aborted" } | { kind: "auth-required" } | { kind: "retryable"; error: Error }
+
+/** テスト注入用の依存一式。 */
+export type DailyReportIdsStreamClientOptions = {
+    /** API ベースパス (既定 `/daily_report/api`)。 */
+    apiBasePath?: string
+    /** fetch 実装 (既定 globalThis.fetch)。 */
+    fetchFn?: (input: string, init: { signal: AbortSignal; headers: Record<string, string>; cache: RequestCache }) => Promise<Response>
+    /** タイマー実装 (既定 setTimeout / clearTimeout)。 */
+    setTimeoutFn?: (handler: () => void, ms: number) => ReturnType<typeof setTimeout>
+    clearTimeoutFn?: (id: ReturnType<typeof setTimeout>) => void
+    /** 警告ロガー (既定 console.warn)。 */
+    warn?: (...args: unknown[]) => void
+    /**
+     * チャンク由来 publish の合体窓 (ms)。0 で無効 (毎チャンク即時 publish)。
+     * 高速回線ではネットワーク read が密集し、publish ごとに全件ソート + 全行再レンダーが
+     * 走るため、先頭は即時 (初回描画優先)・後続は窓内で合体するスロットルを掛ける。
+     * 完走 publish と外部ミューテーション (ユーザー操作の即時フィードバック) は対象外。
+     */
+    publishCoalesceMs?: number
+}
+
+/** チャンク由来 publish の既定合体窓 (ms)。 */
+const DEFAULT_PUBLISH_COALESCE_MS = 50
+
+/** 初回リトライ遅延。 */
+const INITIAL_RETRY_DELAY_MS = 1_000
+
+/** リトライ遅延の上限。 */
+const MAX_RETRY_DELAY_MS = 30_000
+
+/** 連続失敗の上限。到達で failed へ落ち、手動 retry 待ちになる。 */
+const MAX_CONSECUTIVE_FAILURES = 6
+
+/** 既定の API ベースパス (config-context の既定と一致させる)。 */
+const DEFAULT_API_BASE_PATH = "/daily_report/api"
+
+/** 再開カーソルとして採用する営業日の唯一の形式 (サーバー側の検証契約と一致)。 */
+const CURSOR_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * NDJSON ids stream client with dedupe, cursor resume, and exponential backoff.
+ * 重複排除・カーソル再開・指数バックオフを備えた NDJSON ids ストリームクライアント。
+ */
+export class DailyReportIdsStreamClient {
+    private readonly apiBasePath: string
+    private readonly fetchFn: NonNullable<DailyReportIdsStreamClientOptions["fetchFn"]>
+    private readonly setTimeoutFn: NonNullable<DailyReportIdsStreamClientOptions["setTimeoutFn"]>
+    private readonly clearTimeoutFn: NonNullable<DailyReportIdsStreamClientOptions["clearTimeoutFn"]>
+    private readonly warn: NonNullable<DailyReportIdsStreamClientOptions["warn"]>
+
+    /** reportHubId → アイテム。挿入順を保ち、再開の重複到着を吸収する。 */
+    private readonly itemMap = new Map<number, DailyReportItem>()
+    private readonly listeners = new Set<() => void>()
+
+    private state: DailyReportIdsStreamState = {
+        items: [],
+        loadedCount: 0,
+        totalCount: null,
+        phase: "idle",
+        isRevalidating: false,
+        hasCompletedOnce: false,
+        completedAt: null,
+        error: null,
+    }
+
+    private lastCursor: DailyReportIdsStreamCursor | null = null
+    private consecutiveFailures = 0
+    private started = false
+    private disposed = false
+    /** 実行中ループの世代。refresh/dispose で進め、旧ループの続行を無効化する。 */
+    private loopGeneration = 0
+    private activeAbortController: AbortController | null = null
+    /**
+     * 先頭 (cursor 無し) から始まった走査で観測した ID の集合。
+     * 完走時にこの集合へ含まれない Map エントリを剪定し、サーバー側で削除された
+     * 日報がモジュール常駐データに永久残留するのを防ぐ。途中失敗のカーソル再開は
+     * 同じ走査の続きなので集合を引き継ぐ (全区間の和 = サーバーの全量)。
+     */
+    private activeSeenIds: Set<number> | null = null
+    /**
+     * 外部削除のトゥームストーン。サーバーは配列全体を先に確定させてから送出するため、
+     * 走査中に届いた削除の後、同じ削除前スナップショットの後続チャンクが同 ID を
+     * 再配送してくる。これを吸収せずに素通しすると、削除済み日報が Map へ戻り
+     * 完走剪定も免れてしまう (観測集合に再記録されるため)。新しい走査の開始
+     * (削除コミット後のスナップショット) でクリアする。
+     */
+    private readonly externalRemovalTombstones = new Set<number>()
+    /**
+     * 走行中の再検証中に届いた明示的キャッシュバイパス要求の持ち越しフラグ。
+     * 走行中の再検証は中断しない方針のため、要求を黙って捨てず完走後に連結実行する。
+     */
+    private pendingForceRefresh = false
+    private wakeRetryWait: (() => void) | null = null
+    private readonly handleOnline = () => this.wakeRetryWait?.()
+
+    /** チャンク由来 publish の合体窓 (ms)。 */
+    private readonly publishCoalesceMs: number
+    /** 合体窓のトレーリングタイマー。 */
+    private publishCoalesceTimer: ReturnType<typeof setTimeout> | null = null
+    /** 直近のアイテム publish 時刻 (leading edge 判定用)。 */
+    private lastItemsPublishAt = 0
+
+    constructor(options: DailyReportIdsStreamClientOptions = {}) {
+        this.apiBasePath = options.apiBasePath ?? DEFAULT_API_BASE_PATH
+        this.fetchFn = options.fetchFn ?? ((input, init) => fetch(input, init))
+        this.setTimeoutFn = options.setTimeoutFn ?? ((handler, ms) => setTimeout(handler, ms))
+        this.clearTimeoutFn = options.clearTimeoutFn ?? ((id) => clearTimeout(id))
+        this.warn = options.warn ?? ((...args) => console.warn(...args))
+        this.publishCoalesceMs = options.publishCoalesceMs ?? DEFAULT_PUBLISH_COALESCE_MS
+        if (typeof window !== "undefined") {
+            // オフライン復帰でバックオフ待機を即時解除する
+            window.addEventListener("online", this.handleOnline)
+        }
+    }
+
+    /**
+     * Returns the current snapshot (stable reference between publishes).
+     * 現在のスナップショットを返す処理 (publish 間で参照が安定)。
+     */
+    getState(): DailyReportIdsStreamState {
+        return this.state
+    }
+
+    /**
+     * Subscribes to snapshot updates.
+     * スナップショット更新の購読を登録する処理。
+     *
+     * @param listener Change callback. 変更通知コールバック。
+     * @returns Unsubscribe function. 購読解除関数。
+     */
+    subscribe(listener: () => void): () => void {
+        this.listeners.add(listener)
+        return () => this.listeners.delete(listener)
+    }
+
+    /**
+     * Starts the initial stream (idempotent).
+     * 初回ストリーミングを開始する処理 (冪等)。
+     */
+    start(): void {
+        if (this.started || this.disposed) return
+        this.started = true
+        void this.runStreamLoop({ revalidate: false, forceRefresh: false })
+    }
+
+    /**
+     * Restarts after a terminal failure (no-op unless phase is "failed").
+     * failed からの手動再開処理 (failed 以外では何もしない)。
+     *
+     * 受信済みデータと再開カーソルは保持したまま続きから読む。
+     */
+    retry(): void {
+        if (this.disposed || this.state.phase !== "failed") return
+        this.consecutiveFailures = 0
+        void this.runStreamLoop({ revalidate: this.state.hasCompletedOnce, forceRefresh: false })
+    }
+
+    /**
+     * Revalidates a completed stream in the background (SWR-style).
+     * 完走済みストリームをバックグラウンドで再検証する処理 (SWR)。
+     *
+     * カーソルを捨てて先頭から読み直し、Map の重複排除で差分を上書き吸収し、
+     * 完走時に「今回の走査で観測されなかった行」を剪定する (サーバー側削除の反映)。
+     * failed のときはカーソルを保持した再開に切り替える (forceRefresh 指定は失わない)。
+     * streaming/retrying 中は何もしない。
+     *
+     * @param options.forceRefresh サーバー側 SqlResultCache をバイパスするか。
+     */
+    refresh(options: { forceRefresh?: boolean } = {}): void {
+        if (this.disposed) return
+        if (this.state.phase === "failed") {
+            // retry() 相当だが forceRefresh の指定を落とさない (キャッシュクリア意図の保存)
+            this.consecutiveFailures = 0
+            void this.runStreamLoop({ revalidate: this.state.hasCompletedOnce, forceRefresh: options.forceRefresh ?? false })
+            return
+        }
+        if (this.state.phase !== "complete") return
+        // 走行中の再検証を別の refresh が中断して先頭からやり直すと、ensure の多重呼び出し
+        // (clientLoader の prime / ensure / ページ effect) だけで再訪ごとに 3 連ダウンロードになる
+        if (this.state.isRevalidating) {
+            // ただし明示的なキャッシュバイパス要求 (キャッシュクリアボタン) は黙って捨てず、
+            // 走行中の再検証の完走後に連結実行する
+            if (options.forceRefresh) {
+                this.pendingForceRefresh = true
+            }
+            return
+        }
+        this.lastCursor = null
+        this.consecutiveFailures = 0
+        void this.runStreamLoop({ revalidate: true, forceRefresh: options.forceRefresh ?? false })
+    }
+
+    /**
+     * Applies an externally-known upsert (SSE / local mutation) to the resident data.
+     * 外部由来 (SSE / ローカル操作) の upsert を常駐データへ反映する処理。
+     *
+     * これを欠くと、マウント中に作成された日報がストリームセッションに存在せず、
+     * 鮮度窓内の再訪 (再検証なし) で一覧から消える。アクティブな走査中は観測集合にも
+     * 刻み、完走時の剪定で「生きていると分かっている行」を誤って落とさないようにする。
+     */
+    applyExternalUpsert(item: DailyReportItem): void {
+        if (this.disposed || !item || typeof item.reportHubId !== "number") return
+        // 明示的な upsert は「生きている」の権威シグナルなので削除トゥームストーンを解除する
+        this.externalRemovalTombstones.delete(item.reportHubId)
+        this.activeSeenIds?.add(item.reportHubId)
+        const existing = this.itemMap.get(item.reportHubId)
+        // sourceType 未指定の upsert (プロバイダーは知らない) は既存値を保持する
+        const next: DailyReportItem = { reportHubId: item.reportHubId, businessDate: item.businessDate, sourceType: item.sourceType ?? existing?.sourceType }
+        if (!existing || existing.businessDate !== next.businessDate || existing.sourceType !== next.sourceType) {
+            this.itemMap.set(item.reportHubId, next)
+            this.publishItems()
+        }
+    }
+
+    /**
+     * Applies an externally-known removal (SSE report-delete / stale valve) to the resident data.
+     * 外部由来 (SSE report-delete / stale 安全弁) の削除を常駐データへ反映する処理。
+     *
+     * 走査中の後続チャンク (削除前スナップショット) による同一行の再配送は、
+     * クライアント側トゥームストーンが次の新しい走査までブロックする。
+     */
+    applyExternalRemoval(reportHubId: number): void {
+        if (this.disposed) return
+        this.activeSeenIds?.delete(reportHubId)
+        // 削除前スナップショットの後続チャンクによる再配送を、次の新しい走査までブロックする
+        this.externalRemovalTombstones.add(reportHubId)
+        if (this.itemMap.delete(reportHubId)) {
+            this.publishItems()
+        }
+    }
+
+    /**
+     * Aborts everything and detaches listeners (terminal).
+     * すべてを中断しリスナーを外す終了処理 (以後再利用不可)。
+     */
+    dispose(): void {
+        this.disposed = true
+        this.loopGeneration += 1
+        this.activeAbortController?.abort()
+        this.cancelScheduledPublishItems()
+        // 保留中のバックオフ待機を起こす (finish が自分のタイマーを片付ける)
+        this.wakeRetryWait?.()
+        if (typeof window !== "undefined") {
+            window.removeEventListener("online", this.handleOnline)
+        }
+        this.listeners.clear()
+    }
+
+    /**
+     * Connection-retry loop: stream → classify → backoff → resume.
+     * 接続リトライループ。ストリーム → 結果分類 → バックオフ → カーソル再開。
+     */
+    private async runStreamLoop(mode: { revalidate: boolean; forceRefresh: boolean }): Promise<void> {
+        const generation = ++this.loopGeneration
+        // 進行中の旧接続 (再検証開始時など) を中断し、バックオフ待機中の旧ループも
+        // 即時に起こして退場させる (放置すると旧タイマーが残り続ける)
+        this.activeAbortController?.abort()
+        this.wakeRetryWait?.()
+
+        // 先頭からの走査 (初回/再検証) は削除剪定用の観測集合を新調し、外部削除の
+        // トゥームストーンをクリアする (これから受けるスナップショットは削除コミット後)。
+        // カーソル再開 (途中失敗からの retry) は同じ走査の続きなので両方引き継ぐ
+        if (this.lastCursor === null) {
+            this.activeSeenIds = new Set()
+            this.externalRemovalTombstones.clear()
+        }
+
+        // このループ自体が forced run なら、持ち越し要求はここで満たされたことにする
+        // (満たされないまま残ると、無関係な後続の再検証に古い強制走査が連鎖する)
+        if (mode.forceRefresh) {
+            this.pendingForceRefresh = false
+        }
+
+        this.publish({
+            phase: mode.revalidate ? this.state.phase : "streaming",
+            isRevalidating: mode.revalidate,
+            error: null,
+        })
+
+        while (!this.disposed && generation === this.loopGeneration) {
+            // forceRefresh はループ全体で維持する。試行がサーバーへ届く前に失敗した場合、
+            // 1 回で降ろすと後続リトライが古いサーバーキャッシュを掴む
+            const outcome = await this.streamOnce(mode.forceRefresh)
+            if (this.disposed || generation !== this.loopGeneration) return
+
+            if (outcome.kind === "complete") {
+                this.pruneUnseenItems()
+                // 完走 = 成功。失敗予算をリセットする (前進ゼロの完走もあり得るため、
+                // 進行時リセットだけに頼ると連結実行される次のループへ古い予算が漏れる)
+                this.consecutiveFailures = 0
+                // 完走 publish が全量を運ぶため、保留中のトレーリング publish は不要
+                this.cancelScheduledPublishItems()
+                this.lastItemsPublishAt = Date.now()
+                this.publish({
+                    phase: "complete",
+                    isRevalidating: false,
+                    hasCompletedOnce: true,
+                    completedAt: Date.now(),
+                    error: null,
+                    items: Array.from(this.itemMap.values()),
+                    loadedCount: this.itemMap.size,
+                })
+                // 走行中に持ち越された明示的キャッシュバイパス要求を連結実行する
+                if (this.pendingForceRefresh && !this.disposed) {
+                    this.pendingForceRefresh = false
+                    this.lastCursor = null
+                    void this.runStreamLoop({ revalidate: true, forceRefresh: true })
+                }
+                return
+            }
+            if (outcome.kind === "aborted") return
+            if (outcome.kind === "auth-required") {
+                this.publish({ phase: "auth-required", isRevalidating: false })
+                return
+            }
+
+            this.consecutiveFailures += 1
+            if (this.consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                // 再検証中の力尽きは既存データを守って complete のまま静かに諦める
+                // (completedAt は更新しない — 次の再訪で再検証が確実に走るように)
+                if (mode.revalidate && this.state.hasCompletedOnce) {
+                    this.warn("[DailyReportIdsStream] revalidation gave up:", outcome.error.message)
+                    // 持ち越し要求も破棄する (死んだ再検証の後に古い強制走査を連鎖させない)
+                    this.pendingForceRefresh = false
+                    this.publish({ isRevalidating: false, error: outcome.error })
+                } else {
+                    this.publish({ phase: "failed", isRevalidating: false, error: outcome.error })
+                }
+                return
+            }
+
+            this.publish({ phase: mode.revalidate ? this.state.phase : "retrying", error: outcome.error })
+            await this.waitBeforeRetry(Math.min(INITIAL_RETRY_DELAY_MS * 2 ** (this.consecutiveFailures - 1), MAX_RETRY_DELAY_MS))
+        }
+    }
+
+    /**
+     * Prunes map entries not observed by the completed full scan.
+     * 完走した全量走査で観測されなかった Map エントリを剪定する処理。
+     *
+     * サーバー側で削除された日報の残留 (再訪時の亡霊復活・loadedCount > totalCount) を防ぐ。
+     * 観測集合が無い場合 (理論上到達しない防御) は何も消さない。
+     */
+    private pruneUnseenItems(): void {
+        const seen = this.activeSeenIds
+        this.activeSeenIds = null
+        if (!seen) return
+        for (const id of Array.from(this.itemMap.keys())) {
+            if (!seen.has(id)) {
+                this.itemMap.delete(id)
+            }
+        }
+    }
+
+    /**
+     * Runs one streaming attempt and classifies its outcome.
+     * 1 回のストリーミング試行を実行し、結末を分類する処理。
+     */
+    private async streamOnce(forceRefresh: boolean): Promise<StreamAttemptOutcome> {
+        const abortController = new AbortController()
+        this.activeAbortController = abortController
+        try {
+            const response = await this.fetchFn(this.buildStreamUrl(forceRefresh), {
+                signal: abortController.signal,
+                headers: { Accept: "application/x-ndjson" },
+                cache: "no-store",
+            })
+            if (response.status === 401 || response.status === 403) {
+                return { kind: "auth-required" }
+            }
+            if (!(response.ok && response.body)) {
+                return { kind: "retryable", error: new Error(`ids stream HTTP ${response.status}`) }
+            }
+
+            const reader = response.body.getReader()
+            const decoder = new TextDecoder()
+            let partialLine = ""
+            let sawErrorLine = false
+            let sawIsLast = false
+
+            while (true) {
+                const { done, value } = await reader.read()
+                if (done) break
+                // ネットワークチャンクは行境界と無関係に割れるため、末尾の欠け行を持ち越す
+                const lines = (partialLine + decoder.decode(value, { stream: true })).split("\n")
+                partialLine = lines.pop() ?? ""
+
+                let mutated = false
+                for (const rawLine of lines) {
+                    if (rawLine.trim() === "") continue
+                    let parsed: DailyReportIdsStreamLine
+                    try {
+                        parsed = JSON.parse(rawLine) as DailyReportIdsStreamLine
+                    } catch {
+                        // 単一行の破損はスキップし、接続レベルの再開に委ねる
+                        this.warn("[DailyReportIdsStream] skipped malformed line")
+                        continue
+                    }
+                    if (!isIdsStreamChunkLine(parsed)) {
+                        sawErrorLine = true
+                        continue
+                    }
+                    mutated = this.absorbChunkItems(parsed.items) || mutated
+                    if (typeof parsed.total === "number" && Number.isFinite(parsed.total) && parsed.total !== this.state.totalCount) {
+                        // total 単独の変化でも必ず購読者へ通知する (無通知のスナップショット
+                        // 置換は useSyncExternalStore のスナップショット安定契約を破る)
+                        this.publish({ totalCount: parsed.total })
+                    }
+                    if (parsed.nextCursor && (parsed.nextCursor.businessDate === null || CURSOR_DATE_PATTERN.test(parsed.nextCursor.businessDate))) {
+                        // 契約外の日付 (混入データ等) を持つカーソルは採用しない。
+                        // 日付を欠いた id だけの再開は NULL 営業日領域へスキップして欠落を生むため、
+                        // 直前の正当なカーソル (無ければ先頭) から読み直す方が安全
+                        this.lastCursor = parsed.nextCursor
+                    }
+                    if (parsed.isLast) {
+                        sawIsLast = true
+                    }
+                }
+                if (mutated) {
+                    // 前進があった時点で失敗カウンタを戻す (断続的な不調で failed へ落とさない)
+                    this.consecutiveFailures = 0
+                    this.schedulePublishItems()
+                }
+            }
+
+            if (sawErrorLine) {
+                return { kind: "retryable", error: new Error("Stream interrupted by server error") }
+            }
+            if (!sawIsLast) {
+                // サーバー再起動や中間切断。カーソルから再開する
+                return { kind: "retryable", error: new Error("Stream ended before completion") }
+            }
+            return { kind: "complete" }
+        } catch (error) {
+            // DOMException (ブラウザー/undici) と Error 派生 (テスト DI) の両形を受ける
+            if (error instanceof Error && error.name === "AbortError") {
+                return { kind: "aborted" }
+            }
+            return { kind: "retryable", error: error instanceof Error ? error : new Error(String(error)) }
+        } finally {
+            if (this.activeAbortController === abortController) {
+                this.activeAbortController = null
+            }
+        }
+    }
+
+    /**
+     * Merges chunk items into the dedupe map.
+     * チャンクのアイテム群を重複排除 Map へ取り込む処理。
+     *
+     * @returns True when anything was added or changed. 追加または内容変化があれば true。
+     */
+    private absorbChunkItems(items: DailyReportItem[]): boolean {
+        let mutated = false
+        for (const item of items) {
+            if (!item || typeof item.reportHubId !== "number") continue
+            // 走査中に外部削除された ID は、同じ削除前スナップショットの後続チャンクが
+            // 再配送してきても受け入れない (受けると剪定も免れて再訪時に蘇る)
+            if (this.externalRemovalTombstones.has(item.reportHubId)) continue
+            // 内容が既知でも「観測した」事実は剪定用集合へ必ず刻む
+            this.activeSeenIds?.add(item.reportHubId)
+            const existing = this.itemMap.get(item.reportHubId)
+            if (!existing || existing.businessDate !== item.businessDate || existing.sourceType !== item.sourceType) {
+                this.itemMap.set(item.reportHubId, item)
+                mutated = true
+            }
+        }
+        return mutated
+    }
+
+    /** アイテム配列を再スナップショットして即時 publish する。 */
+    private publishItems(): void {
+        this.lastItemsPublishAt = Date.now()
+        this.publish({ items: Array.from(this.itemMap.values()), loadedCount: this.itemMap.size })
+    }
+
+    /**
+     * チャンク由来のアイテム publish をスロットルする (leading edge 即時 + trailing 合体)。
+     * 最初のチャンクは即時に描画へ届け、窓内に密集した後続チャンクは 1 回の publish
+     * (= 1 回の全件ソートと再レンダー) へ合体する。合体窓 0 は無効 (常に即時)。
+     */
+    private schedulePublishItems(): void {
+        if (this.publishCoalesceMs <= 0) {
+            this.publishItems()
+            return
+        }
+        const elapsed = Date.now() - this.lastItemsPublishAt
+        if (elapsed >= this.publishCoalesceMs) {
+            this.publishItems()
+            return
+        }
+        if (this.publishCoalesceTimer !== null) return
+        this.publishCoalesceTimer = this.setTimeoutFn(() => {
+            this.publishCoalesceTimer = null
+            this.publishItems()
+        }, this.publishCoalesceMs - elapsed)
+    }
+
+    /** 保留中のトレーリング publish を破棄する (完走 publish が全量を運ぶ場合など)。 */
+    private cancelScheduledPublishItems(): void {
+        if (this.publishCoalesceTimer !== null) {
+            this.clearTimeoutFn(this.publishCoalesceTimer)
+            this.publishCoalesceTimer = null
+        }
+    }
+
+    /** 部分状態をマージした新スナップショットを作り、購読者へ通知する。 */
+    private publish(partial: Partial<DailyReportIdsStreamState>): void {
+        this.state = { ...this.state, ...partial }
+        for (const listener of this.listeners) {
+            listener()
+        }
+    }
+
+    /** 再開カーソル付きのストリーム URL を構築する。 */
+    private buildStreamUrl(forceRefresh: boolean): string {
+        const params = new URLSearchParams()
+        if (this.lastCursor) {
+            params.set("cursor_report_hub_id", String(this.lastCursor.reportHubId))
+            // null 営業日領域の再開は日付パラメータを省略する (サーバー側の契約)
+            if (this.lastCursor.businessDate !== null) {
+                params.set("cursor_business_date", this.lastCursor.businessDate)
+            }
+        }
+        if (forceRefresh) {
+            params.set("forceRefresh", "true")
+        }
+        const query = params.toString()
+        return `${this.apiBasePath}/ids-stream${query ? `?${query}` : ""}`
+    }
+
+    /**
+     * バックオフ待機。online イベント・dispose・後続ループの開始で早期解除される。
+     *
+     * タイマー ID は待機ごとのローカルに閉じ、共有スロット (wakeRetryWait) は
+     * 「まだ自分を指しているときだけ」外す。単一スロットへ素朴に書くと、
+     * 追い越された旧待機の finish が新しいループのタイマーを消してしまい、
+     * 再検証が永久に固まる (実測済みの競合)。
+     */
+    private waitBeforeRetry(delayMs: number): Promise<void> {
+        return new Promise((resolve) => {
+            let timerId: ReturnType<typeof setTimeout> | null = null
+            const finish = () => {
+                if (timerId !== null) {
+                    this.clearTimeoutFn(timerId)
+                    timerId = null
+                }
+                if (this.wakeRetryWait === finish) {
+                    this.wakeRetryWait = null
+                }
+                resolve()
+            }
+            this.wakeRetryWait = finish
+            timerId = this.setTimeoutFn(finish, delayMs)
+        })
+    }
+}