chore(fts): enrich D1 upsert failure logs to surface root cause (#135)

[liplus-lin-lay]

概要

processAndUpsertCommitDiff の FTS5 upsert 失敗時に出ているログ (Failed to upsert FTS5 row for diff ...) が ftsErr.message のみで根本原因が特定できないため、構造化詳細行を追加する観測強化 PR。

選択肢

#135 が提示している 2 候補のうち Option B (log enrichment) を選択。

理由:

• 現状ログから D1 側の具体エラー型 (D1_ERROR / SQLITE_CORRUPT_VTAB / その他) が判別できない
• cross-repo かつ diff のみという発生パターンは強い signal だが、コードリーディングだけでは根本原因 (trigram tokenizer 限界 / content size / 特殊バイト / 過去の VTAB corruption 再発 など仮説複数) を一意に決められない
• Option A (ノーエビデンスでの推測修正) はリスクが高く最小修正の原則から外れる
• bug(fts): D1 FTS5 upsert failures observed for diff rows across all repos #135 自体「first step として log enrichment」と明示

変更内容

src/pipeline.ts の diff 用 FTS5 upsert catch ブロック 1 箇所のみ:

• 既存の "Failed to upsert FTS5 row for diff ..." 行は検索性のため温存
• 新規 FTS5 diff upsert detail (#135): 行を追加し、JSON で以下を出力:
  • errorName (Error.name / typeof — D1_ERROR か他か判別)
  • vectorId (該当 SHA-256 base64url ID)
  • tokenizerKind: "code" (trigram 仮説の確認用)
  • contentChars (8000 上限近接かどうか)
  • filePathChars (path 長さ仮説)
  • fileStatus (added/modified 等 status との相関)
  • commitSha, repo

diff stat: src/pipeline.ts | 16 ++++++++++++++++ 1 file, +16/-0.

検証

• npx tsc --noEmit exit 0 (型エラーなし)
• 他のサーフェス (issue / release / doc / wiki / comment / review) の FTS5 catch は手付かず — diff 経路のみ失敗が観測されているため scope 最小化

後続

このログが次回以降の cron 実行で蓄積されたあと、別 issue/PR で root-cause fix を行う。issue #135 はそれまで open のまま (Refs #135、Closes ではない)。

実行モード

auto mode、AI 自律 self-review 経由で merge。--auto flag は付けない (operations.md auto mode rule に準拠)。

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	github-rag-mcp	90ae0ac	Apr 27 2026, 09:54 AM

[liplus-lin-lay]

Self-review (auto mode)

Option choice & reasoning

選択: Option B (log enrichment) — #135 が first step として明示している経路。
理由:

• コードリーディングだけでは根本原因仮説が複数残る (trigram tokenizer 限界 / content size / 特殊バイト / VTAB corruption 再発)
• D1 側エラーの具体型 (D1_ERROR / SQLITE_*) が現状ログから読み取れず、推測修正のリスクが高い
• 観測フェーズを 1 cron 走らせれば仮説を 1〜2 個に絞れる

Files touched & scope minimality

src/pipeline.ts 1 ファイル, +16 行, -0 行。
diff 経路の catch ブロック 1 箇所のみ修正。issue / release / doc / wiki / comment / review の FTS5 catch は意図的に手付かず — 失敗観測は diff のみのため scope を広げない。

Risk assessment

回帰リスク: 極小。

• 振る舞い変化なし (catch ブロック内の console.error 1 行追加のみ)
• 例外フロー変更なし (re-throw も swallow 解除もしていない)
• 成功パスは未変更
• ログ量増加: 失敗時 1 行 → 2 行。失敗が常時発生している現状なら出力量は倍増だが、根本原因特定までの一時負担として許容範囲

ログ PII リスクなし (commitSha / repo は public、filePathChars / contentChars は数値、errorName は型名のみ)。

Verification path (open question)

このコード変更自体の verify は tsc --noEmit で完結 (exit 0 確認済) だが、ログ強化の効果検証 は merge 後 deploy + 次回 :30 cron 実行の構造化ログ出現を待つ必要がある:

• merge → Workers Builds 自動 deploy
• 次回 :30 UTC cron 実行 (pollDiffs) で diff upsert が発生
• Cloudflare Workers Observability で FTS5 diff upsert detail (#135): 行を観測
• 取得できた errorName / contentChars / fileStatus 分布から根本原因仮説を絞り込み、後続 PR で root-cause fix

#135 は本 PR では Refs に留める。root-cause fix の後続 PR が Closes #135 を担当する。

CI status

Workers Builds: github-rag-mcp SUCCESS、test IN_PROGRESS (lint/typecheck 系)。merge gate は CI 完了待ち。

Verdict

Approve for merge (auto mode self-review)。