feat: add independent retrieval channels

README.md

@@ -205,6 +205,30 @@ MCP 対応 AI との接続は、コアへ MCP SDK を追加せず、同一 repos
 
 契約には、接続した AI が `tools/list` だけから feedback 行動を判断できる model-facing description literal と、trace retention / expiry の表示規則も含みます。MCP server、認証、transport、remote deployment はまだ実装・確定していません。
 
+## Independent retrieval channels
+
+`search_channels(query, limit=...)`は既存`search()`を変更せず、同一queryへ二つの独立した候補列を返します。
+
+- `lexical`: BM25だけの順位。graph pathを保存しない
+- `relation`: BM25+dense entryをseed選択にだけ使い、anchored edge-only graph activationだけで順位付けする
+- 各laneは独立`trace_id`を持ち、`agreement_node_ids`は両方へ現れたnodeを示す
+- cross-lane final score、combined rank、single winnerは返さない
+
+```python
+channels = rag.search_channels("How are these decisions related?", limit=5)
+for hit in channels.lexical.hits:
+    print("lexical", hit.explain())
+for hit in channels.relation.hits:
+    print("relation", hit.explain())
+
+# lexical traceならedge不変、relation traceなら保存済みpathだけを強化する
+rag.record_success(channels.relation.trace_id, ["related-node"])
+```
+
+callerは両laneを検査し、下流判断で実際に使用したlaneの`trace_id`と`node_id`をfeedbackへ渡します。channel文字列を後から自己申告せず、保存済みtrace provenanceがreinforcement有無を決めます。固定D1 split、4-case hard gate、one-time holdout規則は[Independent retrieval channels experiment](docs/independent-retrieval-channels-experiment.md)を参照してください。
+
+凍結後のdevelopmentではrelation MRR改善、lane parity、feedback帰属を含む10/12 gateが成立しましたが、rank-1 lexical controlとfrozen path-shape matcherの2 gateが不合格でした。停止規則に従ってholdoutは開かず、`search_channels()`へvalidated判定を付与していません。既存`search()`が引き続きdefaultです。
+
 ## Explanation model
 
 各 `SearchHit` は次の情報を保持します。

docs/independent-retrieval-channels-experiment.md

