5. 文書のバイト数を索引に記録する

• Status: accepted
• Date: 2026-08-15
• Deciders: プロジェクトオーナー
• Applies to: v0.23.0

背景と課題

ADR-0004 は「resource の read は索引で縛る」と決め、したがって resources/list は read が受け付ける ものだけを提示する必要があるとした。同時に、その性質が成り立っていない箇所を 1 つ記録している:

GET_DOCUMENT_MAX_BYTES (テキスト 1 MiB) を超える文書は、索引が 50 MiB まで 受け入れるので索引され、read で拒否される。これは知り得るが、知るには listing のたびに索引済みファイルを全部 stat するしかない […] 恒久的な修正は index 時に size を記録するか、2 つの cap を揃えるかで、それまでは既知の 制限であって主張ではない。

つまり 1 MiB〜50 MiB の Markdown / プレーンテキスト文書は、索引され、topic の 一覧に現れ、search hit に uri が付き、クライアントがそのリンクを辿ると 拒否される。バイナリ形式は影響を受けない — 50 MiB の cap で読まれ、抽出 テキストは拒否ではなく注記付きで切り詰められる (ADR-0004 で扱い済み)。

今この問いに答えなければならない理由は無かった。答える時機にしたのは kb-mcp doctor を足すからで、どちらも「索引が自分自身について何を知っているか」 の話であり、後回しにすると同じテーブルに 2 回目の migration をかけることになる。

決定要因

• ADR-0004 の原則 —「提示は索引の性質である」— は争点ではない。穴を塞ぐ手段は それを維持するものでなければならず、取引材料にしてはならない
• この穴は現実には測定にかからない (参照コーパス 666 件中 0 件が cap に届く)。 だからコストが問題になる: 通常経路を遅くしてはいけない
• 既存の索引はそのまま動き続けること。以前のリリースで索引した KB に、使い続ける ために再 embed を要求してはならない
• listing と search の uri は一緒に変わること。2 つの面が 1 つの問いに 答えているのに、共有述語を通っていたのは片方だけだった

検討した選択肢

1. listing のたびに索引済みファイルを全部 stat する — ADR-0004 が名指しして 退けた案
2. 2 つの cap を揃える — read が返せる量を超えるテキストは索引しない
3. index 時に byte size を documents に記録し、提示判定の述語で使う

決定

選択肢 3。

選択肢 1 は「提示」を索引の性質からその場の filesystem 探査へ変えるもので、 これはまさに ADR-0004 が引いた境界そのもの。しかも穴は塞がらない — listing と read の間にファイルが cap を跨げるため。

選択肢 2 は最悪の方向に後方非互換になる。GET_DOCUMENT_MAX_BYTES = 1 MiB は 索引とは無関係な理由 —「1 レスポンスで MCP クライアントに渡してよいテキスト量」— で決まっているので、揃えるとは索引側の上限をそこまで下げること。今日索引され 検索できている文書が黙って索引されなくなる。長いという理由で文書を落とす検索系は、 見つけた上で全文の inline を断る検索系より悪い。

選択肢 3 は ADR-0004 を保つ: size が「索引が知っていること」の一部になるので、 提示は索引についての言明のままでいられる。コストは nullable な列 1 つと、 最小の read cap を超える行だけを問い合わせるクエリ 1 本 — cap 超えの文書が 無いコーパスでは 0 行が返る。

ServableRules が resources/list と search hit の uri の両方の背後にある 唯一の述語になった。拡張子ごとの cap は max_bytes_for で当てる — load_document_blocking が read_checked に渡すのと同じ chooser なので、 listing と read が別々の上限を持つことは構造的に起きない。この変更前は 2 つの面が registry 判定を別々に呼んでおり、述語が 1 つの呼び出しである間だけ無害だった。 片方に条件を 1 つ足した瞬間に、search が resources/read の拒むリンクを 配ることになる。

帰結

• documents に size_bytes INTEGER (nullable) が増える。既存 DB には open 時に 追加される (他の forward migration と同じ)
• NULL は「未記録」であって 0 ではなく、NULL は提示される。本リリース以前に 書かれた索引の全行がこの状態で始まるので、未知を「大きすぎる」と読むと、 再 index せずに上げた人の resources/list が空になる。安全に見える側の解釈が 破壊的という位置
• size は documents 行を書くあらゆる箇所で書かれる。バイトは変わったが chunk は 変わらなかった frontmatter-only の更新経路も含む
• index 実行は「飛ばした文書」を backfill する。rebuild_index は content hash が 一致するファイルに Unchanged を返し、その経路は document 行を一切書かない。 つまり「2 つの書き込み経路からしか書かない migration」は、それが書かれた対象で ある「何も変わっていない KB」でこそ決して走らない。backfill は代わりに disk scan から読み (backfill_fts の隣)、WHERE size_bytes IS NULL が実 read の記録した size を上書きしないよう守る
• read cap を超えるテキスト文書は resources/list から消え、topic 本文からも消え、 search hit に uri が付かなくなる。hit そのものは残る — 未登録拡張子と まったく同じ扱いで、文書は見つかり続け、拒否される read へのリンクだけが付かない
• テキスト cap を超えるバイナリ文書は提示され続ける。read が拒否ではなく 切り詰めるため。両者を分けるのは拡張子ごとの cap で、それは read と同じ関数から来る
• 索引 cap を超えて成長したファイルは、拒否すると同時に新しい size を記録する。 そのファイルは skip され、skip は意図的に行を保持するので、これが無いと記録済み size は「最後に索引できた時」の小さい値のまま残り、disk 上のファイルはどの read も 返せない大きさになる。これが知り得る側に属するのは明確な理由による: kb-mcp はそれを拒否するために直前に stat している。答えを持っていて捨てていた。 full index と watcher の両方が書く — 片方を他方の次回実行に任せるのが、 この feature がまさに扱っている drift だから
• 依然として約束しないものは ADR-0004 から変わらない: その場の条件による拒否 (索引後に削除された / hard link が上書きされた / listing と read の間に成長した) は listing には知りようがない。どちら側かを決めるのは「kb-mcp が測ったかどうか」
• kb-mcp doctor が「cap を超える文書」と「size 未記録の文書」の両方を報告するので、 この migration が作る状態は黙って残らず可視になる