test-data: acquire a D1 corpus fixture for NGR validation

[lipluscodex]

目的

github-rag-mcp の本番 D1 から実データを読み取り専用で取得し、Neuron Graph RAG（NGR）の検索・時系列・成功フィードバックを、合成データだけでなく実際の Li+ 履歴コーパスでも再現可能に検証できるようにする。

前提

• D1 の検索コーパスの正本は search_docs である。FTS5 virtual table / shadow table は派生索引であり、fixture の正本にしない。
• Decision Structure の参照関係は doc_edges に格納される。NGR の typed edge へ変換する際は、現在の mention と将来の typed edge を区別できる provenance を残す。
• 2026-08-01 に本番 D1 の live schema を SELECT ... FROM pragma_table_info(...) で読み取り確認した。search_docs は migration 0006 の content_fts を含む20列、doc_edges は7列で、現在の source schema と一致する。
• D1 は GitHub 本体の完全な状態バックアップではなく、content truncation や binary / patchless file の除外を含む検索用の損失ありスナップショットである。GitHub を完全な履歴復元の正本とする。
• github-rag-mcp#178 の forward watermark 修正は merge / deploy 済みで、2026-08-01 に既存 gap の backfill が再開された。初回 fixture は取得時点の coverage を記録し、backfill 完了後に再取得して差を比較する。backfill 未完は取得ツール実装を止めないが、本 issue の close は比較完了まで待つ。
• Cloudflare D1 は remote query と remote export を提供し、REST query API は D1 Read 権限で利用できる。取得経路は SELECT / export のみに制限する。
• NGR core は Python 標準ライブラリのみで動作する。取得ツールに追加依存が必要な場合は core runtime から分離する。

変換契約

• search_docs.vector_id を DocumentNode.node_id、raw content を DocumentNode.text へ写す。DocumentNode.confidence の初期値は 1.0 とする。
• node metadata には content と派生列 content_fts を除く search_docs の全 provenance 列を保持する。fixture schema version と source schema fingerprint を別途記録する。
• doc_edges.src_vector_id / dst_vector_id を NGR edge の両端へ、edge_kind を TypedEdge.edge_type へ写す。初期 weight / factuality は 1.0 とする。
• 小 fixture に両端 node が含まれる edge のみを変換する。片端または両端が欠ける edge は node を捏造せず除外し、件数と理由を provenance report に記録する。
• 縮小規則は明示された repo / type filter と per-type limit を入力にし、(repo, type, updated_at, vector_id) の固定順で選ぶ。同じ input snapshot と引数から byte-identical JSON を生成する。
• fixture は UTF-8、key sort、固定改行で出力し、取得時刻のような可変値は fixture 本体ではなく provenance report に隔離する。

制約

• D1 への操作は読み取り専用とし、本番データを変更しない。SQL を受け取る場合は単一の SELECT / WITH query 以外を拒否する。
• Cloudflare / GitHub の認証情報をログ、fixture、provenance report、リポジトリへ保存しない。認証情報らしい文字列を検出した場合は deterministic redaction または fail-closed とする。
• 取得日時、対象リポジトリ、type 別件数、最古・最新日時、distinct commit 数、既知の gap、D1 query の rows_written=0 を機械可読な provenance report に残す。
• 公開リポジトリ由来であることと、元 URL、commit SHA、document path などの出典情報を fixture に保持する。
• 完全スナップショットは Git へコミットせず、小さく安定した決定論的 fixture のみを管理対象にする。
• 小規模 fixture を用いた統合テストで、ingest、検索、時系列 metadata、graph activation、success feedback を再現可能に確認する。
• backfill 完了後に再取得し、provenance report の coverage が直近 commit 側へ伸びたことを比較できるようにする。
• 取得方法、データの出典、完全性の限界、再取得・監査手順を docs に記録する。

想定変更箇所

• tools/ — read-only D1 export、fixture 縮小、provenance 生成
• tests/fixtures/ — 小規模で決定論的な実データ形状 fixture
• tests/ — fixture から NGR へ ingest する統合テスト
• docs/ — 取得、認証、provenance、coverage 監査、再取得手順
• .gitignore — 完全スナップショットと一時 export の除外

[lipluscodex]

PR #8 は commit 4f3236a で実装と CI を完了しました。

Issue 本文の close 条件どおり、github-rag-mcp#178 の backfill 完了後に同一引数で再取得し、tools/compare_d1_provenance.py で diff coverage の count / distinct commit / newest timestamp の伸長を比較するまで merge / close を待ちます。