feat: add independent lexical and relation lanes

[lipluscodex]

目的

Issue #17 / PR #18では、anchored graphを強くするとrelationは改善するがdirect / negative-controlが退行し、保守化するとcontrolは維持するがrelation改善が消えた。global weight、normalization、RRFで一つの順位へ圧縮する限り、採用可能な中間点は観測できなかった。

本Issueでは単一fusionを廃し、同じqueryに対して次の2 laneを独立に返す。

1. BM25 lexical lane: direct lookupとnegative-controlの安全な候補列
2. anchored edge-only relation lane: relation発見の候補列

利用するLLMが両laneの説明と独立trace IDを見て、lexical、relation、または両方を選ぶ。NGRはquery分類器やcross-lane scalar scoreで先に一つへ潰さない。

Dual-lane契約

additive core APIとして search_channels(query, limit) を追加する。既存searchの挙動とdefaultは変更しない。

返却値は一つのenvelopeに次を持つ。

• query
• lexical lane
  • 独立trace_id
  • channel=lexical
  • BM25だけで順位付けしたhits
  • dense retrievalとgraph propagationを呼ばない
  • graph pathを持たない
• relation lane
  • 独立trace_id
  • channel=relation
  • BM25+dense entryはseed選択にだけ使用
  • anchored_local_competitionでedgeを1本以上通過したpositive graph nodeだけを返す
  • rankはraw graph activation降順、node ID昇順
  • entry scoreをrelation順位へ融合しない
  • 各hitにedge pathを要求
• agreement_node_ids
  • 両laneに現れたnodeを示す
  • 重複を消さず、各laneのrankと説明を保持

envelopeにはcross-lane final score、combined hits、single winnerを持たせない。各lane内のscoreは比較可能だが、lane間で大小比較しない。

LLM向け利用契約

model-facing descriptionへ次を明示する。

• lexical laneはqueryと明示的に一致するsource候補
• relation laneはgraph edgeで関係付けられたsource候補
• 両laneを検査し、下流判断の根拠として実際に使用したlaneのtrace_idとnode_idへfeedbackを返す
• retrievalはselected / validated / usedを意味しない
• searchだけでedgeを強化しない

LLMの意味判断自体をNGRの固定classifierへ置き換えない。

Feedback帰属

二つの独立trace IDを既存record_successへ渡せるようにする。

• lexical traceのstored hitsにはgraph pathを保存しない。lexical nodeへのsuccessはedgeを一切変更しない。
• relation traceのstored hitsには実際にcreditedされたedge-only pathだけを保存する。relation nodeへのsuccessはそのpathだけを強化する。
• 片方のtrace IDで他方だけに存在するnodeを成功扱いできない。
• 同じnodeが両laneに存在しても、選択したtrace IDによってreinforcement有無が決まる。
• search_channelsの実行だけではedge weightを変更しない。

channel文字列を後から自己申告させず、trace provenanceから帰属を決定する。

D1事前確認とデータ分離

production D1 search_docs / doc_edgesをread-only確認した。

• 既存9 fixture群のnode pathsをすべて除外
• 58 nonblank doc_path / file_path valuesをdenylist化
• 21 eligible active wiki docs
• eligible同士のmention edgeは2本で、相互disjointな2-node / 1-edge componentを2組確保可能
• component A: didd-umbrella-naming -> DiDD
• component B: skill-trigger-declaration-in-description -> agentic-search-five-phase-refactor
• rows_written=0 / changes=0 / changed_db=false

A/Bのdevelopment / holdout割当、fixture、4-case hard-gate gold、provenance、contamination audit、評価規則、stop ruleをresult観測前の独立freeze commitで固定する。全既存fixture、新development、新holdout間のdoc path、node ID、source URL、normalized query、expected node、relation endpoint重複を拒否する。

各splitは2-node / 1-edgeの最小構成でrank粒度が粗いため、一般性能ではなくlane independence、availability、feedback attributionの構造検証として扱う。集約MRRを主gateにせず、次の4 caseを個別hard gateとして結果前に固定する。

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

自然なquery、expected node、relation pathを事前固定できなければresultを観測せず停止する。

Development評価

各queryで次を保存する。

• lexical lane: BM25 raw / normalized score、rank、trace ID、path absence
• relation lane: seed entry、raw graph activation、graph rank、edge path、trace ID
• agreement node
• isolated BM25-only runとのlexical順位一致
• isolated anchored graph-only runとのrelation順位一致
• cross-lane combined score / combined rankが存在しないこと
• search前後のedge weight
• lexical success後の全edge差分
• relation success後のcredited / uncredited edge差分
• determinism、step、expansion、active path、停止理由

Development gate

次をすべて満たす場合だけholdoutを開く。

1. lexical laneの全hit/rank/scoreがisolated BM25-onlyと一致
2. lexical laneのdirect / negative-control MRRと各case rankがBM25-onlyから退行しない
3. relation laneの全hit/rank/graph scoreがisolated anchored graph-onlyと一致
4. relation laneのrelation MRRがBM25-onlyより厳密に高く、最低1 relation caseが個別改善
5. 全relation hitが固定endpoint / edge type pathと一致し、zero-hopを含まない
6. dual responseにcombined final score / combined rank / single winnerがない
7. 両laneが独立trace IDを持ち、同一queryへ対応する
8. searchだけではedge不変
9. lexical traceへのsuccessでは全edge不変
10. relation traceへのsuccessではcredited edgeが1本以上変化し、uncredited edgeは不変
11. cross-lane node/traceの誤用を拒否
12. 全結果が決定論的

補助指標としてcohortごとのintended-lane MRR / Hit@k、どちらかのlaneに正解があるunion coverage、agreement率を保存する。2-node splitでは個別hard gateを採否の正本とし、集約値は説明用とする。gold cohortによるoracle選択は評価用だけに使い、production query routerとして実装しない。

一回限りのholdout

development gateをすべて通過した場合だけ、未観測holdoutで同じdual-lane契約を一度評価する。採用には同じgateをすべて要求する。

holdout観測後のfixture、gold、lane定義、seed規則、rank規則、feedback規則、threshold、gate、stop rule変更、result上書き、再実行を拒否する。

制約

• Python標準ライブラリのみ
• 既存search API / default / fused実験再現性を壊さない
• learned router、query classifier、LLM呼び出しは今回のcore実験に含めない
• LLMへはlane意味とfeedback契約を提示し、最終選択を委ねる
• coreをLi+ node、D1 schema、gold、case IDへ依存させない
• 特定query、expected node、goldへの例外は禁止
• 陰性結果もversioned artifactとして保存
• 品質数値をCI固定閾値にせず、CIはfreeze hash、分離、lane parity、trace provenance、feedback isolation、one-time holdoutを検証

完了条件

• BM25 lexical laneとanchored relation laneを合成せず同時返却できる
• LLMが独立trace IDで利用laneを選択しfeedbackを帰属できる
• lexical利用でedge不変、relation利用でcredited pathだけ強化される
• 新developmentと必要時のholdoutで固定gateを機械的に再現できる
• holdoutが全条件を通過した場合だけdual-lane APIをvalidatedと記録する