eval: benchmark graph retrieval on real Li+ corpus

README.md

@@ -108,6 +108,20 @@ python -m neuron_graph_rag eval
 
 取得 tool は D1 の単一 `SELECT / WITH` だけを許可し、Wrangler が `rows_written=0` を返したことを query ごとに検証します。認証、再取得、schema fingerprint、coverage、既知 gap、完全性の限界は [docs/d1-corpus-fixture.md](docs/d1-corpus-fixture.md) を参照してください。
 
+## Real-corpus benchmark
+
+`tests/fixtures/d1_liplus_benchmark.json` と `.gold.json` は、12 wiki node の connected fixture と、結果を見る前に固定した 12 query（direct lookup / relation / negative control 各4件）です。
+
+```bash
+python -m neuron_graph_rag benchmark \
+  --fixture tests/fixtures/d1_liplus_benchmark.json \
+  --gold tests/fixtures/d1_liplus_benchmark.gold.json
+```
+
+同一 corpus・encoder・query 上の baseline / graph の MRR、Hit@3、rank delta に加え、one-hop / two-hop の説明経路と success feedback の局所性を検査します。品質結果は CI 合格条件にせず、固定 JSON と [観測記録](docs/real-corpus-benchmark.md) に支持・不支持・判定不能をそのまま残します。
+
+初回観測では relation 改善と説明経路・feedback isolation は支持されましたが、negative control の2件が悪化したため非対象の過剰押し上げ仮説は不支持でした。詳細値と適用限界は観測記録を参照してください。
+
 ## Public API
 
 ```python
@@ -183,6 +197,7 @@ MCP 対応 AI との接続は、コアへ MCP SDK を追加せず、同一 repos
 - reinforcement は credit assignment の最小実装として、成功結果の最大寄与経路を選びます。
 - graph propagation は決定論的な重み付き探索であり、GNN 学習ではありません。
 - eval corpus は機構確認用の小規模 fixture であり、一般的な retrieval 品質を保証しません。
+- real-corpus benchmark も learned semantic embedding ではない現行 MVP 構成だけを評価し、Li+ D1 は損失あり snapshot であるため一般的な corpus / embedding 品質へ外挿できません。
 
 受け入れ要件の詳細は [docs/requirements.md](docs/requirements.md) にあります。
 

docs/d1-corpus-fixture.md

@@ -38,6 +38,8 @@ python tools/acquire_d1_fixture.py `
 
 選択順は `(repo, type, updated_at, vector_id)` で固定する。同一 snapshot と引数から fixture JSON は byte-identical になる。取得時刻は provenance report だけに置く。credential らしい文字列は、node / edge だけでなく source 引数と既知 gap を含む最終 fixture / provenance 全体で `[REDACTED_SECRET]` へ決定論的に置換する。fixture、provenance、合計の置換件数を report に残す。
 
+評価用 connected fixture は `--doc-path` を反復指定し、単一 repository の `wiki_doc` を `(repo, type, doc_path, vector_id)` 順で取得する。`--require-connected` は `doc_edges` を無向に見た時に全 node が接続されていなければ出力前に失敗する。SQL guard は quoted literal 内の語を命令として解釈せず、literal 外の write / administration keyword は従来どおり拒否する。
+
 完全 export や作業中の raw JSON は commit しない。`.gitignore` は `*.d1-export.json`、`artifacts/d1/`、`tests/fixtures/.full-*` を除外する。
 
 ## Provenance と coverage 監査

docs/real-corpus-benchmark.md

