eval: validate local recurrent competition

README.md

@@ -130,6 +130,14 @@ development では `budget-025` が relation MRR 0.3833 を維持し、negative-
 
 全13 variants の gate 不合格と tradeoff、選択理由、holdout 判定は [Neural dynamics experiment](docs/neural-dynamics-experiment.md) と versioned result JSON に保存しています。現在の holdout は再選択や parameter 調整に再利用しません。
 
+## Local recurrent competition experiment
+
+PR #12のglobal recurrent tradeoffを受け、競合を同じsourceのsibling neighborへ局所化し、query relevanceとactive path identityを独立に比較する6-variant experimentを定義しています。
+
+production D1から取得した新しいdevelopment / holdoutは、旧development、開封済み旧holdout、相互間でdoc pathとnode IDを分離しています。両provenance、contamination audit、二baseline gate、one-time holdout停止規則は[Local recurrent competition experiment](docs/neural-dynamics-local-competition-experiment.md)を参照してください。
+
+freeze後のdevelopmentでは、queryなしのlocal variantsがrelationを改善した一方でdirect / negative-controlを退行させ、query variantsはnegative-controlを維持した一方でbest prior recurrentのrelationを上回れませんでした。候補gate通過は0件だったためholdoutは開かず、既定strategyは`current_positive_additive`のままです。
+
 ## Public API
 
 ```python

docs/neural-dynamics-local-competition-experiment.md

@@ -0,0 +1,113 @@
+# Local recurrent competition experiment
+
+## 目的
+
+PR #12で観測されたrecurrent competitionのrelation改善とdirect / negative-control退行を分離するため、競合をglobal node集合から同じsourceのsibling neighborへ局所化する。query relevanceとactive path identityを独立ablationとして比較し、未観測holdoutが固定gateを通過した場合だけdefault変更を許可する。
+
+旧developmentはfamilyと`recurrent-balanced` baselineを選んだ探索的根拠に限定する。旧holdoutのgold、rank、metrics、resultは本実験へ読み込まない。
+
+## 固定入力
+
+- manifest: `tests/fixtures/d1_liplus_local_competition_experiment.manifest.json`
+- development fixture / gold / provenance: `d1_liplus_local_competition_development.*.json`
+- holdout fixture / gold / provenance: `d1_liplus_local_competition_holdout.*.json`
+- contamination audit: `d1_liplus_local_competition.contamination.json`
+- 両fixtureはproduction D1 `search_docs` / `doc_edges`からread-only取得した9 node / 11 `mention` edgeのweakly-connected subgraph
+- developmentはjudgment-learning / self-evolution / retrieval-surface cluster
+- holdoutはwiki-sync / Character_Instance cluster
+
+acquisition provenanceはschema fingerprint、取得時刻、coverage、zero-write evidence、known gapを保持する。D1はlossy search snapshotであり、GitHubをbyte-exact sourceの正本とする。
+
+## Contamination boundary
+
+auditは次の重複が空であることを固定する。
+
+- 新developmentと新holdoutのdoc path、node ID、source URL
+- 両新splitと旧development fixture
+- 両新splitと開封済み旧holdout fixture
+- 新split間のnormalized query、expected node、relation endpoint
+
+旧holdoutはfixture identifierだけをdenylist照合する。旧holdout goldとresultはaudit toolもexperiment runnerも読み込まない。
+
+## 固定variant
+
+variantは6件で、追加parameter gridを持たない。全variantは同じentry / graph weight、seed count、hop limit、hop decay、recurrent step、decay、activation budget、inhibition ratioを使う。
+
+| role | variant | structure |
+|---|---|---|
+| baseline | `current` | current positive additive |
+| baseline | `recurrent-balanced` | PR #12のbest prior recurrent |
+| candidate | `local-neighbor` | sourceごとのsibling neighbor競合 |
+| candidate | `local-neighbor-query` | sibling競合 + query relevance |
+| candidate | `local-neighbor-path` | active pathごとのsibling競合 |
+| candidate | `local-neighbor-query-path` | active path競合 + query relevance |
+
+path identityはseed IDとruntimeで通過したedge target列から決める。gold path、expected node、case ID、特定query文字列をruntime条件にしない。path stateはnodeごとに最大4件、全伝播は`max_propagation_expansions`で停止する。
+
+## Local update
+
+各sourceまたはactive pathについてoutgoing edge messageを作り、その集合内だけで次を行う。
+
+1. query variantだけtarget text / edge typeとのquery overlapでmessageをgateする。
+2. sibling集合の最大messageに固定inhibition ratioを掛け、各messageから引く。
+3. 残ったmessage総量を`activation_budget * source_activation`以内へscaleする。
+4. path variantだけpath identityを維持してnode集約前に上位pathを決定論的に残す。
+5. recurrent decayを前step stateへ適用する。
+
+global maximumを使った抑制はlocal候補へ適用しない。diagnosticsは競合集合ごとのsource、path identity、neighbor数、平均query relevance、message総量の前後を保存する。
+
+## Development gate
+
+新developmentで6 variantsを一度評価する。local候補は次をすべて満たす場合だけ通過する。
+
+1. relation MRRが`current`と`recurrent-balanced`を両方厳密に上回る。
+2. direct lookup MRRが`current`から退行しない。
+3. negative-control MRRが`current`から退行しない。
+4. 全relation caseのendpoint / edge type pathが一致する。
+5. credited feedback edgeが1本以上変化する。
+6. uncredited edgeと非対象case rankが変化しない。
+
+複数候補のtie-breakはworst-cohort MRR、relation MRR、平均展開数、構造複雑度、variant IDの順とする。候補がなければholdoutを開かずdefaultを維持する。
+
+## Holdout stop rule
+
+development候補がある場合だけ、holdoutで`current`、`recurrent-balanced`、選択候補を一度評価する。result fileが存在する場合は上書きを拒否する。
+
+採用にはdevelopmentと同じgateを要求する。一つでも失敗した場合は`current_positive_additive`を維持し、holdout観測後のparameter、gold、doc path、閾値、選択規則、停止規則変更を禁止する。
+
+## 実行境界
+
+fixture、gold、provenance、audit、manifest、implementation、tests、上記規則をfreeze commitとしてpushするまでdevelopment runnerを実行しない。
+
+freeze後の順序は次に限定する。
+
+1. development resultを新規作成する。
+2. 固定gateで候補を一意に決める。
+3. 候補がなければ終了する。
+4. 候補があればholdout resultを一度だけ新規作成する。
+5. 固定gateからdefault維持または候補採用を記録する。
+
+品質数値はCI合格閾値にしない。CIはhash、contamination、determinism、局所性、variant上限、停止規則を検証する。
+
+## 観測結果
+
+freeze commit `3562c0f` のpush後、developmentを一度実行した。全結果は`tests/fixtures/d1_liplus_local_competition_experiment.development.result.json`に保存する。
+
+| variant | direct MRR | relation MRR | negative MRR | path | feedback | gate |
+|---|---:|---:|---:|---:|---:|---|
+| `current` | 1.0000 | 0.3167 | 1.0000 | 3/3 | pass | reference |
+| `recurrent-balanced` | 0.6667 | 0.3611 | 1.0000 | 3/3 | pass | baseline |
+| `local-neighbor` | 0.4444 | 0.5278 | 0.8333 | 3/3 | pass | fail |
+| `local-neighbor-query` | 0.8333 | 0.3333 | 1.0000 | 3/3 | pass | fail |
+| `local-neighbor-path` | 0.4444 | 0.5278 | 0.8333 | 3/3 | pass | fail |
+| `local-neighbor-query-path` | 0.8333 | 0.3333 | 1.0000 | 3/3 | pass | fail |
+
+全variantでrelation path 3/3とfeedback isolationは成立した。
+
+query conditioningなしのlocal variantsはrelation MRRで両baselineを上回ったが、direct MRRとnegative-control MRRが`current`から退行した。query-conditioned variantsはnegative-controlを維持したが、relation MRRが`recurrent-balanced`を上回らず、direct MRRも退行した。path-conditioned variantsは対応するnode-aggregated variantsと同じrankになり、この9-node topologyでは追加の識別信号を生まなかった。
+
+固定gateを通る候補は0件だった。selectionは`current`、理由は`no_local_variant_passed_frozen_gate`である。停止規則に従ってholdoutは開封せず、holdout resultも作成しない。defaultは`current_positive_additive`のままとする。
+
+## 適用限界
+
+9-nodeの固定Li+ wiki subsetとfeature-hashing encoderだけを対象とする。path ablationが同値だったことは、このfixtureで複数active pathが最終rankを分離しなかったという観測に限られる。D1 snapshot、別graph topology、learned embedding、一般corpusへ結果を外挿しない。

docs/requirements.md

@@ -49,6 +49,14 @@
 31. 候補選択は development result だけで行い、relation MRR と negative-control MRR の Pareto gate、worst-cohort MRR、展開数、構造複雑度、variant ID の順で一意に決める。
 32. development gate を通る候補がない場合は holdout を開かず既定を変更しない。候補がある場合だけ holdout を一度評価し、cohort 退行、path 不一致、feedback 汚染のいずれかがあれば採用しない。
 33. experiment result は gate 不合格、Pareto 支配、holdout 不採用を含む全 variant を上書きせず versioned artifact として保存する。
+34. recurrent activation は global inhibition に加え、同じ source の sibling neighbor だけを競合させる local strategy を選択できる。
+35. local recurrent strategy は query relevance と active path identity を独立に有効化でき、競合集合ごとに source、path identity、neighbor 数、query relevance、配分前後の message 総量を記録する。
+36. local recurrent experiment は production D1 から read-only 取得した新しい development / holdout を旧 development / 開封済み holdout および相互間で分離し、両 provenance と contamination audit を結果観測前に固定する。
+37. 旧 development result は family と baseline の探索的根拠だけに使用し、旧 holdout は fixture identifier の重複拒否以外では読み込まない。
+38. local recurrent experiment は `current`、`recurrent-balanced`、neighbor / query / path の4 ablationを合わせた6 variantsに固定し、parameter gridを追加しない。
+39. development候補はrelation MRRで両baselineを厳密に上回り、direct / negative-control MRRがcurrentから退行せず、全relation pathとfeedback isolationを満たす場合だけ選択する。
+40. development候補がある場合だけ、未観測holdoutで`current`、`recurrent-balanced`、選択候補を一度評価する。resultの再実行と上書きを拒否する。
+41. local recurrent strategyは未観測holdoutで同じgateを通過した場合だけ既定候補になり、それ以外では`current_positive_additive`を維持する。
 
 ## 4. Constraints
 
@@ -70,3 +78,4 @@
 - [D1 corpus fixture](d1-corpus-fixture.md) が read-only 取得、認証境界、provenance、coverage 比較、再取得手順を定義する。
 - [Real-corpus benchmark](real-corpus-benchmark.md) が gold freeze、判定規則、観測結果、外挿限界を定義する。
 - [Neural dynamics experiment](neural-dynamics-experiment.md) が development / holdout 分離、固定探索空間、候補選択、単一 holdout 開封、停止規則を定義する。
+- [Local recurrent competition experiment](neural-dynamics-local-competition-experiment.md) が新規D1 subgraph、contamination audit、query / path ablation、二baseline gateを定義する。