@aiquants/daily-report 0.20.0 → 0.21.0

package/src/server/handlers.ts

@@ -1,1638 +0,0 @@
-/**
- * React Router loader/action factories for the daily-report HTTP surface.
- * 日報 HTTP サーフェス向けの React Router loader / action 工場。
- *
- * - index.loader: 画面ルートの認証 + 難読化ユーザー ID 解決
- * - api.loader / api.action: `:endpoint` パラメータ式の認証付き API ルーター
- * - sse.loader: Redis Streams ベースのリアルタイム更新 SSE エンドポイント
- */
-import { normalizeBusinessDateKey } from "../shared/business-date"
-import { computeIdsStreamSnapshotToken, type DailyReportIdsStreamChunkLine, type DailyReportIdsStreamCursor, type DailyReportIdsStreamErrorLine, findIdsStreamResumeIndex } from "../shared/ids-stream"
-import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
-import { type DailyReportSseMessage, dailyReportSseMessageSchema } from "../shared/sse-schema"
-import type { DailyReportDetail, DailyReportItem } from "../shared/types"
-import type { DailyReportAttachmentFailure, DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportIdCodec, DailyReportReadAttachment, DailyReportRedisProvider, DailyReportResolveVisibleSourceTypes, DailyReportVisibilityResolveReason } from "./ports"
-import { jsonResponseWithETag } from "./response"
-import type { DailyReportService } from "./service"
-import type { DailyReportSseReader, StreamEntry } from "./sse-reader"
-import { isStreamIdLte } from "./sse-reader"
-import { DailyReportViewerScope, isSourceTypeVisible, type VisibleSourceTypeSet } from "./visibility"
-
-type LoaderArgs = { request: Request; params: Record<string, string | undefined> }
-
-/** `data()` 相当の JSON レスポンス生成 (react-router 非依存)。`setCookie` 指定時は Set-Cookie を付与する。 */
-const jsonData = (payload: unknown, init?: { status?: number; setCookie?: string }): Response => {
-    const headers = new Headers({ "Content-Type": "application/json" })
-    // セッション破棄の Set-Cookie は未認証応答にも載せる (捨てると無効セッションがブラウザに残る)
-    if (init?.setCookie) {
-        headers.append("Set-Cookie", init.setCookie)
-    }
-    return new Response(JSON.stringify(payload), { status: init?.status ?? 200, headers })
-}
-
-// ---------------- ids NDJSON ストリームの定数とヘルパー (純粋・モジュールスコープ) ----------------
-
-/**
- * First-chunk size, tuned for time-to-first-render.
- * 初回チャンクのアイテム数。最初の描画までの時間を優先して小さく保つ。
- *
- * 一覧の可視行 + オーバースキャンを一度に満たせる件数であればよい。
- */
-const IDS_STREAM_FIRST_CHUNK_SIZE = 30
-
-/**
- * 2 チャンク目以降のアイテム数。1 アイテムが数十バイト (id/日付/種別のみ) と軽いため
- * 大きめに運ぶ。実データは 20 万件超に達するため、小さすぎると行数 (= pull 往復と
- * クライアント側 publish 回数) が肥大する (4000 件 ≈ 240 KB/行、20 万件で約 50 行)。
- */
-const IDS_STREAM_NEXT_CHUNK_SIZE = 4000
-
-/**
- * Sanitized message for mid-stream failures (no internal details).
- * ストリーム送出中の失敗をクライアントへ伝える定型文 (内部情報は載せない)。
- */
-const IDS_STREAM_ERROR_CLIENT_MESSAGE = "stream interrupted by server error"
-
-/** 再開カーソルの営業日として受け付ける唯一の形式 (正規化済み YYYY-MM-DD)。 */
-const IDS_STREAM_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
-
-/**
- * Heartbeat interval while the next chunk is pending (ms).
- * 次チャンク待ちの間に空行ハートビートを送る間隔 (ms)。
- *
- * 全量クエリ (20 万件超) の確定待ちで無音が続くと、クライアントの stall ウォッチドッグ
- * (既定 30s) が生きた接続を half-open と誤認する。それより十分短い間隔で空行を送り、
- * read を解決させて誤検知を防ぐ。空行はクライアント側で読み飛ばされる (`trim() === ""`)。
- */
-const IDS_STREAM_HEARTBEAT_MS = 15_000
-
-/** next() 待ちがハートビート間隔に負けたことを表す番兵。 */
-const IDS_STREAM_HEARTBEAT = Symbol("ids-stream-heartbeat")
-
-/**
- * Keep-alive ticks between SSE visibility re-resolutions.
- * SSE の可視集合を再解決する間隔 (keep-alive tick 数)。
- *
- * keep-alive は 5 秒間隔なので 12 tick = 約 60 秒。読み取り経路がリクエストごとに再解決するのに対し
- * SSE は接続が長寿命なため、この間隔が権限失効の反映遅延の上限になる。
- */
-const SSE_VISIBILITY_REFRESH_TICKS = 12
-
-/**
- * Parses and validates resume-cursor query params (fail-closed).
- * 再開カーソルのクエリパラメータを検証付きで解釈する処理 (不正は fail-closed)。
- *
- * - `cursor_report_hub_id` 単独 = 「営業日なし領域」のカーソル (businessDate: null)。
- * - `cursor_business_date` は `cursor_report_hub_id` 無しでは意味を持たないため 400。
- *
- * @param url Request URL. リクエスト URL。
- * @returns Cursor (null = 先頭から) か、検証失敗の印。
- */
-/** スナップショットトークンの形式 (computeIdsStreamSnapshotToken の出力域)。 */
-const IDS_STREAM_SNAPSHOT_PATTERN = /^[0-9a-f]{1,16}$/
-
-const parseIdsStreamCursor = (url: URL): { cursor: DailyReportIdsStreamCursor | null; snapshot: string | null } | { invalid: true } => {
-    const rawId = url.searchParams.get("cursor_report_hub_id")
-    const rawDate = url.searchParams.get("cursor_business_date")
-    const rawSnapshot = url.searchParams.get("cursor_snapshot")
-    // ❗ トークンの形式違反は 400 にしない。「トークン無し」へ落とせば先頭からの再送で
-    //    回復できる — 再開の失敗はデータ喪失ではなく、接続ごと落とすより常に安全側
-    const snapshot = rawSnapshot !== null && IDS_STREAM_SNAPSHOT_PATTERN.test(rawSnapshot) ? rawSnapshot : null
-
-    if (rawId === null) {
-        // 営業日だけのカーソルは並び順上の位置を決められない
-        return rawDate === null ? { cursor: null, snapshot } : { invalid: true }
-    }
-
-    const reportHubId = Number.parseInt(rawId, 10)
-    if (!Number.isSafeInteger(reportHubId) || String(reportHubId) !== rawId || reportHubId <= 0) {
-        return { invalid: true }
-    }
-
-    if (rawDate === null) {
-        return { cursor: { businessDate: null, reportHubId }, snapshot }
-    }
-    if (!IDS_STREAM_DATE_PATTERN.test(rawDate)) {
-        return { invalid: true }
-    }
-    return { cursor: { businessDate: rawDate, reportHubId }, snapshot }
-}
-
-/**
- * Emits a finalized id array as chunked NDJSON lines from a resume position.
- * 確定済み ID 配列を再開位置からチャンク行として送出するジェネレーター。
- *
- * `total` は最初に yield する行へ載せる (= 接続内で全量が確定した最初の行。
- * キャッシュヒットの新規接続と再開接続では先頭行、高速先頭ページ経路では 2 行目)。
- *
- * @param items Stream-ordered full array. ストリーム順の全量配列。
- * @param resumeKey Resume position (null = 先頭から)。
- * @param firstChunkSize このジェネレーターの最初のチャンクサイズ。
- */
-async function* streamLinesFromFullArray(items: DailyReportItem[], resumeKey: DailyReportIdsStreamCursor | null, firstChunkSize: number, options: { snapshot: string; restarted?: boolean }): AsyncGenerator<DailyReportIdsStreamChunkLine> {
-    let position = resumeKey ? findIdsStreamResumeIndex(items, resumeKey) : 0
-    let isFirstYield = true
-    while (true) {
-        const chunkItems = items.slice(position, position + (isFirstYield ? firstChunkSize : IDS_STREAM_NEXT_CHUNK_SIZE))
-        position += chunkItems.length
-        const isLast = position >= items.length
-        const lastItem = chunkItems[chunkItems.length - 1]
-        yield {
-            kind: "chunk",
-            items: chunkItems,
-            nextCursor: isLast || !lastItem ? null : { businessDate: lastItem.businessDate, reportHubId: lastItem.reportHubId },
-            isLast,
-            ...(isFirstYield ? { total: items.length } : {}),
-            // 権威行は必ずトークンを運ぶ (resume 経路も含む)。載せ忘れると最初の再開成功で
-            // クライアントのトークンが失われ、2 度目以降の切断が全量再送へ退化する
-            snapshot: options.snapshot,
-            // restarted は先頭行にのみ載せる。全行に載せるとクライアントが行ごとに初期化し、
-            // 直前の行で受けたデータを捨てる
-            ...(isFirstYield && options.restarted ? { restarted: true } : {}),
-        }
-        isFirstYield = false
-        if (isLast) return
-    }
-}
-
-/**
- * Wraps a line iterator into a pull-based NDJSON streaming Response.
- * 行イテレーターを pull 駆動の NDJSON ストリーミング Response へ包む処理。
- *
- * - 切断検知時はイテレーターを畳んで (`return()`) DB 待ちを解放し、close する
- *   (素の return は desiredSize > 0 のまま pull が再帰する)。
- * - イテレーターの throw は内部情報を含まない定型エラー行 + 正常クローズへ倒す
- *   (クライアントは「isLast 無し終端」をカーソル再開のシグナルとして扱う)。
- */
-const buildIdsStreamResponse = (cookie: string | null, lines: AsyncGenerator<DailyReportIdsStreamChunkLine>, request: Request, logger: DailyReportLogger): Response => {
-    const encoder = new TextEncoder()
-    // cancel() の lines.return() は「pull が DB 待ちの next() を保留中」だと先取りできない。
-    // 待ちが明けた後の enqueue が閉じたストリームへ落ちて catch に入るため、切断は
-    // フラグで決定的に識別し、通常イベントとして静かに畳む (ERROR ログにしない —
-    // 全量クエリ中の離脱は日常イベントで、本物の送出失敗が雑音に埋もれる)
-    let cancelled = false
-    // next() の解決はハートビートを跨いで保持する。ハートビートが先着したら空行を出し、
-    // 同じ next() を次の pull で await し直す (毎回 next() を呼び直すと二重取得になる)。
-    let pendingNext: Promise<IteratorResult<DailyReportIdsStreamChunkLine>> | null = null
-    const stream = new ReadableStream<Uint8Array>({
-        async pull(controller) {
-            if (cancelled || request.signal.aborted) {
-                await lines.return(undefined).catch(() => {})
-                try {
-                    controller.close()
-                } catch {
-                    // cancel 済みコントローラーの close は失敗してよい
-                }
-                return
-            }
-            let heartbeatTimer: ReturnType<typeof setTimeout> | null = null
-            try {
-                if (pendingNext === null) {
-                    pendingNext = lines.next()
-                }
-                // 次チャンクの確定待ちが長引く間、接続の生存を示す空行を送る
-                const heartbeatPromise = new Promise<typeof IDS_STREAM_HEARTBEAT>((resolve) => {
-                    heartbeatTimer = setTimeout(() => resolve(IDS_STREAM_HEARTBEAT), IDS_STREAM_HEARTBEAT_MS)
-                })
-                const raced = await Promise.race([pendingNext, heartbeatPromise])
-                if (heartbeatTimer !== null) {
-                    clearTimeout(heartbeatTimer)
-                    heartbeatTimer = null
-                }
-                if (raced === IDS_STREAM_HEARTBEAT) {
-                    // next() はまだ保留中。空行だけ送って pending は次の pull へ持ち越す
-                    if (cancelled || request.signal.aborted) {
-                        await lines.return(undefined).catch(() => {})
-                        try {
-                            controller.close()
-                        } catch {
-                            // cancel 済みコントローラーの close は失敗してよい
-                        }
-                        return
-                    }
-                    controller.enqueue(encoder.encode("\n"))
-                    return
-                }
-                pendingNext = null
-                const { value, done } = raced
-                if (done) {
-                    controller.close()
-                    return
-                }
-                // 保留中の next() の間に切断された場合はここで検知して静かに終える
-                if (cancelled || request.signal.aborted) {
-                    await lines.return(undefined).catch(() => {})
-                    try {
-                        controller.close()
-                    } catch {
-                        // cancel 済みコントローラーの close は失敗してよい
-                    }
-                    return
-                }
-                controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`))
-            } catch (error) {
-                if (heartbeatTimer !== null) {
-                    clearTimeout(heartbeatTimer)
-                }
-                // next() が throw した = このイテレーターは畳む。保留参照を残さない
-                pendingNext = null
-                if (cancelled || request.signal.aborted) {
-                    // 切断起因の enqueue/close 失敗はエラーではない
-                    return
-                }
-                logger.error(`ids-stream emission failed: ${error instanceof Error ? error.message : String(error)}`)
-                try {
-                    // ❗ 素のリテラルを stringify に渡さない。JSON.stringify は any を受けるため、
-                    //    型を束縛しないとワイヤユニオンの `kind` 要求がここだけ素通りする
-                    const errorLine: DailyReportIdsStreamErrorLine = { kind: "error", error: IDS_STREAM_ERROR_CLIENT_MESSAGE }
-                    controller.enqueue(encoder.encode(`${JSON.stringify(errorLine)}\n`))
-                    controller.close()
-                } catch {
-                    // 既に切断済みなら何もできない
-                }
-            }
-        },
-        cancel() {
-            cancelled = true
-            void lines.return(undefined).catch(() => {})
-        },
-    })
-
-    const headers = new Headers({
-        "Content-Type": "application/x-ndjson; charset=utf-8",
-        // no-transform: compression ミドルウェア/中間プロキシによるバッファリングを禁止する (SSE と同じ理由)
-        "Cache-Control": "private, no-cache, no-transform",
-        "X-Content-Type-Options": "nosniff",
-    })
-    if (cookie) {
-        headers.append("Set-Cookie", cookie)
-    }
-    return new Response(stream, { status: 200, headers })
-}
-
-// ---------------- 添付配信の定数とヘルパー (純粋・モジュールスコープ) ----------------
-
-/** 添付 1 件あたりの既定上限。サービス側のワイヤ上限 (既定 64 MiB) より必ず低く保つ。 */
-const DEFAULT_ATTACHMENT_MAX_BYTES = 32 * 1024 * 1024
-
-/**
- * Default per-user rate limit (calls per minute), enforced per process.
- * ユーザー単位の既定レート上限 (1 分あたり)。ただし**プロセス単位**で計上する。
- *
- * バケットはハンドラーのクロージャに置く素の `Map` であり、プロセス間で共有されない。
- * 消費アプリが Node Cluster 等で複数ワーカーを起動する場合、コンテナ全体の実効上限は
- * この値のワーカー数倍になる。全体で厳密に効かせたいなら共有ストア (Redis 等) が要る。
- */
-const DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE = 60
-
-/**
- * Default simultaneous-read limit, enforced per process.
- * 既定の同時実行上限。**プロセス単位**で計上する。
- *
- * 1 リクエストが上限バイト数をヒープへ載せるため小さく保つ。ヒープ見積りは
- * 「この値 × `attachmentMaxBytes` × ワーカー数」であり、ワーカー数を掛け忘れると
- * コンテナのメモリ上限を実際の数倍で見誤る。消費アプリはワーカー数を織り込んだ値を
- * `attachmentConcurrency` で明示注入すること。
- *
- * スロットは**本文をクライアントへ送出し終えるまで**保持する。読み取り完了時点で
- * 解放すると、前の応答のバイト列がヒープに載ったまま次の読み取りが始まるため、
- * 上の見積りが成立しなくなる (実際の同時保持数は無制限になる)。
- */
-const DEFAULT_ATTACHMENT_CONCURRENCY = 4
-
-/**
- * Backstop for releasing a concurrency slot when the client never drains the body.
- * クライアントが本文を読み切らない場合に同時実行スロットを解放するバックストップ。
- *
- * スロットを送出完了まで保持する以上、接続を張ったまま読み止めたクライアントが
- * スロットを永久に占有できてしまう。これは締め切りではなく枯渇防止の保険であり、
- * 超過しても応答は中断しない (単にゲートの会計上、保持されていない扱いにするだけ)。
- */
-const ATTACHMENT_BODY_FLUSH_TIMEOUT_MS = 120_000
-
-/** レート制限テーブルの上限件数。無制限 Map はプロセス寿命の間だけ単調増加するリークになる。 */
-const RATE_LIMITER_MAX_ENTRIES = 1024
-
-/** レート上限超過時に提示する再試行間隔 (秒)。 */
-const RATE_LIMIT_RETRY_AFTER_SECONDS = 60
-
-/** 同時実行上限に達したときに提示する再試行間隔 (秒)。 */
-const CONCURRENCY_RETRY_AFTER_SECONDS = 5
-
-/**
- * Media types allowed to render inline in the browser.
- * ブラウザーへインライン表示してよい media type。
- *
- * これ以外は必ず添付ダウンロードにし、Content-Type も `application/octet-stream` へ落とす。
- * `file_type` は外部システム由来の未検証値であり、`text/html` や `image/svg+xml` を
- * 自オリジンでインライン配信するとセッション Cookie を持つ文脈でスクリプトが動く。
- * `X-Content-Type-Options: nosniff` は「宣言型から外れた推測」を止めるだけで、
- * 宣言された型の実行は止めない。
- */
-const INLINE_SAFE_MEDIA_TYPES: ReadonlySet<string> = new Set(["image/png", "image/jpeg", "image/gif", "image/webp", "application/pdf", "text/plain"])
-
-/** ヘッダー値として安全で、かつ MIME 型の形をしている値だけを通す。 */
-const HEADER_SAFE_PATTERN = /^[\x20-\x7E]+$/
-const MEDIA_TYPE_PATTERN = /^[\w.+-]+\/[\w.+-]+/
-
-/**
- * Accepts a media type only when it is header-safe and well-formed.
- * ヘッダー安全かつ MIME 型の形をしている場合のみ採用する処理。
- *
- * CR/LF や 0x00-0xFF 外の文字が混ざった値を `new Headers()` へ渡すと TypeError になり、
- * 認可済みのダウンロードが 500 になる。
- *
- * **これは第 2 層である。** 現在の配信経路では、注入値はインライン許可リストに完全一致しないため
- * 必ず `application/octet-stream` へ落ち、ヘッダーには到達しない。つまり本関数を外しても
- * 現状の挙動は変わらない (ミューテーションテストで確認済み)。
- * 許可判定を前方一致や「DB の型を信じる」形へ変えた瞬間に効き始める防御なので、
- * 到達不能なまま放置せず **直接の単体テストで固定する**目的でエクスポートしている。
- *
- * @param value Candidate media type. 候補となる media type。
- * @returns The value when acceptable, otherwise null. 採用可なら値、それ以外は null。
- */
-export const sanitizeMediaType = (value: string | null | undefined): string | null => (value && HEADER_SAFE_PATTERN.test(value) && MEDIA_TYPE_PATTERN.test(value) ? value : null)
-
-/**
- * Percent-encodes a file name for the RFC 8187 `filename*` parameter.
- * RFC 8187 の `filename*` 用にファイル名をパーセントエンコードする処理。
- *
- * `encodeURIComponent` は `'` `(` `)` `*` を残すが、いずれも RFC 8187 の attr-char ではない。
- *
- * @param name Raw file name. 生のファイル名。
- * @returns Encoded value. エンコード済みの値。
- */
-export const encodeRfc8187 = (name: string): string => encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
-
-/**
- * Builds the ASCII fallback used by the plain `filename` parameter.
- * 素の `filename` パラメータ用の ASCII フォールバックを組み立てる処理。
- *
- * @param name Raw file name. 生のファイル名。
- * @returns ASCII-only, quote-free name. ASCII のみで引用符を含まない名前。
- */
-export const asciiFallbackFileName = (name: string): string => name.replace(/[^\x20-\x7E]/g, "_").replace(/["\\]/g, "_")
-
-/**
- * Maps a storage read failure onto the HTTP status the endpoint returns.
- * ストレージ読み取りの失敗種別を、エンドポイントが返す HTTP ステータスへ写像する処理。
- *
- * `not_found` と `denied` はどちらも 404 にする。認可判定は既に SQL 側で完了しているため
- * 横断的な情報漏洩は無いが、実体の有無を 403/404 で区別すると存在オラクルになる。
- *
- * @param reason Failure kind reported by the port. ポートが報告した失敗種別。
- * @returns HTTP status code. HTTP ステータスコード。
- */
-const attachmentFailureToStatus = (reason: DailyReportAttachmentFailure): number => {
-    switch (reason) {
-        case "not_found":
-        case "denied":
-        case "invalid_path":
-            return 404
-        case "too_large":
-            return 413
-        default:
-            return 502
-    }
-}
-
-/**
- * Client-facing messages per failure status.
- * 失敗ステータスごとのクライアント向けメッセージ。
- *
- * 404 は「存在しない」「認可されない」「実体が消えた」の合流点なので、
- * どの経路から来ても同一の文面にする (差分が存在オラクルになるため)。
- */
-const ATTACHMENT_FAILURE_MESSAGES: Readonly<Record<number, string>> = {
-    404: "Attachment not found",
-    413: "Attachment too large",
-    502: "Attachment storage unavailable",
-}
-
-/** レート制限 1 ユーザー分の状態。 */
-type RateBucket = { tokens: number; lastRefillMs: number }
-
-/**
- * Creates a bounded per-user token-bucket rate limiter (process-local).
- * ユーザー単位のトークンバケット方式レート制限を、件数上限付きで生成する処理 (プロセス内限定)。
- *
- * 上限を設ける理由: 素の `Map` で保持するとプロセス寿命の間だけ単調増加し、
- * 「サーバー側の状態は上限を持つ」という設計方針 (SqlResultCache の >500 GC) に反する。
- * 上限到達時は挿入順が最も古いエントリから落とす。
- *
- * 状態はプロセス内に閉じるため、マルチワーカー配備では実効上限がワーカー数倍になる
- * (`DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE` 参照)。
- *
- * @param limitPerMinute Allowed calls per minute. 1 分あたりの許可回数。
- * @returns A function that consumes one token and reports whether it was allowed. トークンを 1 つ消費し可否を返す関数。
- */
-const createRateLimiter = (limitPerMinute: number) => {
-    const buckets = new Map<number, RateBucket>()
-    return (userId: number, nowMs: number): boolean => {
-        const existing = buckets.get(userId)
-        // アクセスのたびに再挿入して LRU 順序にする (Map は挿入順を保つ)
-        if (existing) buckets.delete(userId)
-
-        const bucket = existing ?? { tokens: limitPerMinute, lastRefillMs: nowMs }
-        const elapsedMs = Math.max(0, nowMs - bucket.lastRefillMs)
-        if (elapsedMs > 0) {
-            bucket.tokens = Math.min(limitPerMinute, bucket.tokens + (elapsedMs * limitPerMinute) / 60_000)
-            bucket.lastRefillMs = nowMs
-        }
-
-        const allowed = bucket.tokens >= 1
-        if (allowed) bucket.tokens -= 1
-
-        buckets.set(userId, bucket)
-        while (buckets.size > RATE_LIMITER_MAX_ENTRIES) {
-            const oldest = buckets.keys().next()
-            if (oldest.done) break
-            buckets.delete(oldest.value)
-        }
-        return allowed
-    }
-}
-
-/**
- * Creates a fail-fast concurrency gate (no queueing, process-local).
- * 待ち行列を持たない即時失敗型の同時実行ゲートを生成する処理 (プロセス内限定)。
- *
- * 待たせるとリクエストを掴んだまま滞留するだけなので、上限超過は即座に 503 を返す。
- * カウンタはプロセス内に閉じるため、マルチワーカー配備ではコンテナ全体の同時読み取り数が
- * 上限のワーカー数倍になる (`DEFAULT_ATTACHMENT_CONCURRENCY` 参照)。
- *
- * @param limit Maximum simultaneous holders. 同時保持数の上限。
- * @returns Acquire/release pair. 取得と解放の組。
- */
-const createConcurrencyGate = (limit: number) => {
-    let active = 0
-    return {
-        tryAcquire: (): boolean => {
-            if (active >= limit) return false
-            active += 1
-            return true
-        },
-        release: (): void => {
-            if (active > 0) active -= 1
-        },
-    }
-}
-
-/**
- * Streams already-materialized bytes and releases the held slot once the body is drained.
- * materialize 済みのバイト列をストリームとして送出し、送出完了時に保持中のスロットを解放する処理。
- *
- * 読み取り完了時点で解放してはならない。その時点でバイト列はまだヒープ上にあり、
- * 応答が流し切られるまで参照が保持されるため、「同時実行上限 × 上限バイト数」という
- * ヒープ見積りが成立しなくなる。ここで送出完了まで保持することで見積りを実際に成立させる。
- *
- * 解放は必ず 1 回だけ行う (正常終了・キャンセル・バックストップのいずれか最初の 1 回)。
- *
- * @param bytes Body bytes to send. 送出する本文のバイト列。
- * @param release Idempotent slot release. 冪等なスロット解放関数。
- * @param timeoutMs Backstop before force-releasing. 強制解放までのバックストップ時間。
- * @returns A stream that emits the bytes once. バイト列を 1 度だけ流すストリーム。
- */
-const streamAndRelease = (bytes: Uint8Array<ArrayBuffer>, release: () => void, timeoutMs: number): ReadableStream<Uint8Array> => {
-    const timer: ReturnType<typeof setTimeout> = setTimeout(release, timeoutMs)
-    // タイマーがプロセス終了を待たせないようにする (Node 以外では unref を持たない)
-    ;(timer as unknown as { unref?: () => void }).unref?.()
-    const finish = () => {
-        clearTimeout(timer)
-        release()
-    }
-
-    let sent = false
-    return new ReadableStream<Uint8Array>({
-        pull(controller) {
-            // 1 回目の pull で本文を積み、消費された後の 2 回目の pull で閉じて解放する
-            if (sent) {
-                controller.close()
-                finish()
-                return
-            }
-            sent = true
-            controller.enqueue(bytes)
-        },
-        cancel() {
-            finish()
-        },
-    })
-}
-
-/**
- * Decides whether an SSE message is visible under the viewer's source-type set.
- * SSE メッセージが閲覧者の可視 sourceType 集合において可視かを判定する処理。
- *
- * - `connected` / `status-update`: 常に可視。前段で本人限定済みであり、区分も本文も載らない。
- * - `report-create` / `report-update` / `report-publish`: 埋め込み `report.sourceType` で判定する。
- *   値が欠落していれば `isSourceTypeVisible` の規則により制限閲覧者には不可視 (fail-close)。
- * - `comment-add` / `comment-delete`: 新規コメントは `addComment` の Internal 限定ゲートを通るため
- *   構造上 Internal のみ。明示 `sourceType` があればそれを使い、無い旧エントリは `"Internal"` として扱う。
- * - `report-delete`: 明示 `sourceType` で判定し、値の無い旧エントリは fail-close で落とす
- *   (削除の取りこぼしは次回取得で自己修復する良性の劣化)。
- *
- * ❗ `comment-add` / `comment-delete` は**コメント次元**で判定する。本文次元で判定すると、
- * 「本文は読めるがコメントは読めない」閲覧者へコメント本文が届く。
- *
- * @param parsed Validated SSE message. 検証済みの SSE メッセージ。
- * @param raw Raw payload carrying server-only fields. サーバー専用フィールドを含む生ペイロード。
- * @param visible Normalized visible source-type set (body dimension). 正規化済みの可視 sourceType 集合 (本文次元)。
- * @param commentable Normalized commentable source-type set. 正規化済みのコメント可視 sourceType 集合。
- * @returns True when the message may be delivered. 配信してよいなら true。
- */
-const isSseMessageSourceTypeVisible = (parsed: DailyReportSseMessage, raw: Record<string, unknown>, visible: VisibleSourceTypeSet, commentable: VisibleSourceTypeSet): boolean => {
-    // 両次元とも無制限なら種別を問わず配信する (現行互換の高速経路)
-    if (visible === null && commentable === null) {
-        return true
-    }
-    const rawSourceType = typeof raw.sourceType === "string" ? raw.sourceType : undefined
-    switch (parsed.type) {
-        case "connected":
-        case "status-update":
-            return true
-        case "report-create":
-        case "report-update":
-        case "report-publish":
-            // 本文次元だけで配信可否を決める。コメント面はフィールド単位で落とす
-            // (メッセージごと落とすと日報更新そのものが届かなくなる)
-            return isSourceTypeVisible(visible, parsed.report.sourceType)
-        case "comment-add":
-        case "comment-delete":
-            return isSourceTypeVisible(commentable, rawSourceType ?? "Internal")
-        case "report-delete":
-            return isSourceTypeVisible(visible, rawSourceType)
-    }
-}
-
-/**
- * Empties the comment arrays of a `report-*` payload when the viewer may not read comments.
- * コメントを読めない閲覧者向けに `report-*` ペイロードのコメント配列を空にする処理。
- *
- * `report-create` / `report-update` / `report-publish` は `report: dailyReportDetailSchema` を
- * 埋め込んでおり、その detail は `externalComments` と `postedComments` を必須キーとして含む。ペイロードは
- * 発行時に**無制限スコープ**で構築されて Redis Stream へ載る共有物であるため、閲覧者ごとの
- * 絞り込みはこの配信直前が唯一の機会になる。
- *
- * ❗ キーを**省いてはならない**。必須キーの欠落は受信側の `safeParse` を失敗させ、メッセージ全体が
- * fail-close で捨てられる (日報更新そのものが永久に届かなくなる)。必ず空配列で上書きする。
- *
- * ❗ `raw` は購読者ごと・エントリごとに `JSON.parse` された固有オブジェクトなので、その場で
- * 書き換えてよい (他の購読者へ波及しない)。
- *
- * ❗ 戻り値は捨てないこと。配信側は元の生文字列 (`fields.data`) をそのまま送る高速経路を持って
- * おり、秘匿したのに再直列化しないと**書き換えが無かったことになる**。
- *
- * @param parsed Validated SSE message. 検証済みの SSE メッセージ。
- * @param raw Raw payload to redact in place. その場で秘匿する生ペイロード。
- * @param commentable Normalized commentable source-type set. 正規化済みのコメント可視 sourceType 集合。
- * @returns True when the payload was modified. ペイロードを書き換えたなら true。
- */
-/**
- * The two comment faces of a detail payload, as wire keys.
- * 詳細ペイロードのコメント 2 面 (ワイヤキー)。
- *
- * ❗ 文字列キーで直接書かない。秘匿対象の生ペイロードは `Record<string, unknown>` なので、
- * 素の文字列は改名を tsc が検知できず、秘匿が無音で no-op になる (= コメント本文が権限の
- * 無い閲覧者へ漏洩する)。`satisfies keyof` で型から導出しておけば、次の改名はこの定数を
- * コンパイルエラーにして追従を強制する。
- */
-const COMMENT_FACE_KEYS = ["externalComments", "postedComments"] as const satisfies readonly (keyof DailyReportDetail)[]
-
-const redactSseReportComments = (parsed: DailyReportSseMessage, raw: Record<string, unknown>, commentable: VisibleSourceTypeSet): boolean => {
-    if (commentable === null) {
-        return false
-    }
-    if (parsed.type !== "report-create" && parsed.type !== "report-update" && parsed.type !== "report-publish") {
-        return false
-    }
-    if (isSourceTypeVisible(commentable, parsed.report.sourceType)) {
-        return false
-    }
-    const report = raw.report
-    if (typeof report !== "object" || report === null) {
-        return false
-    }
-    const target = report as Record<string, unknown>
-    for (const key of COMMENT_FACE_KEYS) {
-        target[key] = []
-    }
-    return true
-}
-
-export type DailyReportHandlersConfig = {
-    /** リクエスト認証ポート。 */
-    authenticate: DailyReportAuthenticate
-    /**
-     * 可視 sourceType リゾルバ。未注入なら全件 (現行互換)。
-     * 全データ経路 (一覧 / 詳細 / コメント / 添付 / SSE) に一貫して効き、例外は全拒否として扱う。
-     */
-    resolveVisibleSourceTypes?: DailyReportResolveVisibleSourceTypes
-    /** データアクセスサービス。 */
-    service: DailyReportService
-    /** 内部数値 ID の難読化ポート。 */
-    encodeUserId: DailyReportEncodeUserId
-    /**
-     * 添付 ID の難読化コーデック。未注入なら添付エンドポイントは常に 404。
-     * ユーザー ID 用とは別インスタンスを渡すこと (ID 空間の分離)。
-     */
-    attachmentIdCodec?: DailyReportIdCodec
-    /** 添付ファイル読み取りポート。未注入なら添付エンドポイントは常に 404。 */
-    readAttachment?: DailyReportReadAttachment
-    /** 添付ファイルの最大バイト数 (既定 32 MiB)。サービス側のワイヤ上限より低く保つこと。 */
-    attachmentMaxBytes?: number
-    /** 添付エンドポイントの 1 分あたり呼び出し上限 (ユーザー単位・既定 60)。 */
-    attachmentRateLimitPerMinute?: number
-    /** 添付読み取りの同時実行上限 (プロセス単位・既定 4)。 */
-    attachmentConcurrency?: number
-    /** SSE 用 redis プロバイダー (catch-up の xRange / xRevRange に使用)。 */
-    redis?: DailyReportRedisProvider
-    /** SSE Fan-Out 共有リーダー。 */
-    sseReader: DailyReportSseReader
-    /** SSE Redis Stream キー。 */
-    streamKey: string
-    /** 未ログイン時のリダイレクト先 (index.loader 用、既定 "/auth/login")。 */
-    loginRedirectPath?: string
-    /**
-     * `intent=clearCache` (全サーバーキャッシュの一括破棄) を許可するか。既定 false。
-     * 開発用アフォーダンスであり、有効化すると認証済みユーザーなら誰でも全ワーカーの
-     * キャッシュを無制限に破棄できるため、本番では必ず無効のままにする
-     * (消費アプリは開発環境でのみ true を注入する)。
-     */
-    enableDevCacheClear?: boolean
-    /** ロガー (既定は console ベース)。 */
-    logger?: DailyReportLogger
-}
-
-/**
- * Creates the daily-report loaders/actions bound to the injected dependencies.
- * 注入依存に束縛された日報 loader / action 群を生成する処理。
- */
-export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
-    const { authenticate, service, encodeUserId, redis, sseReader, streamKey } = config
-    const loginRedirectPath = config.loginRedirectPath ?? "/auth/login"
-    const apiLogger = config.logger ?? createLogger(LogLevel.ERROR, "[DailyReportAPI]")
-    const visibilityLogger = config.logger ?? createLogger(LogLevel.ERROR, "[DailyReportVisibility]")
-    const sseLogger = config.logger ?? createLogger(LogLevel.INFO, "[DailyReportSSE]")
-    const attachmentLogger = config.logger ?? createLogger(LogLevel.INFO, "[DailyReportAttachment]")
-
-    // 添付配信のプロセス内状態。ファクトリ 1 インスタンスにつき 1 組。
-    const attachmentMaxBytes = config.attachmentMaxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES
-    const consumeAttachmentRateToken = createRateLimiter(config.attachmentRateLimitPerMinute ?? DEFAULT_ATTACHMENT_RATE_LIMIT_PER_MINUTE)
-    const attachmentGate = createConcurrencyGate(config.attachmentConcurrency ?? DEFAULT_ATTACHMENT_CONCURRENCY)
-
-    /**
-     * Resolves and normalizes the visible source-type set once per request (fail-closed).
-     * リクエストごとに可視 sourceType 集合を 1 回だけ解決・正規化する処理 (fail-close)。
-     *
-     * ポート未注入なら `null` (無制限・現行互換)。ポートが例外を投げたら**空集合 (全拒否)**へ倒す。
-     * 認可ストアの障害時に無制限へ倒れないための唯一の防波堤であり、ここを緩めてはならない。
-     *
-     * @param request Incoming request. 受信したリクエスト。
-     * @param reason Why it is being resolved. 解決理由 (SSE の定期再解決は "refresh")。
-     * @returns Normalized visible set. 正規化済みの可視集合。
-     */
-    const resolveViewerScope = async (request: Request, reason: DailyReportVisibilityResolveReason = "initial"): Promise<DailyReportViewerScope> => {
-        const port = config.resolveVisibleSourceTypes
-        if (!port) {
-            return DailyReportViewerScope.unrestricted("no visibility port injected: this deployment does not restrict by source type")
-        }
-        try {
-            const resolved = await port(request, { reason })
-            // ❗ ポートが nullish を返したら「この配備は区分で絞らない」という契約上の fail-open。
-            //    restrictTo へ渡して黙って無制限化すると、監査 grep に現れない 2 つ目の
-            //    無制限生成経路になるため、ここで明示的に unrestricted として記録する
-            return resolved == null ? DailyReportViewerScope.unrestricted("visibility port returned null/undefined: this deployment opts out of source-type filtering") : DailyReportViewerScope.restrictTo(resolved)
-        } catch (e) {
-            visibilityLogger.error("resolveVisibleSourceTypes threw; failing closed (deny all)", e)
-            return DailyReportViewerScope.restrictTo([])
-        }
-    }
-
-    // ---------------- index (画面ルート) ----------------
-
-    /**
-     * Document loader that authenticates and resolves the obfuscated internal user id.
-     * 認証と難読化済み内部ユーザー ID の解決を行うドキュメントローダー。
-     */
-    const indexLoader = async ({ request }: LoaderArgs) => {
-        const { user, cookie } = await authenticate(request, { failureRedirect: loginRedirectPath })
-        const headers = new Headers()
-        if (cookie) {
-            headers.append("Set-Cookie", cookie)
-        }
-
-        // 文字列モード (`failureRedirect: loginRedirectPath`) では認証失敗が redirect として
-        // throw されるため `user` は必ず存在する (`DailyReportAuthenticate` のオーバーロードも
-        // そう宣言している)。`if (user)` は到達しないので置かない
-        const userId: number | null = await service.getUserIdByExternalId(user.id)
-
-        const hashedUserId = userId ? encodeUserId(userId) : null
-
-        return { data: { user, userId: hashedUserId }, headers }
-    }
-
-    // ---------------- api (:endpoint ルーター) ----------------
-
-    type User = { id: string }
-    type EndpointHandler = (url: URL, cookie: string | null, request: Request, user: User, scope: DailyReportViewerScope) => Promise<Response>
-
-    /**
-     * Handlers for each API endpoint.
-     * 各 API エンドポイントのハンドラー定義。
-     */
-    const endpointHandlers: Record<string, EndpointHandler> = {
-        /**
-         * Retrieves daily reports for a specific business date.
-         * 指定された営業日の日報一覧を取得する。
-         */
-        "business-date": async (url, cookie, request, user, scope) => {
-            const normalizedBusinessDate = normalizeBusinessDateKey(url.searchParams.get("businessDate"))
-            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
-
-            if (!normalizedBusinessDate) {
-                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid business date" } }, 400)
-            }
-            const reports = await service.getDailyReportsByBusinessDateByExternalId(scope, normalizedBusinessDate, user.id, { forceRefresh })
-            return jsonResponseWithETag(request, cookie, { businessDate: normalizedBusinessDate, reports }, 200)
-        },
-        /**
-         * Streams the full daily report id list as NDJSON chunks.
-         * 日報 ID 一覧全件を NDJSON チャンクとして逐次配信する。
-         *
-         * 全量クエリ (`SqlResultCache` の TTL / Redis epoch / in-flight コアレッシングを
-         * 素通しで維持) は常に即時に開始する。全量確定を待ってから送出するのは再開接続のみで、
-         * その場合の DB エラーはストリーム開始前に throw されて apiLoader の catch が
-         * 500 JSON を返す。新規接続はキャッシュ無しの TOP 200 高速先頭ページと競争させ、
-         * キャッシュミス時は全量確定前に最初のチャンクを送出する (最初の描画までの時間が
-         * 全体データ量に依存しない)。キャッシュヒット時は全量が即勝ちし、従来どおり
-         * 確定済み配列のメモリスライス送出になる。
-         */
-        "ids-stream": async (url, cookie, request, user, scope) => {
-            const parsed = parseIdsStreamCursor(url)
-            if ("invalid" in parsed) {
-                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid cursor" } }, 400)
-            }
-            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
-
-            // 高速先頭ページは「本リクエストが実際に全量クエリを起動した」ときだけ走らせる。
-            // ❗ この因果が B* の健全性の土台である。バケットヒット・進行中フェッチへの相乗り・
-            //   refresh-ahead が返す全量配列は本リクエストより**古くなり得る**ため、そこへ
-            //   新鮮な先頭ページを重ねると「ページに在って全量に無い行 = 削除済み」の判定が
-            //   反転し、作成直後の日報を消してしまう。合図の後に始まるページは全量より古く
-            //   なり得ないので、この判定が初めて健全になる。
-            //   副次効果として、キャッシュヒット時に走って捨てられていた TOP-N クエリが消える
-            let pageQueryStarted = false
-            let resolvePage: ((items: DailyReportItem[]) => void) | null = null
-            let rejectPage: ((reason?: unknown) => void) | null = null
-            const pagePromise = new Promise<DailyReportItem[]>((resolve, reject) => {
-                resolvePage = resolve
-                rejectPage = reject
-            })
-            // 未処理拒否警告を出さない (拒否はレース側で分類する)
-            pagePromise.catch(() => {})
-
-            // 全量 (SqlResultCache / epoch / コアレッシング維持) は常に即時に走らせ始める
-            const fullArrayPromise = service.getDailyReportIdsByExternalId(scope, user.id, {
-                forceRefresh,
-                // 再開接続は先頭ページを使わない (クライアントは受信済みの続きだけを読む)
-                onFetchStart: parsed.cursor
-                    ? undefined
-                    : () => {
-                          pageQueryStarted = true
-                          service.getDailyReportIdsFirstPageByExternalId(scope, user.id, IDS_STREAM_FIRST_CHUNK_SIZE).then(
-                              (items) => resolvePage?.(items),
-                              (error) => rejectPage?.(error),
-                          )
-                      },
-            })
-            // 拒否はイテレーターの await 側で扱う (ここで未処理拒否警告を出さない)
-            fullArrayPromise.catch(() => {})
-
-            if (parsed.cursor) {
-                // 再開接続: クライアントは高速先頭を受信済みなので全量確定を待つ (エラーは 500)。
-                // 全量クエリはアプリ側の requestTimeout (既定 60s) で境界づけられ、確定後は
-                // スライスだけなので、接続確立後の無音はハートビート対象にならない
-                const fullItems = await fullArrayPromise
-                const snapshot = computeIdsStreamSnapshotToken(fullItems)
-                // ❗ トークンが一致した配列にだけカーソルを信用する。別スナップショットへ当てると、
-                //    カーソルより前に入った行が丸ごと飛ぶ (再接続のたびの欠損)。不一致・トークン
-                //    無し (旧クライアント) は先頭から流し直す — 配備跨ぎタブの再接続が全量再送に
-                //    なる費用は受容済み (仕様書に明記)
-                const resumable = parsed.snapshot !== null && parsed.snapshot === snapshot
-                return buildIdsStreamResponse(cookie, streamLinesFromFullArray(fullItems, resumable ? parsed.cursor : null, IDS_STREAM_FIRST_CHUNK_SIZE, { snapshot, restarted: !resumable }), request, apiLogger)
-            }
-
-            /**
-             * 新規接続: 「高速先頭ページ (TOP n・キャッシュ無し)」と「全量 (キャッシュ経由)」を
-             * 競争させ、先に確定した方で最初のチャンクを出す。キャッシュヒット時はページ自体が
-             * 起動しないので全量が唯一の経路になる (従来どおり先頭行に total)。キャッシュミス時は
-             * 先頭ページが先に届き、最初の描画は全量クエリの確定を待たない。
-             *
-             * ❗ 先頭ページは**暫定 (provisional)** として送る。全量配列とは別スナップショットなので
-             *   「観測した」と扱うと、送出後に消えた行が完走剪定を免れて幽霊行になる。暫定行は
-             *   クライアントが描画はするが観測集合へ刻まないため、権威パスに現れなかった行が
-             *   完走時に正確に落ちる。権威パスは**必ず先頭から**流し直すので、ページ送出後に
-             *   先頭領域へ入ってきた行の取りこぼし (欠損) も構造的に起きない。
-             */
-            const lineIterator = (async function* (): AsyncGenerator<DailyReportIdsStreamChunkLine> {
-                const winner = await Promise.race([
-                    fullArrayPromise.then(
-                        (items) => ({ kind: "full" as const, items }),
-                        (error) => ({ kind: "full-error" as const, error }),
-                    ),
-                    pagePromise.then(
-                        (items) => ({ kind: "page" as const, items }),
-                        () => ({ kind: "page-error" as const }),
-                    ),
-                ])
-
-                let fullItems: DailyReportItem[] | null = null
-                let emittedProvisionalPage = false
-
-                if (winner.kind === "full") {
-                    fullItems = winner.items
-                } else if (winner.kind === "page") {
-                    const pageItems = winner.items
-                    if (pageItems.length < IDS_STREAM_FIRST_CHUNK_SIZE) {
-                        // 先頭ページが上限未満 = データセット全量。しかもページは全量クエリより
-                        // 後に始まっているので、これが最新の権威である。全量を待たずに完結する。
-                        // ❗ ここを provisional にしてはならない (小規模データセットが完走剪定で全消しになる)
-                        yield { kind: "chunk", items: pageItems, nextCursor: null, isLast: true, total: pageItems.length }
-                        return
-                    }
-                    // ❗ カーソルは載せない。未確認領域を指すカーソルで再開すると、継ぎ目が
-                    //    三つ目のスナップショットへ移るだけになる。失敗時は先頭からやり直す
-                    yield { kind: "chunk", items: pageItems, nextCursor: null, isLast: false, provisional: true }
-                    emittedProvisionalPage = true
-                } else if (winner.kind === "full-error" && pageQueryStarted) {
-                    // 全量が先に死んでも、生きている先頭ページがあればまず届ける (暫定として)。
-                    // 完走しない走査では剪定が走らないため、暫定行はそのまま残って画面を埋める
-                    const pageItems = await pagePromise.catch(() => null)
-                    if (pageItems && pageItems.length > 0) {
-                        yield { kind: "chunk", items: pageItems, nextCursor: null, isLast: false, provisional: true }
-                    }
-                }
-                // page-error は全量へフォールバック。full-error はここで throw されエラー行になる
-                if (fullItems === null) {
-                    fullItems = await fullArrayPromise
-                }
-                // ❗ 権威パスは常に index 0 から。ページのキーを再開カーソルとして使うと、
-                //    ページ送出後に先頭領域へ入った行が丸ごと飛ばされる (欠損の構造的原因)。
-                //    チャンクサイズは明示指定する — 三項演算子の既定へ落とすと、ページを出した
-                //    経路で権威パスの初回チャンクが黙って先頭サイズへ縮み、行数が無駄に増える
-                yield* streamLinesFromFullArray(fullItems, null, emittedProvisionalPage ? IDS_STREAM_NEXT_CHUNK_SIZE : IDS_STREAM_FIRST_CHUNK_SIZE, { snapshot: computeIdsStreamSnapshotToken(fullItems) })
-            })()
-
-            return buildIdsStreamResponse(cookie, lineIterator, request, apiLogger)
-        },
-        /**
-         * Retrieves details for a specific daily report.
-         * 指定された日報の詳細情報を取得する。
-         */
-        report: async (url, cookie, request, user, scope) => {
-            const param = url.searchParams.get("reportHubId")
-            const forceRefresh = url.searchParams.get("forceRefresh") === "true"
-            const parsedId = param ? Number.parseInt(param, 10) : NaN
-
-            if (!Number.isFinite(parsedId) || parsedId <= 0) {
-                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid reportHubId" } }, 400)
-            }
-            const detail = await service.getDailyReportDetailByIdByExternalId(scope, parsedId, user.id, { snapshot: true, forceRefresh })
-            if (!detail) {
-                return jsonResponseWithETag(request, cookie, { error: { message: "Report not found" } }, 404)
-            }
-            return jsonResponseWithETag(request, cookie, { report: detail }, 200)
-        },
-    }
-
-    /**
-     * Routes authenticated daily report API requests by endpoint.
-     * エンドポイントごとに認証済みの日報 API リクエストを振り分ける。
-     */
-    const apiLoader = async ({ request, params }: LoaderArgs) => {
-        const { user, cookie } = await authenticate(request, { failureRedirect: null })
-        const sanitizedCookie = cookie ?? null
-
-        if (!user) {
-            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Unauthorized" } }, 401)
-        }
-
-        if (request.method !== "GET") {
-            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Method not allowed" } }, 405)
-        }
-        const endpoint = params.endpoint ?? ""
-        const handler = endpointHandlers[endpoint]
-        if (!handler) {
-            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Unknown endpoint" } }, 404)
-        }
-        const startTime = Date.now()
-        try {
-            const url = new URL(request.url)
-            // 可視集合はリクエストごとに 1 回だけ解決する (キャッシュキーが戻り値に依存する)
-            const scope = await resolveViewerScope(request)
-            return await handler(url, sanitizedCookie, request, user, scope)
-        } catch (error) {
-            const elapsed = Date.now() - startTime
-            const err = error instanceof Error ? error : new Error(String(error))
-            apiLogger.error(`500 endpoint=${endpoint} elapsed=${elapsed}ms name=${err.name} code=${"code" in err ? (err as { code: unknown }).code : "N/A"} message=${err.message}`)
-            apiLogger.error("Stack:", err.stack)
-            return jsonResponseWithETag(request, sanitizedCookie, { error: { message: "Internal Server Error" } }, 500)
-        }
-    }
-
-    /**
-     * Handles data mutations for daily reports.
-     * 日報データの変更操作を処理するアクション。
-     */
-    const apiAction = async ({ request, params }: LoaderArgs) => {
-        const { user, cookie } = await authenticate(request, { failureRedirect: null })
-
-        /**
-         * Builds a JSON response that always carries the session cookie for this request.
-         * 本リクエストのセッション cookie を必ず載せた JSON レスポンスの生成。
-         *
-         * 全分岐 (成功・4xx・未認証) で転送する必要がある。トークン更新の cookie を落とすとブラウザは
-         * 期限切れトークンを持ち続け、以後のリクエストが毎回リフレッシュを試みて収束しない。
-         * 破棄 cookie を落とせば無効セッションがブラウザに残り続ける。個別の `jsonData` へ付け回すと
-         * 必ず取りこぼすため、この関数以外を本ハンドラ内で使わない。
-         *
-         * @param payload Response payload / レスポンス本文
-         * @param init Status override / ステータス指定
-         * @returns JSON response carrying the session cookie / セッション cookie を載せた JSON レスポンス
-         */
-        const respond = (payload: unknown, init?: { status?: number }): Response => jsonData(payload, { ...init, setCookie: cookie })
-
-        if (!user) {
-            return respond({ error: "Unauthorized" }, { status: 401 })
-        }
-
-        // apiAction には外側 try/catch が無く、`respond` を通らない例外 (service / DB / Redis の
-        // 失敗) がハンドラの外へ抜けていた。抜けるとセッション cookie が載らないまま 500 になり、
-        // トークン更新がブラウザへ届かない。apiLoader (:930) と同じ形で包む
-        const actionStartTime = Date.now()
-        try {
-            const endpoint = params.endpoint
-            if (endpoint !== "action") {
-                return respond({ error: "Unknown endpoint" }, { status: 404 })
-            }
-
-            const userId = await service.getUserIdByExternalId(user.id)
-            if (!userId) {
-                return respond({ error: "User not found" }, { status: 404 })
-            }
-
-            // 可視集合はリクエストごとに 1 回だけ解決し、他者の日報に作用する 4 種へ渡す
-            // (create / update / publish / delete / clearCache は所有者・開発者ゲートで別管理)
-            const scope = await resolveViewerScope(request)
-
-            const formData = await request.formData()
-            const intent = formData.get("intent")
-            const reportHubIdRaw = formData.get("reportHubId")
-            const reportHubId = reportHubIdRaw ? Number(reportHubIdRaw) : NaN
-            const businessDate = formData.get("businessDate") as string | null
-            const operationTimestamp = Number(formData.get("operationTimestamp"))
-            const clientTempId = formData.get("clientTempId") as string | null
-
-            if (intent === "clearCache") {
-                // 開発専用アフォーダンス。既定は封鎖 (認証済みなら誰でも全ワーカーの
-                // キャッシュを無制限破棄できてしまうため、注入で明示的に開けた環境のみ許可)
-                if (!config.enableDevCacheClear) {
-                    return respond({ error: "Invalid intent" }, { status: 400 })
-                }
-                await service.clearCache()
-                return respond({ status: "OK", intent: "clearCache" })
-            }
-
-            if (!clientTempId) {
-                return respond({ error: "clientTempId required" }, { status: 400 })
-            }
-
-            if (intent !== "create" && (!reportHubId || Number.isNaN(reportHubId))) {
-                return respond({ error: "Invalid reportHubId" }, { status: 400 })
-            }
-
-            /**
-             * Runs a boolean user-status toggle and maps its outcome onto a response.
-             * 真偽値のユーザー状態トグルを実行し、結果をレスポンスへ写像する処理。
-             *
-             * `toggleStar` と `toggleRead` は必須フィールド名と呼び出すサービスだけが異なるため、
-             * 検証・応答整形・エラー写像をここへ集約する。
-             *
-             * @param intentName Intent echoed back to the client. クライアントへ返す intent 名。
-             * @param fieldName Required boolean form field. 必須の真偽値フォームフィールド名。
-             * @param apply Service call performing the toggle. トグルを実行するサービス呼び出し。
-             * @returns The HTTP response. HTTP レスポンス。
-             */
-            const runStatusToggle = async (intentName: "toggleStar" | "toggleRead", fieldName: "isStarred" | "isRead", apply: (value: boolean) => Promise<{ isStarred: boolean; isRead: boolean }>): Promise<Response> => {
-                const raw = formData.get(fieldName)
-                if (raw === null) {
-                    return respond({ error: `${fieldName} required` }, { status: 400 })
-                }
-                try {
-                    const updatedStatus = await apply(raw === "true")
-                    // クライアントは isStarred/isRead のみ参照する。生内部 ID (userId/created_by/updated_by) を
-                    // 含む行全体は返さず、必要なフラグだけに絞る (内部 ID の自己開示防止)。
-                    return respond({ status: "OK", intent: intentName, updatedStatus: { isStarred: updatedStatus.isStarred, isRead: updatedStatus.isRead }, operationTimestamp, reportHubId: String(reportHubId), clientTempId })
-                } catch (e: unknown) {
-                    // 不可視区分・不存在・削除済みは 404 へ写像する (未捕捉だと 500 になる)
-                    if (e instanceof Error && e.message === "Not Found") {
-                        return respond({ error: "Report not found" }, { status: 404 })
-                    }
-                    throw e
-                }
-            }
-
-            switch (intent) {
-                case "create": {
-                    if (!businessDate) {
-                        return respond({ error: "businessDate required" }, { status: 400 })
-                    }
-                    const newReport = await service.createDailyReport(userId, businessDate, clientTempId)
-                    return respond({
-                        status: "OK",
-                        intent: "create",
-                        report: newReport,
-                        reportHubId: String(newReport.reportHubId),
-                        clientTempId, // Echo back for validation
-                    })
-                }
-                case "update": {
-                    const title = formData.get("title") as string | undefined
-                    const content = formData.get("content") as string | undefined
-                    try {
-                        await service.updateDailyReport(reportHubId, userId, { title, content }, clientTempId)
-                        return respond({ status: "OK", intent: "update", reportHubId: String(reportHubId), clientTempId })
-                    } catch (e: unknown) {
-                        if (e instanceof Error) {
-                            if (e.message === "Unauthorized") {
-                                return respond({ error: "Unauthorized" }, { status: 403 })
-                            }
-                            if (e.message === "Not Found") {
-                                return respond({ error: "Report not found" }, { status: 404 })
-                            }
-                        }
-                        throw e
-                    }
-                }
-                case "publish": {
-                    try {
-                        const publishedReport = await service.publishDailyReport(reportHubId, userId, clientTempId)
-                        return respond({ status: "OK", intent: "publish", reportHubId: String(reportHubId), clientTempId, report: publishedReport })
-                    } catch (e: unknown) {
-                        if (e instanceof Error) {
-                            if (e.message === "Unauthorized") {
-                                return respond({ error: "Unauthorized" }, { status: 403 })
-                            }
-                            if (e.message === "Not Found") {
-                                return respond({ error: "Report not found" }, { status: 404 })
-                            }
-                        }
-                        throw e
-                    }
-                }
-                case "delete": {
-                    try {
-                        await service.deleteDailyReport(reportHubId, userId, clientTempId)
-                        return respond({
-                            status: "OK",
-                            intent: "delete",
-                            reportHubId: String(reportHubId),
-                            clientTempId, // Echo back for validation even on delete
-                        })
-                    } catch (e: unknown) {
-                        if (e instanceof Error) {
-                            if (e.message === "Unauthorized") {
-                                return respond({ error: "Unauthorized" }, { status: 403 })
-                            }
-                            if (e.message === "Not Found") {
-                                return respond({ error: "Report not found" }, { status: 404 })
-                            }
-                        }
-                        throw e
-                    }
-                }
-                case "toggleStar":
-                    return await runStatusToggle("toggleStar", "isStarred", (value) => service.setStarStatus(scope, userId, reportHubId, businessDate, value, clientTempId))
-                case "toggleRead":
-                    return await runStatusToggle("toggleRead", "isRead", (value) => service.setReadStatus(scope, userId, reportHubId, businessDate, value, clientTempId))
-                case "addComment": {
-                    const content = formData.get("content") as string
-                    if (!content) {
-                        return respond({ error: "Content required" }, { status: 400 })
-                    }
-                    try {
-                        const newComment = await service.addComment(scope, userId, reportHubId, content, businessDate, clientTempId)
-                        const safeComment = { ...newComment, userId: newComment.userId }
-                        return respond({ status: "OK", intent: "addComment", newComment: safeComment, reportHubId: String(reportHubId), clientTempId })
-                    } catch (e: unknown) {
-                        if (e instanceof Error) {
-                            // 削除直後の日報への投稿レース等。500 ではなく意味のある状態コードへ写像する
-                            if (e.message === "Not Found") {
-                                return respond({ error: "Report not found" }, { status: 404 })
-                            }
-                            if (e.message.startsWith("Comments are restricted")) {
-                                return respond({ error: "Comments are restricted for this report" }, { status: 403 })
-                            }
-                        }
-                        throw e
-                    }
-                }
-                case "deleteComment": {
-                    const commentId = Number(formData.get("commentId"))
-                    if (!commentId || Number.isNaN(commentId)) {
-                        return respond({ error: "Invalid commentId" }, { status: 400 })
-                    }
-                    try {
-                        await service.deleteComment(scope, userId, reportHubId, commentId, businessDate, clientTempId)
-                        return respond({ status: "OK", reportHubId: String(reportHubId), deletedCommentId: String(commentId), clientTempId })
-                    } catch (e: unknown) {
-                        if (e instanceof Error) {
-                            if (e.message === "Unauthorized") {
-                                return respond({ error: "Unauthorized" }, { status: 403 })
-                            }
-                            if (e.message === "Not Found") {
-                                return respond({ error: "Comment not found" }, { status: 404 })
-                            }
-                        }
-                        throw e
-                    }
-                }
-                default:
-                    return respond({ error: "Invalid intent" }, { status: 400 })
-            }
-        } catch (error) {
-            // React Router のリダイレクト等は握り潰さず素通しする
-            if (error instanceof Response) throw error
-            const elapsed = Date.now() - actionStartTime
-            const err = error instanceof Error ? error : new Error(String(error))
-            apiLogger.error(`500 action elapsed=${elapsed}ms name=${err.name} message=${err.message}`)
-            apiLogger.error("Stack:", err.stack)
-            return respond({ error: "Internal Server Error" }, { status: 500 })
-        }
-    }
-
-    // ---------------- sse (リアルタイム更新) ----------------
-
-    /**
-     * SSE endpoint for real-time daily report updates via Redis Streams.
-     * Redis Streams を使用した日報リアルタイム更新の SSE エンドポイント。
-     */
-    const sseLoader = async ({ request, params }: LoaderArgs) => {
-        // 認証チェック
-        const { user, cookie } = await authenticate(request, { failureRedirect: null })
-        // セッション cookie は**この応答がどれになろうと**転送する。トークンが更新された
-        // リクエストがたまたま SSE 接続だった場合、ここで落とすと更新後のトークンがブラウザへ
-        // 届かず、以降のリクエストが毎回リフレッシュをやり直すことになる。破棄 cookie を
-        // 落とした場合はさらに悪く、無効セッションがブラウザに残り続ける (apiAction と同じ理由)。
-        // SSE は接続が長命なぶん、更新を担うリクエストになりやすい
-        const sessionHeaders = (extra?: Record<string, string>): Record<string, string> | undefined => {
-            if (cookie === undefined) return extra
-            return { ...(extra ?? {}), "Set-Cookie": cookie }
-        }
-        if (!user) {
-            return new Response("Unauthorized", { status: 401, headers: sessionHeaders() })
-        }
-
-        // 内部ユーザー ID の解決
-        const internalUserId = await service.getUserIdByExternalId(user.id)
-        if (!internalUserId) {
-            return new Response("Forbidden", { status: 403, headers: sessionHeaders() })
-        }
-
-        // エンドポイントの検証
-        if (params.endpoint !== "updates") {
-            return new Response("Not Found", { status: 404, headers: sessionHeaders() })
-        }
-
-        // 可視集合は接続時に解決し、以降 keep-alive tick に相乗りして再解決する (D6)。
-        // 接続生存期間で固定すると、権限失効後も本文付きイベントが届き続けてしまう。
-        // ❗ 集合はここで 1 度だけ取り出して保持する。`scope.visible` / `scope.commentable` は
-        //    毎回コピーを返す getter なので、メッセージごとに読むと配信 1 件あたり 2 個の Set を
-        //    確保することになる (共有 Fan-Out の高頻度経路)
-        const initialScope = await resolveViewerScope(request)
-        let visibleSet = initialScope.visible
-        let commentableSet = initialScope.commentable
-        let keepAliveTick = 0
-        let resolveGeneration = 0
-
-        // URL から lastEventId を取得 (再接続時の catch-up 用)
-        // クエリパラメータ優先、EventSource 自動再接続時の Last-Event-ID ヘッダーにフォールバック
-        const url = new URL(request.url)
-        const lastEventId = url.searchParams.get("lastEventId") || request.headers.get("Last-Event-ID")
-
-        const encoder = new TextEncoder()
-        let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null
-        let keepAliveInterval: ReturnType<typeof setInterval> | null = null
-        let unsubscribe: (() => void) | null = null
-        let isCleaningUp = false
-
-        // クリーンアップ処理
-        const cleanup = () => {
-            if (isCleaningUp) return
-            isCleaningUp = true
-
-            // keep-alive タイマー停止
-            if (keepAliveInterval) {
-                clearInterval(keepAliveInterval)
-                keepAliveInterval = null
-            }
-
-            // Fan-Out 購読解除 (entry / error 両リスナーを解除)
-            if (unsubscribe) {
-                unsubscribe()
-                unsubscribe = null
-            }
-
-            // SSE ストリームの終了
-            if (controllerRef) {
-                try {
-                    if (controllerRef.desiredSize !== null) {
-                        controllerRef.close()
-                    }
-                } catch (_e) {
-                    // ストリームが既に閉じている場合は無視
-                } finally {
-                    controllerRef = null
-                }
-            }
-
-            isCleaningUp = false
-        }
-
-        /**
-         * Processes a single Redis Stream entry and sends it to the SSE client.
-         * Redis Stream のエントリを処理し、SSE クライアントに送信する。
-         */
-        /**
-         * Emits a content-free frame that only advances the client's resume anchor.
-         * 内容を伴わず、クライアントの再開アンカーだけを前進させるフレームを送出する処理。
-         *
-         * 種別は `connected` を使う。クライアントは既にこの種別を無視しつつ `lastEventId` を
-         * 更新するため、フィルタで落としたエントリの ID を安全に伝播できる。
-         *
-         * @param entryId Redis Stream entry id. Redis Stream のエントリ ID。
-         * @returns Nothing. なし。
-         */
-        const emitAnchorOnly = (entryId: string): void => {
-            if (controllerRef && controllerRef.desiredSize !== null) {
-                controllerRef.enqueue(encoder.encode(`id: ${entryId}\ndata: ${JSON.stringify({ type: "connected" })}\n\n`))
-            }
-        }
-
-        const processEntry = (entryId: string, fields: Record<string, string>) => {
-            // data フィールドの存在チェック
-            if (!fields.data) return
-
-            try {
-                const raw = JSON.parse(fields.data)
-                const result = dailyReportSseMessageSchema.safeParse(raw)
-                if (!result.success) {
-                    sseLogger.error("SSE message validation failed:", result.error.format())
-                    return // Fail-Closed: 不正なメッセージは送信しない
-                }
-                const parsed = result.data
-
-                // recipientRawUserId によるフィルタリング
-                const recipientRawUserId = typeof raw.recipientRawUserId === "number" ? raw.recipientRawUserId : undefined
-
-                if (parsed.type === "status-update") {
-                    if (recipientRawUserId === undefined || recipientRawUserId !== internalUserId) {
-                        return
-                    }
-                } else if (recipientRawUserId !== undefined && recipientRawUserId !== internalUserId) {
-                    return
-                }
-
-                // 区分の可視性フィルタ (宛先フィルタを通過した後に適用する)
-                if (!isSseMessageSourceTypeVisible(parsed, raw, visibleSet, commentableSet)) {
-                    // ❗ 内容は送らないが、再開アンカーだけは前へ進める。クライアントの
-                    //    `lastEventId` は配信されたイベントでしか更新されないため、落とし続けると
-                    //    アンカーが古いまま固定され、再接続のたびに同じ範囲を読み直す
-                    //    (かつ catch-up の COUNT 上限を超えた分を取りこぼしうる)。
-                    //    `connected` はクライアントが既に無視する種別なので、内容は漏れない
-                    emitAnchorOnly(entryId)
-                    return
-                }
-
-                // コメント次元が拒否する区分なら、埋め込み detail のコメント面だけを空にする
-                const redacted = redactSseReportComments(parsed, raw, commentableSet)
-
-                // recipientRawUserId をクライアントに送信しない (内部 ID 漏洩防止)
-                let sanitizedMessage: string
-                if ("recipientRawUserId" in raw) {
-                    const { recipientRawUserId: _, ...rest } = raw
-                    sanitizedMessage = JSON.stringify(rest)
-                } else if (redacted) {
-                    // ❗ 秘匿したら必ず再直列化する。元の生文字列を送る高速経路のままだと
-                    //    書き換えが捨てられ、コメント本文がそのまま流れる
-                    sanitizedMessage = JSON.stringify(raw)
-                } else {
-                    sanitizedMessage = fields.data
-                }
-
-                // SSE フォーマットで送信 (id フィールド付き)
-                if (controllerRef && controllerRef.desiredSize !== null) {
-                    controllerRef.enqueue(encoder.encode(`id: ${entryId}\ndata: ${sanitizedMessage}\n\n`))
-                }
-            } catch (e) {
-                sseLogger.error(`[SSE:${internalUserId}] processEntry error:`, e)
-            }
-        }
-
-        const stream = new ReadableStream({
-            async start(controller) {
-                // 1. controllerRef 設定
-                controllerRef = controller
-
-                // 2. Keep-Alive: 5 秒ごとにコメントを送信して接続維持
-                keepAliveInterval = setInterval(() => {
-                    try {
-                        if (controllerRef && controllerRef.desiredSize !== null) {
-                            controllerRef.enqueue(encoder.encode(": keep-alive\n\n"))
-                            // 約 60 秒ごと (12 tick) に可視集合を再解決し、権限失効を有界化する。
-                            // 世代ガード: 順序が逆転した古い解決結果で最新を上書きしない
-                            // (上書きすると広い集合へ戻り fail-open 方向に倒れる)。
-                            // resolveVisibleSet 自身が fail-close なので catch は不要
-                            if (++keepAliveTick % SSE_VISIBILITY_REFRESH_TICKS === 0) {
-                                const generation = ++resolveGeneration
-                                resolveViewerScope(request, "refresh").then((next) => {
-                                    if (generation === resolveGeneration) {
-                                        // 両次元の集合を同一スコープから同時に差し替える。
-                                        // 片方だけ更新すると次元間で世代がずれ、失効が半分しか効かない
-                                        visibleSet = next.visible
-                                        commentableSet = next.commentable
-                                    }
-                                })
-                            }
-                        } else {
-                            cleanup()
-                        }
-                    } catch (_e) {
-                        cleanup()
-                    }
-                }, 5000)
-
-                // 3. クライアント切断時のクリーンアップ (全 await の前に登録)
-                request.signal.addEventListener("abort", () => {
-                    cleanup()
-                })
-
-                // catch-up の基準 ID (Fan-Out エントリとの重複排除に使用)
-                let lastProcessedId = lastEventId || "0-0"
-
-                /**
-                 * Fan-Out がライブ配信した最初のエントリ ID。catch-up の重複排除に使う。
-                 *
-                 * ❗ catch-up の判定に `lastProcessedId` を使ってはならない。`xRange` を待つ間に
-                 * ライブエントリが 1 件でも届くと共有の高水位が catch-up 範囲の先まで進み、
-                 * 「既に処理済み」と誤判定して**取得した範囲を丸ごと捨てて**しまう。
-                 * ライブで配ったのは「この ID 以降」だけなので、その境界で判定する。
-                 */
-                let firstLiveEntryId: string | null = null
-
-                // 4. Fan-Out 共有リーダーを購読 (catch-up より先に登録して取りこぼしを防止)
-                unsubscribe = sseReader.subscribe(
-                    (entry: StreamEntry) => {
-                        // catch-up 済みエントリはスキップ (重複排除)
-                        if (isStreamIdLte(entry.id, lastProcessedId)) return
-                        if (firstLiveEntryId === null) {
-                            firstLiveEntryId = entry.id
-                        }
-                        lastProcessedId = entry.id
-                        processEntry(entry.id, entry.message)
-                    },
-                    (err: Error) => {
-                        sseLogger.error(`[SSE:${internalUserId}] Fan-Out reader error:`, err)
-                        cleanup()
-                    },
-                )
-
-                // 5. 初回接続時: 最新 Stream ID を取得して connected の id: に使用
-                // (再接続時は lastEventId が既にあるためスキップ)
-                if (!lastEventId) {
-                    try {
-                        const client = await redis?.getClient()
-                        if (client) {
-                            const latest = await client.xRevRange(streamKey, "+", "-", { COUNT: 1 })
-                            // Fan-Out が既に lastProcessedId を進めている場合は巻き戻さない
-                            if (latest.length > 0 && !isStreamIdLte(latest[0].id, lastProcessedId)) {
-                                lastProcessedId = latest[0].id
-                            }
-                        }
-                    } catch {
-                        /* 取得失敗時は現在の lastProcessedId を維持 */
-                    }
-                }
-
-                // 6. 接続完了通知 (id: 付きで再接続時の catch-up アンカーを提供)
-                if (controllerRef && controllerRef.desiredSize !== null) {
-                    const connectedPayload = `data: ${JSON.stringify({ type: "connected" })}\n\n`
-                    const sseMessage = lastProcessedId !== "0-0" ? `id: ${lastProcessedId}\n${connectedPayload}` : connectedPayload
-                    controllerRef.enqueue(encoder.encode(sseMessage))
-                }
-
-                // 7. catch-up: lastEventId が指定されている場合、それ以降のエントリを一括取得
-                if (lastEventId) {
-                    try {
-                        const client = await redis?.getClient()
-                        if (client) {
-                            const catchUpEntries = await client.xRange(streamKey, lastEventId, "+", { COUNT: 1000 })
-                            for (const entry of catchUpEntries) {
-                                // xRange は inclusive なので lastEventId 自身はスキップ
-                                if (entry.id === lastEventId) continue
-                                // Fan-Out がライブ配信した境界以降は重複するのでスキップ。
-                                // 共有の高水位ではなくこの境界で判定することで、await 中に届いた
-                                // ライブ 1 件が catch-up 範囲全体を捨てさせる事故を防ぐ
-                                if (firstLiveEntryId !== null && isStreamIdLte(firstLiveEntryId, entry.id)) continue
-                                // 高水位は後退させない (ライブが先行している場合がある)
-                                if (!isStreamIdLte(entry.id, lastProcessedId)) {
-                                    lastProcessedId = entry.id
-                                }
-                                processEntry(entry.id, entry.message as Record<string, string>)
-                            }
-                        }
-                    } catch (e) {
-                        sseLogger.error(`[SSE:${internalUserId}] catch-up xRange error:`, e)
-                        // catch-up 失敗時は Fan-Out のみで継続
-                    }
-                }
-            },
-            cancel() {
-                cleanup()
-            },
-        })
-
-        return new Response(stream, {
-            headers: sessionHeaders({
-                "Content-Type": "text/event-stream",
-                "Cache-Control": "no-cache, no-transform",
-                Connection: "keep-alive",
-            }),
-        })
-    }
-
-    // ---------------- attachment (認可済みバイト配信) ----------------
-
-    /**
-     * Streams an authorized attachment's bytes to the client.
-     * 認可済みの添付ファイルをバイト列としてクライアントへ返すローダー。
-     *
-     * 認可は `service.getAttachmentForUser` の SQL 述語で完結させる。ストレージ側の
-     * 資格情報はサービス共通のものであり、利用者間の分離を一切提供しない。
-     * したがってこの述語が唯一の認可境界であり、ここに欠陥があれば全テナント横断の読み取りになる。
-     *
-     * 「存在しない」と「認可されない」は区別せず 404 にする (存在オラクル回避)。
-     *
-     * 本体は必ず try/catch で包む。ここで漏らした例外はフレームワークの最終防衛線に落ち、
-     * JSON ではないプレーンテキストの 500 になるうえ `Set-Cookie` (セッション延長) も失われる。
-     * **認証ポートの呼び出しも try の内側**に置くこと。認証実装はセッション復号や warmup の
-     * 失敗で素の例外を投げうるため、外に置くと同じ穴が残る。ただしリダイレクトは `Response` を
-     * throw する正常な制御フローなので、catch では素通しする。
-     */
-    const attachmentLoader = async ({ request, params }: LoaderArgs) => {
-        let sanitizedCookie: string | null = null
-
-        /** エラー応答。`Set-Cookie` はすべての分岐で伝播させる。 */
-        const fail = (status: number, message: string, retryAfterSeconds?: number): Response => {
-            const headers = new Headers({ "Content-Type": "application/json" })
-            if (retryAfterSeconds !== undefined) headers.set("Retry-After", String(retryAfterSeconds))
-            if (sanitizedCookie) headers.append("Set-Cookie", sanitizedCookie)
-            return new Response(JSON.stringify({ error: { message } }), { status, headers })
-        }
-
-        try {
-            const { user, cookie } = await authenticate(request, { failureRedirect: null })
-            sanitizedCookie = cookie ?? null
-
-            if (!user) return fail(401, "Unauthorized")
-            if (request.method !== "GET" && request.method !== "HEAD") return fail(405, "Method not allowed")
-
-            const codec = config.attachmentIdCodec
-            const readAttachment = config.readAttachment
-            // ポート未注入は「この配備に添付機能が無い」であり、認可失敗と区別しない
-            if (!(codec && readAttachment)) return fail(404, "Attachment not found")
-
-            const token = params.token ?? ""
-            const attachmentId = codec.decode(token)
-            // `Number.isSafeInteger` であること。可逆難読化は入力トークンの正準性を検証しないため、
-            // 正規トークンと同じ長さの入力から 2^53 を超える値が復号されうる。それを SQL パラメータへ
-            // 渡すとドライバーの範囲検証が TypeError を投げ、400 のはずが 500 になる。
-            if (attachmentId === null || !Number.isSafeInteger(attachmentId) || attachmentId <= 0) {
-                return fail(400, "Invalid attachment token")
-            }
-
-            const internalUserId = await service.getUserIdByExternalId(user.id)
-            if (!internalUserId) return fail(403, "Forbidden")
-
-            // レート制限。トークンは列挙可能なので、これが実効的な唯一の緩和策
-            if (!consumeAttachmentRateToken(internalUserId, Date.now())) {
-                attachmentLogger.error(`429 attachment=${attachmentId} viewer=${internalUserId} reason=rate_limit`)
-                return fail(429, "Too many requests", RATE_LIMIT_RETRY_AFTER_SECONDS)
-            }
-
-            // 認可判定 (SQL 側で完結)。null は「存在しない」「認可されない」「親が論理削除済み」の合流
-            // 可視集合はこの try の内側で解決する (例外封じ込め規約の維持)
-            const scope = await resolveViewerScope(request)
-            const attachment = await service.getAttachmentForUser(scope, attachmentId, internalUserId)
-            if (!attachment) {
-                attachmentLogger.error(`404 attachment=${attachmentId} viewer=${internalUserId} reason=not_visible`)
-                return fail(404, "Attachment not found")
-            }
-
-            // DB が既知サイズを持つ場合は読み取り前に弾く (サイズを報告しない取込元の行はここを通過する)
-            if (attachment.fileSize != null && attachment.fileSize > attachmentMaxBytes) {
-                attachmentLogger.error(`413 attachment=${attachmentId} viewer=${internalUserId} reason=db_size`)
-                return fail(413, "Attachment too large")
-            }
-
-            if (!attachmentGate.tryAcquire()) {
-                attachmentLogger.error(`503 attachment=${attachmentId} viewer=${internalUserId} reason=concurrency`)
-                return fail(503, "Too many concurrent downloads", CONCURRENCY_RETRY_AFTER_SECONDS)
-            }
-
-            // スロットの解放は冪等にする。早期 return・例外・送出完了のどの経路からでも
-            // ちょうど 1 回だけ返す必要がある
-            let gateReleased = false
-            const releaseGate = () => {
-                if (gateReleased) return
-                gateReleased = true
-                attachmentGate.release()
-            }
-            // 本文の送出完了まで保持する経路に入ったかどうか (入った場合のみ finally での解放を見送る)
-            let releaseDeferredToStream = false
-
-            try {
-                const isHead = request.method === "HEAD"
-                const result = await readAttachment(attachment.filePath, { maxBytes: attachmentMaxBytes, head: isHead, principal: encodeUserId(internalUserId) })
-
-                if (!result.ok) {
-                    const status = attachmentFailureToStatus(result.reason)
-                    // 実体消失は次回描画へ反映する。記録の失敗は配信結果に影響させない
-                    // (await しないので、拒否を捕まえないと未処理 Promise 拒否になる)
-                    if (result.reason === "not_found") {
-                        void service.markAttachmentMissing(attachmentId).catch((error: unknown) => {
-                            attachmentLogger.error(`markAttachmentMissing failed attachment=${attachmentId} message=${error instanceof Error ? error.message : "unknown"}`)
-                        })
-                    }
-                    // file_path / URI は絶対にログへ出さない (内部パス非露出の方針と整合させる)
-                    attachmentLogger.error(`${status} attachment=${attachmentId} viewer=${internalUserId} reason=${result.reason} code=${result.code ?? "-"}`)
-                    return fail(status, ATTACHMENT_FAILURE_MESSAGES[status] ?? "Attachment storage unavailable")
-                }
-
-                // インライン許可リスト外は宣言型ごと octet-stream へ落とす。構文検証だけでは
-                // text/html や image/svg+xml の自オリジン実行を止められない
-                const declared = sanitizeMediaType(attachment.fileType) ?? sanitizeMediaType(result.contentType) ?? "application/octet-stream"
-                const inlineSafe = INLINE_SAFE_MEDIA_TYPES.has(declared)
-                const wantsDownload = new URL(request.url).searchParams.get("download") === "1"
-                const contentType = inlineSafe ? declared : "application/octet-stream"
-                const disposition = inlineSafe && !wantsDownload ? "inline" : "attachment"
-
-                // HEAD は本体を読まないので `bytes` が空になる。RFC 9110 §9.3.2 が要求する
-                // 「GET と同じ Content-Length」を満たすため、ポートが申告した実サイズを優先する
-                const contentLength = result.size ?? result.bytes.byteLength
-                const headers = new Headers({
-                    "Content-Type": contentType,
-                    "Content-Length": String(contentLength),
-                    "Content-Disposition": `${disposition}; filename="${asciiFallbackFileName(attachment.fileName)}"; filename*=UTF-8''${encodeRfc8187(attachment.fileName)}`,
-                    "Cache-Control": "private, no-store",
-                    "X-Content-Type-Options": "nosniff",
-                    "Content-Security-Policy": "default-src 'none'; sandbox",
-                    "X-Frame-Options": "SAMEORIGIN",
-                })
-                if (sanitizedCookie) headers.append("Set-Cookie", sanitizedCookie)
-
-                // 実体を確認できたので消失記録を解除する。これが唯一の自動回復経路であり、
-                // 片方向のままだと一時障害で立った absent を利用者が自力で戻せない
-                // (UI は absent の添付にリンクを描画しないため再取得の手段が消える)
-                void service.markAttachmentPresent(attachmentId).catch((error: unknown) => {
-                    attachmentLogger.error(`markAttachmentPresent failed attachment=${attachmentId} message=${error instanceof Error ? error.message : "unknown"}`)
-                })
-
-                attachmentLogger.info(`200 attachment=${attachmentId} viewer=${internalUserId} type=${contentType} disposition=${disposition} bytes=${contentLength}`)
-                // HEAD は本文を持たないので即座に解放する。GET は送出完了まで保持し、
-                // 「同時実行上限 × 上限バイト数」というヒープ見積りを実際に成立させる
-                if (isHead) {
-                    return new Response(null, { status: 200, headers })
-                }
-                releaseDeferredToStream = true
-                return new Response(streamAndRelease(result.bytes, releaseGate, ATTACHMENT_BODY_FLUSH_TIMEOUT_MS), { status: 200, headers })
-            } finally {
-                // 送出へ引き渡した場合を除き、早期 return でも例外でも必ずここで返す
-                if (!releaseDeferredToStream) releaseGate()
-            }
-        } catch (error) {
-            // 認証ポートはリダイレクトを Response として throw する。これは正常な制御フローなので素通しする
-            if (error instanceof Response) throw error
-            attachmentLogger.error(`500 attachment=? viewer=? reason=unexpected message=${error instanceof Error ? error.message : "unknown"}`)
-            return fail(500, "Attachment request failed")
-        }
-    }
-
-    return {
-        index: { loader: indexLoader },
-        api: { loader: apiLoader, action: apiAction },
-        sse: { loader: sseLoader },
-        attachment: { loader: attachmentLoader },
-    }
-}