@@ -0,0 +1,62 @@
+# Real-corpus benchmark
+
+## 目的
+
+実際の Li+ D1 corpus 上で、現行 NGR MVP の graph-integrated retrieval が baseline hybrid より有用かを再現可能に観測する。順位だけでなく、説明経路と success feedback の局所性を同じ固定契約で検査する。
+
+## 固定入力
+
+- fixture: `tests/fixtures/d1_liplus_benchmark.json`
+- provenance: `tests/fixtures/d1_liplus_benchmark.provenance.json`
+- gold: `tests/fixtures/d1_liplus_benchmark.gold.json`
+- 12 wiki node / 26 `mention` edge の弱連結 graph
+- provenance の `known_gaps` は空配列。取得対象は `wiki_doc` だけであり、取得時点でこの固定 subset に関係する未解消 gap はない
+- direct lookup / relation / negative control 各4件
+- relation は独立した endpoint 組の one-hop 2件と two-hop 2件
+- baseline は `entry_weight=1.0`、`graph_weight=0.0`
+- graph は既存 smoke eval と同じ `entry_weight=0.25`、`graph_weight=0.75`
+- 両者とも同じ feature-hashing encoder、`seed_count=1`、`max_hops=2`
+
+fixture の node 集合、gold query、許容 rank、期待 path、判定規則は品質結果を見る前に固定する。結果を見た後に変更が必要になった場合は、旧契約と旧結果を残し、別 version として理由を記録する。
+
+初回観測後の provenance 再監査でも fixture SHA-256 は `b3b305aabb57803c2782c3998215e1cbcf9b5e6cdef0f641abc98520d4400cf9`、gold SHA-256 は `a10af7a1a4ec5f0ef66a228b05e14fe0160e4ff5f9b3209073f38fdb90028c71` のまま byte-identical だった。再監査では、wiki-only capture と無関係な diff tracker を `known_gaps` から除き、取得時点で関連する未解消 gap だけを記録する #7 の契約へ戻した。freeze commit `befe245` と初回 result は変更していない。
+
+## 仮説判定
+
+- H1: relation MRR が上昇し、改善件数が悪化件数を上回れば支持。逆条件なら不支持、それ以外は判定不能。
+- H2: direct / negative-control がすべて許容 rank 内で悪化ゼロなら支持。許容外または2 rank以上の悪化があれば不支持、それ以外は判定不能。
+- H3: 全 relation case で固定 endpoint / edge type の完全な path が説明に存在すれば支持。一件でも欠ければ不支持。
+- H4: credited edge が1本以上変化し、credited 外 edge と非対象 case rank が不変なら支持。汚染があれば不支持、edge 変化がなければ判定不能。
+
+## 実行
+
+```bash
+python -m neuron_graph_rag benchmark \
+  --fixture tests/fixtures/d1_liplus_benchmark.json \
+  --gold tests/fixtures/d1_liplus_benchmark.gold.json \
+  --output tests/fixtures/d1_liplus_benchmark.result.json
+```
+
+CI は gold schema、fixture / provenance、metric 計算、path 照合、feedback isolation、固定 result の再生成一致を検証する。観測品質の数値自体は CI 合格閾値にしない。
+
+## 観測結果
+
+gold / fixture / 判定規則を commit `befe245` で固定した後に初回実行した。機械可読な全結果は `tests/fixtures/d1_liplus_benchmark.result.json` に保存する。
+
+| cohort | baseline MRR | graph MRR | baseline Hit@3 | graph Hit@3 | 改善 / 同値 / 悪化 |
+|---|---:|---:|---:|---:|---:|
+| direct lookup | 1.0000 | 1.0000 | 1.0000 | 1.0000 | 0 / 4 / 0 |
+| relation | 0.2583 | 0.3833 | 0.5000 | 0.7500 | 3 / 1 / 0 |
+| negative control | 1.0000 | 0.7083 | 1.0000 | 1.0000 | 0 / 2 / 2 |
+| overall | 0.7528 | 0.6972 | 0.8333 | 0.9167 | 3 / 7 / 2 |
+
+- H1: **支持**。relation は3件改善・0件悪化で、MRR と Hit@3 が上昇した。
+- H2: **不支持**。negative-configuration は rank 1 → 3、negative-installation は rank 1 → 2 に悪化した。両方とも許容 rank 3 内だが、事前規則の「悪化ゼロ」を満たさず、前者は2 rank 悪化の不支持条件にも該当する。
+- H3: **支持**。one-hop 2件と two-hop 2件の全4件で、固定した endpoint / `mention` path が説明に存在した。
+- H4: **支持**。`1.-Model` → `2.-Evolution` の credited `mention` edge だけが weight 1.0 → 1.14 に変化した。非 credited edge と非対象 case rank は不変だった。対象 case 自体の rank は2 → 2であり、強化は起きたが即時 rank 改善は観測されなかった。
+
+relation cohort では graph 統合の有用性が観測された一方、negative control の悪化により overall MRR は低下した。したがって「graph 統合は常に baseline より良い」という結論は支持しない。
+
+## 適用限界
+
+D1 は content truncation と diff 欠損を含み得る損失あり検索 snapshot であり、GitHub が byte-exact history の正本である。既定 dense encoder は learned semantic embedding ではない。この結果は固定した public Li+ subset と現行 MVP 構成の評価であり、一般的な corpus、embedding、GraphRAG 実装へ外挿しない。