@@ -0,0 +1,113 @@
+# Independent retrieval channels experiment
+
+## 目的
+
+fusion calibrationではrelation改善とdirect / negative-control維持を一つの順位で同時に満たす候補がなかった。本実験は既存`search()`とdefaultを保持したまま、BM25 lexical laneとanchored edge-only relation laneを`search_channels()`で合成せず同時返却する。
+
+NGRはquery classifier、learned router、cross-lane scalar scoreを実装しない。利用するAIが両laneを検査し、実際に判断根拠として使用したlaneの独立trace IDへfeedbackを返す。
+
+## channel契約
+
+Lexical lane:
+
+- BM25 raw score降順・node ID昇順
+- dense retrievalとgraph propagationを順位へ使わない
+- graph pathを保存しない
+- feedbackを記録してもedgeを変更しない
+
+Relation lane:
+
+- BM25+dense entry上位をseedにする
+- `anchored_local_competition`を使う
+- 1 edge以上を通過したpositive graph nodeだけを返す
+- raw graph activation降順・node ID昇順
+- entry scoreをrelation順位へ融合しない
+- feedbackは保存済みcredited pathだけを強化する
+
+各laneは同一queryと時刻を持つ独立`trace_id`として保存する。同じnodeが両laneに現れても重複を消さず、laneごとのrankと説明を保持する。envelopeは`agreement_node_ids`を持つが、combined hits、combined rank、final score、single winnerを持たない。
+
+## model-facing利用契約
+
+将来のadapterは次の意味をtool description自体へ含める。
+
+```text
+Inspect both independent retrieval channels before choosing evidence. The lexical channel contains sources that explicitly match the query by BM25. The relation channel contains sources reached through one or more graph edges from BM25+dense entry seeds. The channels have separate trace IDs and their scores are not comparable across channels. Retrieval alone does not mean selected, validated, or used and never reinforces edges. When a source actually becomes a basis of downstream work, send feedback with the trace ID of the channel that was used and that channel's node ID. Lexical-trace feedback never reinforces graph edges; relation-trace feedback reinforces only its stored credited path.
+```
+
+既存`ngr.mcp.feedback/v1`の`hits`をsilent reinterpretationしない。adapter実装時はlane envelopeと独立trace IDを明示する新contract versionを使う。
+
+## 凍結D1 split
+
+production D1 `search_docs` / `doc_edges`へSELECT / WITHだけを実行した。各splitの5 queryすべてで`rows_written=0`、`changes=0`、`changed_db=false`を確認した。
+
+- development: `didd-umbrella-naming` → `DiDD`
+- holdout: `skill-trigger-declaration-in-description` → `agentic-search-five-phase-refactor`
+
+各splitは2 nodes / 1 directed `mention` edgeである。既存9 fixturesの58 nonblank `doc_path` / `file_path`値、新split相互についてdoc path、file path、node ID、source URL、normalized query、expected node、relation endpointの重複を拒否する。auditはprior fixture identifiersだけを読み、prior goldとresultを読み込まない。
+
+## 4-case hard gate
+
+各splitは結果観測前に次の4 caseを固定する。
+
+1. source文書のdirect BM25 lookup
+2. target文書のdirect BM25 lookup
+3. sourceをanchorとしてtargetへ進むrelation lookup
+4. targetをanchorとし、outgoing edgeがないrelation laneが空になるdirectional negative
+
+2-node fixtureは一般性能を推定するには小さい。cohort MRR / Hit@1、union coverage、agreement率は補助指標とし、採否は次の個別hard gateを正本とする。
+
+1. lexical hit / rank / raw・normalized scoreがisolated BM25-onlyと一致
+2. lexical direct / directional-negativeのrankがBM25-onlyから退行しない
+3. relation hit / rank / graph activationがisolated anchored graph-onlyと一致
+4. relation MRRがBM25-onlyより厳密に高く、relation caseを個別改善
+5. relation pathが固定endpoint / edge typeに一致し、zero-hopを含まない
+6. combined score / rank / winnerが存在しない
+7. 両laneが異なるtrace IDと同一queryを持つ
+8. searchだけではedge不変
+9. lexical traceへのsuccessでは全edge不変
+10. relation traceへのsuccessではcredited edgeだけが変化
+11. cross-lane node / trace誤用をatomicに拒否
+12. trace IDを除く全lane結果が決定論的
+
+## result-free freezeと停止規則
+
+凍結artifact:
+
+- `tests/fixtures/d1_liplus_channels_experiment.manifest.json`
+- `d1_liplus_channels_development.json` / `.gold.json` / `.provenance.json`
+- `d1_liplus_channels_holdout.json` / `.gold.json` / `.provenance.json`
+- `d1_liplus_channels.contamination.json`
+
+fixture、gold、provenance、audit、implementation、tests、channel定義、seed規則、rank規則、feedback規則、threshold、gate、stop ruleをfreeze commitとしてpushしてからdevelopmentを一度だけ実行する。
+
+```powershell
+uv run python tools/run_channel_experiment.py development `
+  --manifest tests/fixtures/d1_liplus_channels_experiment.manifest.json `
+  --output tests/fixtures/d1_liplus_channels_experiment.development.result.json
+```
+
+全development gateを通過した場合だけholdoutを一度実行する。一つでも失敗した場合はholdout resultを作らず、既存`search()`をdefaultとして維持する。holdout観測後のartifact変更、result上書き、再実行を禁止する。
+
+## 観測結果
+
+fixture、gold、provenance、audit、manifest、implementation、tests、規則をfreeze commit `0404e9b`としてpushした後、developmentを一度だけ実行した。
+
+補助指標:
+
+| metric | value |
+| --- | ---: |
+| intended-lane MRR | 0.8750 |
+| intended-lane Hit@1 | 0.7500 |
+| relation BM25 MRR | 0.5000 |
+| relation lane MRR | 1.0000 |
+| union coverage | 1.0000 |
+| agreement rate | 0.5000 |
+
+12 gate中10件が通過した。lexical / relation isolated parity、relationのBM25比改善、独立trace、非融合envelope、search edge不変、lexical feedback非強化、relation feedbackのcredited edge限定強化、cross-lane拒否、決定性は成立した。
+
+不合格は次の2件である。
+
+1. frozen direct-target queryはBM25 / lexicalの両方でtarget rank 2となり、`acceptable_rank=1`の個別controlを満たさなかった。lane parity自体は成立しており、実装によるBM25退行ではないが、固定hard gateは不合格である。
+2. relation targetはrank 1となり、実際の`mention` edgeだけがfeedbackで強化された。しかしfrozen matcherはgoldのendpoint / edge typeだけのstepと、observed stepのweight / factualityを含むshapeを直接比較したため、`relation_paths_match_and_exclude_zero_hop=false`となった。観測後にmatcherを変更しない規則を優先し、不合格を維持する。
+
+selectionは`current`、理由は`channel_candidate_failed_frozen_gate`である。`holdout_status=not_opened_no_candidate`としてholdoutを開封せず、holdout resultを作成しない。`search_channels()`はadditive experimental APIとして残るが、本実験によるvalidated判定は付与しない。既存`search()`とdefaultは変更しない。

