eval: benchmark graph retrieval on real Li+ corpus

[lipluscodex]

目的

実際の Li+ D1 コーパス上で、Neuron Graph RAG のグラフ統合検索が通常の hybrid 検索より有用かを、再現可能な gold-query benchmark で検証する。順位改善だけでなく、説明経路の正しさと success feedback による局所強化・非対象汚染も観測し、結果が改善でも不改善でもそのまま保存する。

前提

• 現在の python -m neuron_graph_rag eval は 5 文書・3 query の機構確認用 smoke test であり、README も一般的な検索品質を保証しないと明記している。
• issue test-data: acquire a D1 corpus fixture for NGR validation #7 / PR test-data: acquire D1 corpus fixture #8 により、本番 D1 search_docs / doc_edges から read-only・決定論的に fixture と provenance を生成できる。
• search_docs を文書の正本、doc_edges を Decision Structure の関係正本として扱う。D1 は損失あり検索 snapshot であり、GitHub を byte-exact history の正本とする。
• 既定 dense encoder は learned semantic embedding ではないため、今回の結果は現行 MVP 構成の評価であり、一般的な embedding 品質へ外挿しない。
• benchmark は結果を見た後に gold target や cohort を都合よく変更しない。契約変更が必要なら変更理由と変更前後の結果を分離して残す。

検証仮説

1. relation-dependent query では、graph-integrated retrieval が baseline hybrid より期待 node の順位を改善できる。
2. direct-lookup / negative-control query では、graph 統合が無関係な node を過度に押し上げない。
3. relation-dependent query の上位説明経路が、gold edge type と endpoint に一致する。
4. success feedback は credited path の edge だけを強化し、非対象 query / edge を汚染しない。

制約

• public Li+ corpus から、小さく決定論的な evaluation fixture を生成する。完全 D1 export は commit しない。
• gold query は少なくとも 12 件とし、direct_lookup、relation、negative_control の各 cohort を含める。各 case に query、期待 node、許容 rank、期待 path / edge type（該当時）、根拠となる source URL を保持する。
• relation case は少なくとも 2 種類の関係パターンを含め、同じ2 nodeの言い換えだけで件数を水増ししない。
• baseline と graph を同じ corpus・encoder・query で比較し、全体および cohort 別の MRR、Hit@3、rank delta、改善 / 同値 / 悪化件数を出す。
• explanation verification は score だけでなく、期待 endpoint と edge type を検査する。
• feedback 前後で、変更された edge weight、関連 case の rank、非対象 cohort の rank を記録する。強化対象外 edge の変更は失敗とする。
• 品質指標を CI green のために閾値調整しない。CI は benchmark の決定性、gold schema、provenance、metric 計算、経路検査、feedback isolation を検証し、観測された品質結果は JSON / docs に固定する。
• D1 取得は単一 SELECT / WITH、rows_written=0 / changes=0 / changed_db=false、credential redaction、schema fingerprint の既存契約を維持する。
• MCP adapter / remote deployment は本 issue の範囲外とする。

想定変更箇所

• tools/ - connected evaluation corpus の read-only 選択と benchmark 実行
• tests/fixtures/ - compact evaluation fixture、provenance、gold query
• src/neuron_graph_rag/ - 必要な場合のみ汎用 eval 集計。データ源固有処理は core へ入れない
• tests/ - metric、path、determinism、feedback isolation の検証
• docs/requirements.md - 実コーパス評価契約
• docs/ / README.md - 実行方法、観測結果、適用限界

完了条件

• benchmark がローカルと CI で再現可能に実行され、baseline / graph / feedback 後の機械可読結果を生成する。
• gold source と fixture provenance を監査できる。
• relation、direct lookup、negative control の結果を分けて報告する。
• 観測結果について「支持 / 不支持 / 判定不能」を仮説ごとに記録し、不支持でもテストを改変して隠さない。