docs/requirements.md

@@ -38,6 +38,11 @@
 20. `search_docs.vector_id / content` を node ID / text へ、`doc_edges` の両端と `edge_kind` を typed edge へ変換し、欠損 endpoint は node を捏造せず除外理由を記録できる。
 21. D1 取得は単一 SELECT / WITH query のみに制限し、各 query の `rows_written=0`、`changes=0`、`changed_db=false` を検証できる。
 22. fixture と分離した provenance report に schema fingerprint、coverage、取得時刻、取得時点で未解消の既知 gap、redaction 件数を記録し、再取得前後の count / commit / 最新時刻を比較できる。未解消の既知 gap がない場合は空配列を記録する。
+23. 実 D1 の明示的な wiki doc path 集合から、弱連結で決定論的な評価 fixture を生成できる。gold case と品質結果を見た後に選択集合を変更しない。
+24. 12 件以上の gold query を direct lookup、relation、negative control に分け、query、期待 node、許容 rank、source URL、relation 時の期待 endpoint / edge type を保持できる。
+25. baseline hybrid と graph-integrated retrieval を同一 corpus、encoder、query で実行し、全体・cohort 別の MRR、Hit@3、rank delta、改善・同値・悪化件数を機械可読に出力できる。
+26. relation の説明は score だけでなく、固定した one-hop / two-hop の endpoint と edge type に対して照合する。
+27. success feedback 前後で edge weight と全 gold case の rank を比較し、credited path 外の edge 変更と非対象 case の rank 変更を明示する。
 
 ## 4. Constraints
 
@@ -52,7 +57,9 @@
 - `python -m unittest discover -s tests -v` が単体テストと統合テストを通過する。
 - `python -m neuron_graph_rag demo` が取り込み、検索、成功フィードバック、再検索を実演する。
 - `python -m neuron_graph_rag eval` が baseline hybrid と graph retrieval の比較指標を出力する。
+- `python -m neuron_graph_rag benchmark --fixture ... --gold ...` が固定実コーパス上の比較、説明経路、feedback isolation、仮説判定を出力する。
 - CI が editable install、test、eval を新規環境で実行する。
 - [Optional MCP Feedback Interface](optional-mcp-interface.md) が tool semantics、input、output、failure、core mapping、依存境界、repository 分離条件を定義する。
 - `tests/fixtures/d1_liplus_wiki.json` が実 D1 形状から ingest、検索、時系列 metadata、graph activation、success feedback を再現する。
 - [D1 corpus fixture](d1-corpus-fixture.md) が read-only 取得、認証境界、provenance、coverage 比較、再取得手順を定義する。
+- [Real-corpus benchmark](real-corpus-benchmark.md) が gold freeze、判定規則、観測結果、外挿限界を定義する。