docs/requirements.md

@@ -71,6 +71,13 @@
 53. fusion calibration experimentはproduction D1の新しい3-node development / holdoutを、既存7 fixturesの50 unique doc pathsおよび相互間から分離し、provenance、balanced gold、contamination audit、6 variantsを結果観測前に固定する。
 54. development候補はrelation MRRをcurrentから厳密に改善し、少なくとも1 relation caseを個別改善し、direct / negative-controlのcohort MRRと全個別rankを退行させず、path、feedback、anchor、edge-only graph、formula auditを満たす場合だけ選択する。
 55. development候補がある場合だけ未観測holdoutでcurrentと選択候補を一度評価し、同じgateを通過した場合だけdefault変更候補とする。
+56. `search_channels`は同一queryからBM25 lexical laneとanchored edge-only relation laneを独立trace IDで同時返却し、cross-lane final score、combined rank、single winnerを生成しない。
+57. lexical laneはBM25だけで順位付けし、dense retrievalとgraph propagationをlane順位へ使用せず、保存hitへgraph pathを持たせない。
+58. relation laneはBM25+dense entryをseed選択だけに使い、`anchored_local_competition`で1 edge以上を通過したpositive graph nodeをraw activation降順・node ID昇順で順位付けする。
+59. channel provenanceはcallerのchannel自己申告でなく独立trace IDに保存し、`record_success`はlexical traceでedgeを変更せず、relation traceでは保存済みcredited pathだけを強化する。
+60. 同一nodeが両laneに現れる場合も各rankと説明を保持し、片方のtraceに保存されていないnodeへのfeedbackをatomicに拒否する。
+61. independent-channel experimentはproduction D1からread-only取得した相互disjointな2-node / 1-edge developmentとholdoutを、既存9 fixturesの全node pathから分離し、各splitの4-case hard gate、provenance、contamination audit、lane規則、feedback規則、停止規則を結果観測前に固定する。
+62. developmentでlane parity、relation個別改善、edge-only path、独立trace、edge不変、feedback帰属、cross-lane拒否、決定性の全hard gateを通過した場合だけholdoutを一度開き、同じgateを全通過した場合だけ`search_channels`をvalidatedと記録する。
 
 ## 4. Constraints
 
@@ -95,3 +102,4 @@
 - [Local recurrent competition experiment](neural-dynamics-local-competition-experiment.md) が新規D1 subgraph、contamination audit、query / path ablation、二baseline gateを定義する。
 - [Anchored BM25 and graph hybrid experiment](anchored-bm25-graph-hybrid-experiment.md) がzero-hop anchor、edge-only graph signal、BM25 ablation、新規D1 split、単一holdout gateを定義する。
 - [Anchored fusion calibration experiment](anchored-fusion-calibration-experiment.md) がgraph normalization、bottom-centered RRF、新規D1 split、個別case gateを定義する。
+- [Independent retrieval channels experiment](independent-retrieval-channels-experiment.md) が非融合lane、独立trace provenance、feedback帰属、4-case hard gate、単一holdout開封を定義する。

src/neuron_graph_rag/__init__.py

@@ -4,6 +4,9 @@
     DocumentNode,
     FeedbackReceipt,
     PathStep,
+    SearchChannelHit,
+    SearchChannelsResult,
+    SearchChannelTrace,
     SearchHit,
     SearchTrace,
     TypedEdge,
@@ -18,6 +21,9 @@
     "FeedbackReceipt",
     "NeuronGraphRAG",
     "PathStep",
+    "SearchChannelHit",
+    "SearchChannelsResult",
+    "SearchChannelTrace",
     "SearchHit",
     "SearchTrace",
     "TypedEdge",