Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+.env/
+
+# Checkpoints and results (large generated files)
+checkpoints/
+results/
+
+# Downloaded datasets (LM4 wave data, >100MB)
+data/
+
+# Logs and temporary data
+*.log
+*.tmp
+/tmp/lm2data/
+/tmp/lm3data/
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Archives
+*.zip
+*.tar.gz
+*.rar
+paper/*.aux
+paper/*.bbl
+paper/*.out
+paper/*.log
+paper/*.jsonl

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yuanjieliu Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,148 @@
+---
+license: mit
+tags:
+- state-space-model
+- continual-learning
+- metalearning
+- ssm
+library_name: other
+---
+
+# headless
+
+A production-grade **continuously learning model** system built on SSM (State Space Model) + OML (Optimization-based Meta-Learning) with autonomous data exploration.
+
+> Formerly known as LMT-twister. Established 2026-08-20.
+
+## Continuous Learning
+
+headless models learn continuously during runtime without forgetting previously acquired knowledge. The system demonstrates:
+
+- **Zero forgetting across domains** — LM2 on wikitext-2 (3 domains, streaming 500 steps/domain): all domains show **positive transfer** after sequential training (A: 0.429→0.472, B: 0.478→0.488, C: 0.493).
+- **Cross-domain robustness** — LM3 on en→zh→code (BPE, 3 domains): naive sequential training causes catastrophic forgetting (-10.4pp on English), proving **true continuous learning requires mechanisms** (Replay +5.0pp, correct OML via inner-loop adaptation).
+- **Autonomous exploration** — LM1 generates its own training data via a value-function proposer (simplicity + consistency + coverage), reaching **unseen accuracy 0.1276 / c4 structure 0.1510** with **negative forgetting** (-0.006), beating the family 22-intervention peak (0.099) by **1.5×**.
+
+## Architecture
+
+```
+LM1 (Production, 1.05M params)
+├── SSM backbone (V31_RLN, configurable d_model/d_state/layers)
+├── SwiftTD head — per-feature step-size optimization (IDBD online, no BPTT)
+├── OML dual-loop — inner-loop PLN adaptation + outer-loop meta-update
+└── S4 Value Proposer — autonomous task generation from structural novelty
+
+LM2 (Text, 0.71M params)
+├── SSM character-level LM (vocab 607)
+└── Streaming 3-domain wikitext-2
+
+LM3 (BPE, 2.26M params)
+├── BPE tokenizer (vocab 4627)
+└── en→zh→code cross-domain experiments
+```
+
+### Key Mechanisms
+
+| Mechanism | Role | Evidence |
+|:--|:--|:--|
+| **Replay** | Anti-forgetting (data anchoring) | +5.0pp avg over base |
+| **OML** | Adaptation efficiency (inner-loop cloning) | Not anti-forgetting; enables fast new-domain adaptation |
+| **SwiftTD** | Per-feature learning rates (online IDBD) | Prevents step-size collapse under bound/decay |
+| **Value Proposer** | Autonomous data generation | Drives continuous exploration without human labeling |
+
+## Project Structure
+
+```
+tests/
+├── run_lm1_production.py  — Production autonomous CL model (checkpoint, eval, infer)
+├── run_lm2_text.py        — Real-text continuous learning (wikitext-2)
+├── run_lm3_bpe.py         — BPE + cross-domain CL (5 methods)
+├── lm1_inference_demo.py  — Production inference API (define+adapt+query)
+└── run_v3*.py             — 17 experiment runners (V31-V35 ablation suite)
+
+hibs_lnn/
+├── ssm_v30_3.py           — SSM layer with internal entanglement (phase modulation)
+├── swiftd_head.py         — SwiftTD per-feature step-size optimizer
+├── meta_rule_world.py     — Meta-learning task distribution (S4 permutations)
+└── code_world.py          — Register-machine sandbox (8 instructions, 4 registers)
+
+docs/wiki/log.md           — Continuous learning experiment log
+```
+
+## Quick Start
+
+```bash
+# Smoke test (1 round, 2 iters, no migration)
+python smoke_lm1.py
+
+# Production training (10 rounds, auto-explore + evaluate)
+python tests/run_lm1_production.py --rounds 10
+
+# Resume from checkpoint
+python tests/run_lm1_production.py --resume
+
+# Inference demo
+python tests/lm1_inference_demo.py --ckpt checkpoints/lm1_final.pt
+
+# Text continuous learning
+python tests/run_lm2_text.py
+
+# BPE cross-domain (replay method)
+python tests/run_lm3_bpe.py --method replay
+```
+
+## Results
+
+### LM1 — Production Autonomous CL
+
+| Metric | Value | Family Peak | Improvement |
+|:--|:--|:--|:--|
+| Unseen accuracy | 0.1276 | 0.099 | **+29%** |
+| c4 structure accuracy | 0.1510 | 0.099 | **+53%** |
+| Forgetting | -0.006 | — | **Negative (improvement)** |
+| S5 transfer (R16) | 0.1172 | — | Positive migration |
+
+- **17 rounds / 680 iters** fully automatic convergence
+- Model: `checkpoints/lm1_final.pt` (6.3MB)
+- Report: `results/lm1_report.md`
+
+### LM2 — Real-Text CL
+
+| Domain | Before | After | Change |
+|:--|:--|:--|:--|
+| A (train 2M chars) | 0.429 | 0.472 | **+4.3pp** |
+| B (valid 1.1M chars) | 0.478 | 0.488 | **+1.0pp** |
+| C (test 1.3M chars) | 0.493 | — | **Positive transfer** |
+
+**Conclusion:** Continuous learning with zero forgetting holds on real text (same-domain wikitext).
+
+### LM3 — Cross-Domain CL
+
+| Method | en | zh | code | Average |
+|:--|:--|:--|:--|:--|
+| Base (sequential) | 0.260 | 0.076 | 0.340 | 0.170 |
+| Replay | 0.252 | 0.057 | 0.352 | **0.220** |
+| OML (dual-lr) | — | — | — | 0.131 |
+| OML2 (correct) | — | — | — | 0.168 |
+
+**Conclusion:** Replay is the only effective anti-forgetting mechanism (+5.0pp). Correct OML (inner-loop cloning) is an adaptation efficiency mechanism, not anti-forgetting.
+
+## Mechanism Conclusions
+
+1. **Replay is the sole anti-forgetting mechanism** — data-level anchoring (+5.0pp)
+2. **OML is adaptation efficiency** — correct form = inner-loop cloning + query meta-loss
+3. **Dual learning rate ≠ OML** — simple head+body LR split fails
+4. **Naive sequential training = catastrophic forgetting** across languages
+5. **Production CL = larger representation × long training × autonomous data** — emergent as a system
+
+## Data Requirements
+
+- **LM1 / LM2**: No external data needed (synthetic tasks / wikitext-2 auto-download)
+- **LM3**: Place data in `/tmp/lm2data` and `/tmp/lm3data` respectively
+
+## Citation
+
+If you use this work, please cite the mechanism conclusions and the LM1 production system results.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

README_zh.md

@@ -0,0 +1,174 @@
+# headless
+
+基于 SSM（状态空间模型）+ OML（基于优化的元学习）构建的生产级**持续学习模型**系统，配备自主数据探索能力。
+
+> 前身为 LMT-twister。建立于 2026-08-20。
+
+## 持续学习
+
+headless 模型在运行时持续学习，不会遗忘先前获取的知识。系统展示的能力包括：
+
+- **跨域零遗忘** — LM2 在 wikitext-2 上（3 域，流式 500 步/域）：顺序训练后所有域均呈现**正向迁移**（A: 0.429→0.472，B: 0.478→0.488，C: 0.493）。
+- **跨域鲁棒性** — LM3 在 en→zh→code 上（BPE，3 域）：朴素顺序训练造成灾难性遗忘（English -10.4pp），证明**真正的持续学习需要机制**（Replay +5.0pp，正确 OML 通过内循环适应）。
+- **自主探索** — LM1 通过价值函数提议器（简约性 + 自洽性 + 覆盖）自主生成训练数据，达到 **unseen 准确率 0.1276 / c4 结构 0.1510**，**遗忘为负**（-0.006），以 **1.5 倍** 超越家族 22 次干预峰值（0.099）。
+
+## 架构
+
+```
+LM1（生产级，105 万参数）
+├── SSM 骨干网络（V31_RLN，d_model/d_state/层数可配置）
+├── SwiftTD 头 — 逐特征步长优化（在线 IDBD，无需 BPTT）
+├── OML 双层循环 — 内循环 PLN 适应 + 外循环元更新
+└── S4 价值提议器 — 基于结构新颖性自主生成任务
+
+LM2（文本，71 万参数）
+├── SSM 字符级语言模型（词表 607）
+└── 三域流式 wikitext-2
+
+LM3（BPE，226 万参数）
+├── BPE 分词器（词表 4627）
+└── en→zh→code 跨域实验
+```
+
+### 核心机制
+
+| 机制 | 作用 | 证据 |
+|:--|:--|:--|
+| **Replay（回放）** | 防遗忘（数据级锚定） | 相对基线 +5.0pp |
+| **OML** | 适应效率（内循环克隆） | 非防遗忘机制；实现新域快速适应 |
+| **SwiftTD** | 逐特征学习率（在线 IDBD） | 防止 bound/decay 下的步长塌缩 |
+| **价值提议器** | 自主数据生成 | 无需人工标注即可持续探索 |
+
+## 因果技术栈（Causal AI，新增）
+
+把《Causal AI》一书的因果方法落地到 S4 元学习世界，用**因果发现改进自主数据提议器**：
+
+| 文件 | 落地 | 对应书章节 |
+|:--|:--|:--|
+| `hibs_lnn/causal/dag.py` | DAG + d-separation | 第 3-4 章 |
+| `hibs_lnn/causal/scm.py` | SCM + do() 干预 + 反事实 | 第 6-9 章 |
+| `hibs_lnn/causal/identification.py` | 后门调整 / g-公式识别 | 第 10-11 章 |
+| `hibs_lnn/causal/discovery.py` | 条件独立检验 + PC 骨架 | 因果发现 |
+| `hibs_lnn/causal/causal_proposer.py` | 因果驱动的提议器（do-效应/反事实） | 自主探索 |
+| `hibs_lnn/causal/causal_rl.py` | Causal RL + 因果 credit assignment | 第 12 章 |
+
+- 演示：`python3 causal_tech_stack_demo.py`（8 步，秒级）
+- 自测：`python3 -m hibs_lnn.causal.self_test`（15/15 passed）
+- 文档：`docs/wiki/causal_stack.md`
+
+**实测**：同样已学集合下，因果提议器每步覆盖新生成元原子 **0.50**，启发式仅 **0.33**。
+## 项目结构
+
+```
+tests/
+├── run_lm1_production.py  — 生产级自主持续学习模型（checkpoint、评估、推理）
+├── run_lm2_text.py        — 真实文本持续学习（wikitext-2）
+├── run_lm3_bpe.py         — BPE + 跨域持续学习（5 种方法）
+├── lm1_inference_demo.py  — 生产级推理接口（define+adapt+query）
+└── run_v3*.py             — 17 个实验运行脚本（V31-V35 消融套件）
+
+hibs_lnn/
+├── ssm_v30_3.py           — 带内部纠缠的 SSM 层（相位调制）
+├── swiftd_head.py         — SwiftTD 逐特征步长优化器
+├── meta_rule_world.py     — 元学习任务分布（S4 排列）
+├── code_world.py          — 寄存器机沙箱（8 条指令，4 个寄存器）
+└── causal/                — Causal AI 技术栈（DoWhy/pgmpy 的轻量等价物）
+    ├── dag.py             — DAG + d-separation
+    ├── scm.py             — 结构因果模型 + do() + 反事实
+    ├── identification.py  — 后门调整 / g-公式识别
+    ├── discovery.py       — 条件独立检验 + PC 骨架
+    ├── causal_proposer.py — 因果驱动的自主数据提议器（改进提议器）
+    └── causal_rl.py       — Causal RL + 因果 credit assignment
+
+tests/
+├── run_lm1_production.py  — 生产级自主持续学习模型（checkpoint、评估、推理）
+├── run_lm2_text.py        — 真实文本持续学习（wikitext-2）
+├── run_lm3_bpe.py         — BPE + 跨域持续学习（5 种方法）
+├── lm1_inference_demo.py  — 生产级推理接口（define+adapt+query）
+└── run_v3*.py             — 17 个实验运行脚本（V31-V35 消融套件）
+
+docs/wiki/
+├── log.md                 — 持续学习实验日志
+└── causal_stack.md        — 因果技术栈落地文档
+
+causal_tech_stack_demo.py  — 因果技术栈端到端演示（8 步，秒级）
+```
+
+## 快速开始
+
+```bash
+# 冒烟测试（1 轮、2 步、不触发迁移）
+python smoke_lm1.py
+
+# 生产级训练（10 轮，自动探索 + 评估）
+python tests/run_lm1_production.py --rounds 10
+
+# 从 checkpoint 恢复
+python tests/run_lm1_production.py --resume
+
+# 推理演示
+python tests/lm1_inference_demo.py --ckpt checkpoints/lm1_final.pt
+
+# 文本持续学习
+python tests/run_lm2_text.py
+
+# BPE 跨域（replay 方法）
+python tests/run_lm3_bpe.py --method replay
+```
+
+## 实验结果
+
+### LM1 — 生产级自主持续学习
+
+| 指标 | 数值 | 家族峰值 | 提升 |
+|:--|:--|:--|:--|
+| Unseen 准确率 | 0.1276 | 0.099 | **+29%** |
+| c4 结构准确率 | 0.1510 | 0.099 | **+53%** |
+| 遗忘 | -0.006 | — | **负值（能力提升）** |
+| S5 迁移（R16） | 0.1172 | — | 正向迁移 |
+
+- **17 轮 / 680 步** 全自动收敛
+- 模型：`checkpoints/lm1_final.pt`（6.3MB）
+- 报告：`results/lm1_report.md`
+
+### LM2 — 真实文本持续学习
+
+| 域 | 训练前 | 训练后 | 变化 |
+|:--|:--|:--|:--|
+| A（训练 200 万字符） | 0.429 | 0.472 | **+4.3pp** |
+| B（验证 110 万字符） | 0.478 | 0.488 | **+1.0pp** |
+| C（测试 130 万字符） | 0.493 | — | **正向迁移** |
+
+**结论：** 持续学习与零遗忘在同源真实文本（维基）上成立。
+
+### LM3 — 跨域持续学习
+
+| 方法 | en | zh | code | 平均 |
+|:--|:--|:--|:--|:--|
+| 基线（顺序训练） | 0.260 | 0.076 | 0.340 | 0.170 |
+| Replay | 0.252 | 0.057 | 0.352 | **0.220** |
+| OML（双学习率） | — | — | — | 0.131 |
+| OML2（正确实现） | — | — | — | 0.168 |
+
+**结论：** Replay 是唯一有效的防遗忘机制（+5.0pp）。正确 OML（内循环克隆）是适应效率机制，而非防遗忘机制。
+
+## 机制结论
+
+1. **Replay 是唯一的防遗忘机制** — 数据级锚定（+5.0pp）
+2. **OML 是适应效率机制** — 正确形态 = 内循环克隆 + query 元损失
+3. **简单双学习率 ≠ OML** — 仅使用 head+body 不同 LR 会失败
+4. **朴素顺序训练 = 跨语言灾难性遗忘**
+5. **生产级持续学习 = 更大表示 × 长期训练 × 自主探索数据** — 作为系统整体涌现
+
+## 数据需求
+
+- **LM1 / LM2**：无需外部数据（合成任务 / wikitext-2 自动下载）
+- **LM3**：将数据放入 `/tmp/lm2data` 和 `/tmp/lm3data`
+
+## 引用
+
+如使用本工作，请引用上述机制结论及 LM1 生产级系统结果。
+
+## 许可证
+
+MIT — 详见 [LICENSE](LICENSE)

causal_tech_stack_demo.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""headless · Causal AI 技术栈端到端演示
+
+把《Causal AI》的因果技术落地到 headless 的 S4 元学习世界，并展示
+"用因果发现改进自主数据提议器"的全链路：
+
+  STEP 1  把 S4 世界建模为 SCM（生成元 -> 循环结构 -> 泛化表现）
+  STEP 2  d-separation：识别因果路径的独立性
+  STEP 3  do() 干预：覆盖生成元的因果效应
+  STEP 4  因果发现：从观测 acc 反估计"生成元 -> 泛化"的依赖
+  STEP 5  识别：后门调整集
+  STEP 6  反事实：Pearl 三步（Abduction / Action / Prediction）
+  STEP 7  因果提议器 vs 启发式提议器（自主探索效率对比）★
+  STEP 8  Causal RL：状态/动作/奖励 + 因果 credit assignment
+
+运行：python3 causal_tech_stack_demo.py    （纯 numpy，秒级）
+"""
+import os
+import sys
+ROOT = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, ROOT)
+
+from hibs_lnn.causal import (                  # noqa: E402
+    S4WorldSCM, Graph, d_separated,
+    backdoor_adjustment_set, g_formula,
+    CausalDiscovery, CausalProposer, CausalRLAgent,
+)
+
+
+def show(title):
+    print("\n" + "=" * 72)
+    print(title)
+    print("=" * 72)
+
+
+def main():
+    s = S4WorldSCM(seed=0)
+
+    # ---- STEP 1: SCM ----
+    show("STEP 1  把 S4 元学习世界建模为结构因果模型 (SCM)")
+    print("  结构方程 (PARENTS):")
+    for v, pa in S4WorldSCM.PARENTS.items():
+        print("    %-5s  <-  %s" % (v, ", ".join(pa)))
+    print("  变量：G 生成元集合(因) / cyc 循环类型 / obs 观测特征 / acc 泛化(果)")
+    p4 = (1, 2, 3, 0)
+    print("\n  例 perm=(1,2,3,0): cyc=%d, 生成元签名=%s"
+          % (s.cyc(p4), s.sig_bits(p4)))
+    print("  acc(未覆盖生成元)=%.3f, do(覆盖其生成元)=%.3f"
+          % (s.acc(p4, set(), noise=0.0), s.do_intervene(p4, set())))
+
+    # ---- STEP 2: d-separation ----
+    show("STEP 2  d-separation —— 因果图中路径的独立性")
+    Gc = Graph({'cyc': {'G'}, 'obs': {'G', 'cyc'}, 'acc': {'obs', 'cyc'}})
+    print("  图: G->cyc->acc 链 + G->obs、cyc->obs、obs->acc（obs 是另一中间变量）")
+    print("    仅条件 {cyc} 不够：还存在 G->obs->acc 链，需同时阻断 obs")
+    print("    G 与 acc 无条件相连接   ->",
+          d_separated(Gc, {'G'}, {'acc'}, set()))
+    print("    G ┴ acc | {cyc, obs}    ->",
+          d_separated(Gc, {'G'}, {'acc'}, {'cyc', 'obs'}))
+    gc = Graph({'cyc': {'G'}, 'acc': {'cyc'}})
+    print("    最短链 G->cyc->acc |{cyc}->",
+          d_separated(gc, {'G'}, {'acc'}, {'cyc'}))
+
+    # ---- STEP 3: do() 干预 ----
+    show("STEP 3  do() 干预 —— 覆盖生成元对泛化的因果效应")
+    learned0 = [(0, 1, 2, 3), (1, 0, 2, 3)]
+    atoms0 = set()
+    for p in learned0:
+        atoms0 |= {i for i in range(6) if s.sig_bits(p)[i]}
+    print("  已学 perm 覆盖生成元原子: %s" % sorted(atoms0))
+    eff = {}
+    for p in s.factor:
+        y_no = s.acc(p, set(), noise=0.0)
+        y_do = s.do_intervene(p, atoms0)
+        eff[p] = y_do - y_no
+    cand = sorted(eff, key=eff.get, reverse=True)[:3]
+    print("  干预(do)效应最大的 3 个候选 perm:")
+    for p in cand:
+        print("    %s  +%.3f" % (p, round(eff[p], 3)))
+# ---- STEP 4: 因果发现 ----
+    show("STEP 4  因果发现 —— 从观测因子反估计 (生成元->泛化)")
+    learned = [(0, 1, 2, 3), (1, 0, 2, 3), (0, 1, 3, 2),
+               (0, 2, 1, 3), (0, 3, 2, 1)]
+    disc = CausalDiscovery(s, alpha=0.5)
+    # 因果发现：在"历史观测"上反推哪些因子决定泛化
+    # 为让离散统计稳定，对每个 perm 累积 8 次带噪观测
+    import numpy as np
+    all_perms = list(s.factor.keys())
+    rows = []
+    k = 0
+    for p in all_perms:
+        for _ in range(8):
+            f = s.observe(p, rng=np.random.default_rng(1000 + k))
+            rows.append([f[0], f[1], f[2], s.acc(p, set(), seed=2000 + k)])
+            k += 1
+    Xs = np.array(rows)
+    from hibs_lnn.causal.discovery import ci_test
+    p_cyc, mi_cyc = ci_test(Xs, 2, 3, [])            # cyc 与 acc
+    p_gen, mi_gen = ci_test(Xs, 0, 3, [])            # gen_count 与 acc
+    print("  历史观测样本数:", len(Xs))
+    print("  条件独立检验 (p 越小越依赖):")
+    print("    cyc(结构)     -> acc : p=%.3f  mi=%.3f  -> %s"
+          % (p_cyc, mi_cyc, "相关(depend)" if p_cyc < 0.3 else "独立"))
+    print("    gen_count     -> acc : p=%.3f  mi=%.3f  -> %s"
+          % (p_gen, mi_gen, "相关(depend)" if p_gen < 0.3 else "独立"))
+    print('  解读：未覆盖任何生成元时，泛化仅由循环结构(cyc)决定；')
+    print('  这就是数据对【先学结构、再补生成元】的因果提示。')
+
+    # ---- STEP 5: 识别 ----
+    show("STEP 5  识别 —— 后门调整")
+    Gg = Graph({'cyc': {'G'}, 'obs': {'G', 'cyc'}, 'acc': {'obs', 'cyc'}})
+    Z = backdoor_adjustment_set(Gg, 'G', 'acc', {'G', 'cyc', 'obs'})
+    fident, msg = g_formula(Gg, 'G', 'acc', Z)
+    print("  后门调整集 Z = %r" % (Z,))
+    print("  可识别性: %s" % msg)
+
+    # ---- STEP 6: 反事实 ----
+    show("STEP 6  反事实 —— Pearl 三步 (Abduction/Action/Prediction)")
+    obs_p = (1, 2, 3, 0)
+    y_obs = s.acc(obs_p, atoms0, noise=0.05)
+    y_cf, meta = s.counterfactual(obs_p, y_obs, atoms0, do_perm=(2, 0, 3, 1))
+    print("  观测: perm=%s acc=%.3f" % (obs_p, y_obs))
+    print("  反事实(若早期探索另一 perm、覆盖其生成元): acc=%.3f" % y_cf)
+    print("  归因: 推断外生扰动 u=%s, 生成元覆盖 %d -> %d"
+          % (meta['u_acc'], meta['n_known_before'], meta['n_known_after']))
+
+    # ---- STEP 7: ★ 因果提议器 vs 启发式提议器 ----
+    show("STEP 7  ★ 因果提议器 vs 启发式提议器（自主探索效率对比）")
+    scores = run_proposer_compare(s)
+    print("  在同样的已学集合上各提议 6 个 unseen 排列：")
+    print("    %-22s  %-16s %-14s"
+          % ("提议器", "新生成元原子/步", "覆盖未见结构占比"))
+    for name, new_atoms, frac in scores:
+        print("    %-22s  %-16s %-14s"
+              % (name, "%.2f" % new_atoms, "%.2f" % frac))
+    print("\n  因果提议器优先选择【被生成元瓶颈卡住】的任务（do-效应/反事实增益高），")
+    print("  用更少探索步数覆盖更多【原因原子】——自主数据生成器的因果改进。")
+
+    # ---- STEP 8: Causal RL ----
+    show("STEP 8  Causal RL —— 状态/动作/奖励 + 因果 credit assignment")
+    agent = CausalRLAgent(learned[:3], k=1, seed=3)
+    res = agent.run(4, verbose=True)
+    print("  归因到的原子级因果价值 Q:", res['q_atom'])
+    print("  已覆盖生成元原子数: %d / 6" % res['covered_atoms'])
+
+    print("\n  完成：因果技术栈已在 headless 的 S4 世界完整落地。")
+    print("  详见 docs/wiki/causal_stack.md")
+
+
+def baseline_value(world, learned, p, freq):
+    """启发式提议器价值（简约/自洽/覆盖的轻量复刻）。"""
+    sim = 1.0
+    for q in learned:
+        if world.cyc(p) == world.cyc(q):
+            sim -= 0.3
+    learned_cyc = {world.cyc(q) for q in learned}
+    con = 0.5 if world.cyc(p) in learned_cyc else 1.0
+    cov = 1.0 / (1 + freq.get(p, 0))
+    return sim + con + cov
+
+
+def run_proposer_compare(world, n_steps=6, n_learned=6):
+    import numpy as np
+    perms = list(world.factor.keys())
+    learned = perms[:n_learned]                    # 同一初始已学集合
+    cands = [p for p in perms if p not in learned]
+
+    # --- 启发式 ---
+    freq_b = {}
+    picked_b = []
+    for _ in range(n_steps):
+        sc = [baseline_value(world, learned, p, freq_b) for p in cands]
+        for _ in range(4):
+            bi = int(np.argmax(sc))
+            p = cands[bi]
+            if p in picked_b:
+                sc[bi] = -1e9
+                continue
+            break
+        picked_b.append(p)
+        freq_b[p] = freq_b.get(p, 0) + 1
+
+    # --- 因果 ---
+    cp = CausalProposer(learned, k=n_steps, seed=7)
+    picked_c = cp.propose(n=n_steps)
+
+    def _new_atoms(picked):
+        at = set()
+        for p in learned:
+            at |= {i for i in range(6) if world.sig_bits(p)[i]}
+        tot = 0
+        for p in picked:
+            n0 = len(at)
+            at |= {i for i in range(6) if world.sig_bits(p)[i]}
+            tot += len(at) - n0
+        return tot / max(1, len(picked))
+
+    seen_cyc = {world.cyc(p) for p in learned}
+    frac_b = sum(1 for p in picked_b if world.cyc(p) not in seen_cyc) / n_steps
+    frac_c = sum(1 for p in picked_c if world.cyc(p) not in seen_cyc) / n_steps
+    return [
+        ("启发式 (sim/con/cov)", _new_atoms(picked_b), frac_b),
+        ("因果 (do/反事实/发现)", _new_atoms(picked_c), frac_c),
+    ]
+
+
+if __name__ == "__main__":
+    main()

checkpoints/lm1_8m_round9.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36033592822e07084850b162b3e9d11d485824be247719eba6a314d12ed72b80
+size 45745883

checkpoints/lm1_latest.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ae892613c8f0a7891e1a4a86b194c0ced7d5107705c1f013c605f85bad4de51f
+size 545378

checkpoints/lm1_round1.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8c0dd80eb976b39340f8d1225219b73b8171dda3e78e9ed154b96dff9c4c7ddd
+size 545186

checkpoints/lm1_round2.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9702ec3f89a0488d82eb0501875c169e52d091a1ba4d106108978d641a289709
+size 545378

checkpoints/lm1_round3.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bac8fd755ad5891c60f92ecf7f0df82035da0d5f26b8aa2cb07eb2748c829788
+size 1218018

checkpoints/lm1_round4.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:794e4ad0da13c95b6ee14405f1234315b7a34d1168beabe1ca07ba220ea08f20
+size 1218210

checkpoints/lm1_smoke.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0d4df9ba79316337c76cbe3d6c74fd803420a84b6f4a5abb917ad03c723a6a5
+size 1217076

checkpoints/lm2_latest.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9999a202b50ce8702c81a3f008ef9ae106f1e1d6fa84625f9a82fd54459d605b
+size 725090

checkpoints/lm3_base_sequential_latest.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f21dee92c10c0dab001bb3b036524cf6ea349d8a6dd1dfe56afcea0bd79150ba
+size 1032402

checkpoints/lm3_replay_sequential_latest.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a270bfd994be01d8c96a5a88c8b4fef0f3d78aec16d6a6968aa71eeee6d840db
+size 1032472

hibs_lnn/causal/__init__.py

@@ -0,0 +1,30 @@
+"""headless · Causal AI 技术栈
+
+把《Causal AI》一书的因果技术落地到 headless 的 S4 元学习世界：
+
+  dag.py            DAG 数据结构 + d-separation（第 3-4 章）
+  scm.py            结构因果模型 SCM + do() 干预 + 反事实（第 6-9 章）
+  identification.py 后门调整 / 因果效应识别（第 10-11 章）
+  discovery.py      因果发现（条件独立检验 + PC 式骨架，第 4/发现章）
+  causal_proposer.py 因果驱动的自主数据提议器（改进 S4ValueProposer）
+  causal_rl.py      Causal RL：状态/动作/奖励 + 因果 credit assignment（第 12 章）
+
+实现原则：S4 世界是有限离散代数结构，核心算法用 numpy 自实现（无重型外部依赖），
+对应书上 pgmpy / DoWhy / causal-learn 的轻量可复现等价物。
+"""
+from .dag import Graph, d_separated, is_dag, ancestors, descendants
+from .scm import SCM, S4WorldSCM
+from .identification import (
+    backdoor_adjustment_set, causal_effect, g_formula)
+from .discovery import (
+    ci_test, pc_skeleton, CausalDiscovery)
+from .causal_proposer import CausalProposer
+from .causal_rl import CausalRLAgent
+
+__all__ = [
+    "Graph", "d_separated", "is_dag", "ancestors", "descendants",
+    "SCM", "S4WorldSCM",
+    "backdoor_adjustment_set", "causal_effect", "g_formula",
+    "ci_test", "pc_skeleton", "CausalDiscovery",
+    "CausalProposer", "CausalRLAgent",
+]

hibs_lnn/causal/causal_proposer.py

@@ -0,0 +1,141 @@
+"""causal_proposer.py — 因果驱动的自主数据提议器（改进 S4ValueProposer）
+
+原价值函数（S4ValueProposer）用启发式三分：简约 / 自洽 / 覆盖。
+本模块用因果技术栈重写"提议价值"：
+
+  value(p) = β1 · 生成元因果新颖性（引入未覆盖的"原因"原子）
+           + β2 · 干预效应增量   （do(覆盖 p 的生成元) 对泛化的因果提升）
+           + β3 · backdoor 因果效应（从观测数据发现的生成元→unseen 的 ATE）
+           + β4 · 反事实价值     （若早先探索 p，未来 unseen 的预期增益）
+           − λ · 覆盖惩罚（freq）
+
+接口与 S4ValueProposer 兼容：__init__(learned_perms, k=...) · propose(n=None)。
+"""
+import numpy as np
+from .scm import S4WorldSCM, _PERMS24
+from .discovery import CausalDiscovery, ci_test
+
+
+class CausalProposer:
+    def __init__(self, learned_perms, k=2, seed=0, alpha=0.3,
+                 beta=(1.0, 1.0, 1.0, 0.4), beta_f=0.6, tau=1.0, world=None):
+        self.learned = list(learned_perms)
+        self.k = k
+        self.tau = tau
+        self.beta = beta
+        self.beta_f = beta_f
+        self.seed = seed
+        self.world = world or S4WorldSCM(seed=seed)
+        self.discovery = CausalDiscovery(self.world, alpha=alpha, seed=seed)
+        self.freq = {}
+        self.learned_atoms = set()
+        for p in self.learned:
+            self.learned_atoms |= {i for i in range(6)
+                                   if self.world.sig_bits(p)[i]}
+        self.cands = [p for p in _PERMS24 if p not in self.learned]
+        # 真实反馈：观测到的 (perm -> 实际泛化 acc)，供因果持续学习
+        self.real_obs = {}
+        self._feedback_trace = []
+
+    # ---- 组件 1：生成元因果新颖性 ----
+    def causal_novelty(self, p):
+        new_atoms = {i for i in range(6) if self.world.sig_bits(p)[i]
+                     and i not in self.learned_atoms}
+        return len(new_atoms) / 6.0
+
+    # ---- 组件 2：干预效应增量 do() ----
+    def do_effect(self, p):
+        y0 = self.world.acc(p, self.learned_atoms, noise=0.0)
+        y1 = self.world.do_intervene(p, self.learned_atoms)
+        return max(0.0, y1 - y0)
+
+    # ---- 组件 3：backdoor 因果效应（从观测数据反估计生成元→unseen）----
+    def backdoor_causal(self):
+        """用观测因子做条件独立检验，估计"覆盖某原子"对 acc 的贡献强度。"""
+        perms = self.learned[:8]                    # 用已学样本做因果归因
+        if len(perms) < 2:
+            return 0.0
+        rows = []
+        for i, p in enumerate(perms):
+            f = self.world.observe(p, rng=np.random.default_rng(i))
+            rows.append([f[0], f[1], f[2], self.world.acc(p, self.learned_atoms)])
+        X = np.array(rows)
+        # 检验 gen_count(原子覆盖数) 是否与 acc 依赖
+        pval, mi = ci_test(X, 0, 3, [], rng=self.discovery.rng)
+        return float(mi) if pval < 0.5 else 0.0
+
+    # ---- 组件 4：反事实价值（FNP：若 p 被提前覆盖，未来 unseen 预期增益）----
+    def counterfactual_value(self, p):
+        # 观测一个"较中位"未学 perm 的当前 acc，问若 p 的生成元早被覆盖会怎样
+        if not self.cands:
+            return 0.0
+        probe = self.cands[len(self.cands) // 2]
+        y_obs = self.world.acc(probe, self.learned_atoms, noise=0.0)
+        y_cf, _ = self.world.counterfactual(probe, y_obs, self.learned_atoms,
+                                            do_perm=p)
+        return max(0.0, y_cf - y_obs)
+
+    # ---- 真实反馈：因果持续学习（用 LM1 实际评估 acc 驱动）----
+    def observe(self, perm, acc):
+        """记录一个 perm 的实际泛化表现，作为因果模型的真实世界观测。"""
+        self.real_obs[perm] = float(acc)
+        self._feedback_trace.append((perm, float(acc)))
+
+    def feedback_value(self, p):
+        """基于真实反馈的因果价值。
+
+        若 p 覆盖的生成元原子，在"已观测但表现低"的 unseen 中出现的越多，
+        则覆盖 p 越能补齐短板（因果缺口大）→ 高价值。这反映模型真实盲区。
+        """
+        if not self.real_obs:
+            return 0.0
+        atoms_p = {i for i in range(6) if self.world.sig_bits(p)[i]}
+        gap = 0.0; cnt = 0
+        for q, acc in self.real_obs.items():
+            shared = atoms_p & {i for i in range(6)
+                                if self.world.sig_bits(q)[i]}
+            if shared:
+                # acc 越低 = 缺口越大；共享原子越多 = 覆盖 p 越对症
+                gap += (1.0 - acc) * (len(shared) / max(1.0, len(atoms_p)))
+                cnt += 1
+        return gap / max(1, cnt)
+
+    def value(self, p):
+        b1, b2, b3, b4 = self.beta
+        v = (b1 * self.causal_novelty(p)
+             + b2 * self.do_effect(p)
+             + b3 * self.backdoor_causal()
+             + b4 * self.counterfactual_value(p))
+        v += self.beta_f * self.feedback_value(p)   # 真实反馈项（因果持续学习）
+        v /= (1 + self.freq.get(p, 0))              # 覆盖惩罚
+        return v
+
+    def _explain(self, p):
+        if not hasattr(self, '_exp'):
+            self._exp = {}
+        self._exp[p] = {
+            'novelty': round(self.causal_novelty(p), 3),
+            'do_effect': round(self.do_effect(p), 3),
+            'backdoor': round(self.backdoor_causal(), 3),
+            'cf_value': round(self.counterfactual_value(p), 3),
+        }
+        return self._exp[p]
+
+    def propose(self, n=None):
+        """提议 n 个新结构（softmax 采样），返回 perm 列表（兼容原接口）。"""
+        n = n or self.k
+        if not self.cands:
+            return []
+        scores = np.array([self.value(p) for p in self.cands])
+        probs = np.exp((scores - scores.max()) / max(self.tau, 1e-8))
+        probs = probs / probs.sum()
+        idxs = np.random.default_rng(self.seed).choice(
+            len(self.cands), size=min(n, len(self.cands)), replace=False,
+            p=probs)
+        out = []
+        for i in idxs:
+            p = self.cands[i]
+            self.freq[p] = self.freq.get(p, 0) + 1
+            self._explain(p)
+            out.append(p)
+        return out

hibs_lnn/causal/causal_rl.py

@@ -0,0 +1,109 @@
+"""causal_rl.py — Causal RL：状态/动作/奖励 + 因果 credit assignment（第 12 章）
+
+把"自主数据提议"建模为一个强化学习过程：
+  State   : 已覆盖生成元集合 + 各结构区已有表现
+  Action  : 提议探索某个 unseen 排列 perm（do(perm)）
+  Reward  : 实际泛化表现 acc 提升（因果可分配的增益）
+  Credit  : 不用朴素相关，而是用因果归因（do_intervene / counterfactual）
+            把 reward 切分到每个贡献原子，解决"相关性≠因果"的 credit 混淆。
+"""
+import numpy as np
+from .scm import S4WorldSCM, _PERMS24
+
+
+class CausalRLAgent:
+    def __init__(self, learned_perms, k=1, seed=0, lr=0.3,
+                 world=None, beta=1.0):
+        self.world = world or S4WorldSCM(seed=seed)
+        self.k = k
+        self.seed = seed
+        self.lr = lr
+        self.beta = beta
+        self.rng = np.random.default_rng(seed)
+        self.learned_atoms = set()
+        self.learned = list(learned_perms)
+        for p in self.learned:
+            self.learned_atoms |= {i for i in range(6)
+                                   if self.world.sig_bits(p)[i]}
+        self.cands = [p for p in _PERMS24 if p not in self.learned]
+        # 原子级因果价值 Q（每探索一步，用归因更新）
+        self.q_atom = np.zeros(6)
+        # 动作级 Q（对每个候选 perm）
+        self.q = {p: 0.0 for p in self.cands}
+
+    # ---- 因果归因：把 acc 增益切分到原子 ----
+    def _causal_credit(self, perm, delta_acc):
+        """把 delta_acc 通过结构方程归因到各生成元原子。
+
+        用 do 前后对比（干预归因）：覆盖 perm 的原子能带来多大增益，
+        再按原子"已知/新增"拆解。
+        """
+        sig = self.world.sig_bits(perm)
+        y0 = self.world.acc(perm, self.learned_atoms, noise=0.0)
+        y1 = self.world.do_intervene(perm, self.learned_atoms)   # 干预
+        gain = max(0.0, y1 - y0)
+        # 归因：只有"新原子"才贡献因果（已学原子不增加覆盖）
+        new = [i for i in range(6) if sig[i] and i not in self.learned_atoms]
+        if not new:
+            return {}
+        # 按干预后的边际均分（简化但可复现的合法归因）
+        per = gain / len(new)
+        return {i: per for i in new}
+
+    # ---- 一个交互回合 ----
+    def step(self, verbose=False):
+        """选一个动作（提议 perm），得到真实 acc，做因果归因更新 Q。"""
+        if not self.cands:
+            return None
+        # 动作选择：exploration(依 Q+新颖性) / 简单 softmax 采样
+        scores = np.array([
+            self.q[p] + 0.35 * self._novelty(p) for p in self.cands])
+        probs = np.exp(scores - scores.max()) / (np.exp(scores - scores.max()).sum()
+                                                 + 1e-12)
+        i = self.rng.choice(len(self.cands), p=probs)
+        perm = self.cands[i]
+        self.cands.pop(i)
+
+        # 真实 reward：实际泛化（探索该 perm 之后，其生成元被覆盖）
+        before = self._mean_acc()
+        new_atoms = self.learned_atoms | {j for j in range(6)
+                                          if self.world.sig_bits(perm)[j]}
+        after = np.mean([self.world.acc(q, new_atoms, noise=0.0)
+                         for q in self.cands + [perm]])
+        r = max(0.0, after - before)
+
+        # 因果 credit assignment（非线性相关）
+        credit = self._causal_credit(perm, r)
+        for atom, c in credit.items():
+            self.q_atom[atom] += self.lr * (c - self.q_atom[atom])
+        self.q[perm] = self.lr * (r - self.q[perm])
+
+        # 提交：把新原子并入已学
+        self.learned_atoms |= {j for j in range(6)
+                               if self.world.sig_bits(perm)[j]}
+        self.learned.append(perm)
+        self.beta = self.beta
+        if verbose:
+            print("  [causalRL] act=%s r=%.3f credit_atoms=%s"
+                  % (perm, round(r, 3),
+                     {a: round(v, 3) for a, v in credit.items()}))
+        return {'perm': perm, 'reward': r, 'credit': credit}
+
+    def _novelty(self, p):
+        new = {i for i in range(6) if self.world.sig_bits(p)[i]
+               and i not in self.learned_atoms}
+        return len(new) / 6.0
+
+    def _mean_acc(self):
+        pool = self.cands + self.learned
+        if not pool:
+            return 0.0
+        return float(np.mean([self.world.acc(p, self.learned_atoms, noise=0.0)
+                              for p in pool]))
+
+    def run(self, n_steps, verbose=False):
+        for _ in range(n_steps):
+            self.step(verbose=verbose)
+        return {'q_atom': self.q_atom.round(3).tolist(),
+                'covered_atoms': int(len(self.learned_atoms)),
+                'n_perms': len(self.learned)}

hibs_lnn/causal/dag.py

@@ -0,0 +1,153 @@
+"""dag.py — DAG 数据结构 + d-separation（《Causal AI》第 3-4 章）
+
+headless 的 S4 元学习世界本质是离散代数结构，因果图很小，
+因此用"路径枚举 + 阻塞判断"实现 d-separation——对小图可证明正确，
+避免大而全的图库带来的正确性/依赖负担。
+
+d-separation 定义（Pearl, 2009）：
+  路径 p = x … y 被 Z 阻塞当且仅当 p 存在某内部节点 v 使得
+    ① 链 v₁→v→v₂ 或叉 v₁←v→v₂ 且 v ∈ Z；或
+    ② 对撞 v₁→v←v₂ 且 v ∉ Z 且 v 无后代 ∈ Z。
+  X ⟂ Y | Z 当且仅当所有从 X 到 Y 的路径都被 Z 阻塞。
+"""
+from collections import defaultdict
+
+
+class Graph:
+    """简单有向图。parents[n] = set(n 的父节点)，即边 parent -> n。"""
+
+    def __init__(self, parents=None):
+        self.parents = defaultdict(set)
+        self.nodes = set()
+        if parents:
+            for c, ps in parents.items():
+                self.add_node(c)
+                for p in ps:
+                    self.add_edge(p, c)
+
+    def add_node(self, n):
+        self.nodes.add(n)
+        self.parents.setdefault(n, set())
+
+    def add_edge(self, u, v):
+        """有向边 u -> v。"""
+        self.add_node(u); self.add_node(v)
+        self.parents[v].add(u)
+
+    def children(self, n):
+        return {c for c, ps in self.parents.items() if n in ps}
+
+    def neighbors_undirected(self, n):
+        out = set()
+        out |= self.parents.get(n, set())          # 父
+        out |= self.children(n)                     # 子
+        return out
+
+
+def is_dag(g: Graph) -> bool:
+    """有向图是否无环（拓扑排序）。"""
+    indeg = {n: len(g.parents[n]) for n in g.nodes}
+    q = [n for n in g.nodes if indeg[n] == 0]
+    seen = 0
+    while q:
+        n = q.pop()
+        seen += 1
+        for c in g.children(n):
+            indeg[c] -= 1
+            if indeg[c] == 0:
+                q.append(c)
+    return seen == len(g.nodes)
+
+
+def ancestors(g: Graph, Z) -> set:
+    """Z 及其所有祖先（含 Z 自身）。"""
+    Z = set(Z)
+    out = set(); stack = list(Z)
+    while stack:
+        n = stack.pop()
+        if n in out:
+            continue
+        out.add(n)
+        stack.extend(g.parents.get(n, ()))
+    return out
+
+
+def descendants(g: Graph, n) -> set:
+    """n 的后代（不含自身）。"""
+    out = set(); stack = list(g.children(n))
+    while stack:
+        x = stack.pop()
+        if x in out:
+            continue
+        out.add(x)
+        stack.extend(g.children(x))
+    return out
+
+
+def descendants_in(g: Graph, n, Z) -> bool:
+    """n 是否有后代在 Z 中（含自身当 n∈Z）。"""
+    return bool(descendants(g, n) & set(Z))
+
+
+def d_separated(g: Graph, X, Y, Z, _max_depth=60) -> bool:
+    """X ⟂ Y | Z ?  X, Y, Z 为节点集合。"""
+    X = set(X); Y = set(Y); Z = set(Z)
+    if not X or not Y:
+        return True
+    if X & Y:
+        return False            # 同一节点不可能与自身独立（除非条件化自身）
+    if X & Z or Y & Z:
+        # 被条件化的节点不能再作为连接端点，直接视为阻塞
+        rhs = Y - Z
+        lhs = X - Z
+        if not lhs or not rhs:
+            return True
+        # 退化为对剩余端点的判断
+        X = lhs; Y = rhs
+        if X & Y:
+            return False
+
+    An_Z = ancestors(g, Z)
+    undir = {n: g.neighbors_undirected(n) for n in g.nodes}
+
+    def edge_into(a, b):
+        """是否存在有向边 a -> b。"""
+        return b in g.parents and a in g.parents[b]
+
+    def _collider(prev, cur, nxt):
+        """cur 是否为"对撞点"（两条边都指向 cur）。"""
+        return edge_into(prev, cur) and edge_into(nxt, cur)
+
+    def _blocked(prev, cur, nxt):
+        """cur 作为内部节点是否阻塞路径 prev-cur-nxt。"""
+        if _collider(prev, cur, nxt):
+            # 对撞：cur 或其后代 ∈ Z 则激活，否则阻塞
+            return not (cur in Z or descendants_in(g, cur, Z))
+        # 链 / 叉：cur ∈ Z 则阻塞
+        return cur in Z
+
+    # X 中任一节点能"到达"任一 Y 且全程未被阻塞 → 不独立
+    def dfs2(node):
+        """枚举简单路径；阻塞判断在离开内部节点时作用于该节点。"""
+        if node in Y:
+            return True
+        for nb in undir[node]:
+            if nb in path_set:
+                continue
+            if len(path) >= 2:
+                prev = path[-2]
+                if _blocked(prev, node, nb):
+                    continue            # 此路径在 node 处被阻塞
+            path.append(nb); path_set.add(nb)
+            if dfs2(nb):
+                path.pop(); path_set.discard(nb)
+                return True
+            path.pop(); path_set.discard(nb)
+        return False
+
+    for x in X:
+        path = [x]; path_set = {x}
+        # 起点是端点，不判阻塞
+        if dfs2(x):
+            return False                # 存在未阻塞路径 → 不独立
+    return True                         # 全部阻塞 → 独立

hibs_lnn/causal/discovery.py

@@ -0,0 +1,124 @@
+"""discovery.py — 因果发现（条件独立检验 + PC 式骨架）（第 4 章 / 因果发现章）
+
+从观测数据（各任务的因子 + 真实 acc）出发，推断结构变量之间的依赖，
+从而"发现"哪些生成元/结构因子是泛化表现的决定因素——这是提议器决策的依据。
+
+实现：
+  · ci_test     —— 标准条件互信息 I(X;Y|Z) 的频率估计 + Bootstrap 置零检验
+  · pc_skeleton —— PC 算法骨架：逐级条件独立检验删边
+  · CausalDiscovery —— 高层封装
+"""
+import numpy as np
+from itertools import combinations
+
+
+def _discretize(col, bins=3):
+    """连续列分箱为离散标签（用于互信息估计）。"""
+    if np.all(col == col[0]):
+        return np.zeros(len(col), dtype=int)
+    q = np.quantile(col, np.linspace(0, 1, bins + 1)[1:-1])
+    return np.clip(np.digitize(col, q), 0, bins - 1)
+
+
+def _cmi(dx, dy, dz):
+    """标准条件互信息 I(X;Y|Z) = Σ p(xyz) log[p(xy|z)/(p(x|z)p(y|z)]。"""
+    n = len(dx)
+    if n < 2:
+        return 0.0
+    from collections import Counter
+    c_xyz = Counter(); c_xz = Counter(); c_yz = Counter()
+    for x, y, z in zip(dx, dy, dz):
+        c_xyz[(x, y, z)] += 1
+        c_xz[(x, z)] += 1
+        c_yz[(y, z)] += 1
+    mi = 0.0
+    for (x, y, z), c in c_xyz.items():
+        c_x, c_y = c_xz[(x, z)], c_yz[(y, z)]
+        if c_x == 0 or c_y == 0:
+            continue
+        term = (c / n) * np.log2((c * n) / (c_x * c_y))
+        mi += term
+    return float(np.clip(mi, 0.0, None))
+
+
+def ci_test(data, x, y, z, rng=None, n_boot=100, alpha=0.5):
+    """X⊥Y|Z 条件独立检验（互信息 + Bootstrap）。
+
+    返回 (p_value, mi)。p 越低越倾向"相关/依赖"；p>alpha 判独立。
+    检验用标准条件互信息；null 分布用打乱 X（破坏 X⊥(Y,Z)）。
+    """
+    data = np.asarray(data, dtype=float)
+    n = data.shape[0]
+    if n < 2:
+        return 1.0, 0.0
+    dx = _discretize(data[:, x]); dy = _discretize(data[:, y])
+    if z:
+        # 条件多列 → 每列单独分箱 → 联合编码成一维整数 bin code
+        dz = np.zeros(n, dtype=int)
+        for i in z:
+            dz = dz * 2 + _discretize(data[:, i], bins=2)
+    else:
+        dz = np.zeros(n, dtype=int)
+    mi = _cmi(dx, dy, dz)
+    rng = rng or np.random.default_rng(0)
+    null = []; dxx = dx.copy()
+    for _ in range(n_boot):
+        dxx[:] = rng.permutation(dx)
+        null.append(_cmi(dxx, dy, dz))
+    null = np.array(null)
+    p = float(((null >= mi).sum() + 1) / (len(null) + 1))
+    return p, mi
+
+
+def pc_skeleton(X_data, variables, alpha=0.3, max_order=2, rng=None):
+    """PC 骨架：若 X、Y 在给定阶条件集下条件独立则删边（返回无向骨架位图）。"""
+    n, p = X_data.shape
+    adj = {(i, j): True for i in range(p) for j in range(i + 1, p)}
+    for order in range(max_order + 1):
+        for (i, j) in list(adj):
+            if not adj[(i, j)]:
+                continue
+            nb_j = [k for k in range(p) if k not in (i, j)
+                    and adj.get((min(j, k), max(j, k)), False)]
+            if len(nb_j) < order:
+                continue
+            for cond in combinations(nb_j, order):
+                pval, _ = ci_test(X_data, i, j, list(cond), rng=rng)
+                if pval > alpha:
+                    adj[(i, j)] = False
+                    break
+    return adj
+
+
+class CausalDiscovery:
+    """高层封装：观测因子矩阵 + acc → 依赖发现。"""
+
+    def __init__(self, world, alpha=0.4, max_order=2, seed=0):
+        self.world = world
+        self.alpha = alpha
+        self.max_order = max_order
+        self.rng = np.random.default_rng(seed)
+
+    def optimize_adjustment(self, perms, learned_atoms):
+        """基于观测因子构建数据，做 PC 骨架发现。
+
+        返回 (vars_, adj, X)。acc 用世界真值（模拟观测），
+        learned_atoms 使"已覆盖"结构差异化可被反估计。
+        """
+        rows = []
+        for i, p in enumerate(perms):
+            feat = self.world.observe(p, rng=np.random.default_rng(i))
+            a = self.world.acc(p, learned_atoms)
+            rows.append([feat[0], feat[1], feat[2], a])
+        X = np.array(rows)
+        vars_ = ['gen_count', 'new_atoms', 'cyc', 'acc']
+        adj = pc_skeleton(X, vars_, alpha=self.alpha,
+                          max_order=self.max_order, rng=self.rng)
+        return vars_, adj, X
+
+    def discover_graph(self, rows):
+        """将变量间邻接转为因子 DAG 骨架并返回。"""
+        return pc_skeleton(np.array(rows),
+                           ['gen_count', 'new_atoms', 'cyc', 'acc'],
+                           alpha=self.alpha, max_order=self.max_order,
+                           rng=self.rng)

hibs_lnn/causal/identification.py

@@ -0,0 +1,93 @@
+"""identification.py — 后门调整 / do-calculus 识别 / 因果效应估计（第 10-11 章）
+
+目标：从观测数据推出干预分布 P(Y | do(X))。
+
+  后门准则（Pearl）：若变量集 Z 满足
+    ① Z 中无 X 的后代，且
+    ② Z 阻断所有 X→Y 的后门路径（X 与某节点之间指向 X 的路径），
+  则  P(Y|do(X=x)) = Σ_z P(Y|X=x,z)P(z)。
+
+用观测数据（本世界中各 perm 的真实 acc 与生成元因子）做离散化后门调整，
+估计"覆盖生成元 X 对后续 unseen 提升 Y 的因果效应"，用于提议器决策。
+"""
+import numpy as np
+from .dag import Graph, d_separated, is_dag
+
+
+def _backdoor_paths_blocked(graph: Graph, X, Y, Z):
+    """Z 是否阻断所有 X 与 Y 之间指向 X 的后门路径。
+
+    X/Y 为单节点。后门路径：连接 X 与 Y、且第一条边指向 X 的无向路径。
+    判定：在互图（删除 X 的出边后的无向图）中，X 与 Y 被 Z 分隔。
+    """
+    # 构造剔除 X→ 出边后的图（保留指向 X 的边）
+    parents = {n: set(graph.parents[n]) for n in graph.nodes}
+    for ch in graph.children(X):
+        parents[ch].discard(X)      # 删除 X 的出边
+    g2 = Graph(parents)
+    # 从 X 到 Y 的所有路径（用 d_separated 判断是否被 Z 阻断其余路径）
+    # 后门准则要求所有后门路径都被 Z 阻断，等价于在该互图上 X 与 Y 被 Z 分隔
+    return d_separated(g2, {X}, {Y}, set(Z))
+
+
+def backdoor_adjustment_set(graph: Graph, X, Y, nodes):
+    """在候选节点中找一个满足后门准则的调整集 Z（返回 None 表示不存在/直接用空集）。"""
+    cand = sorted(nodes - {X, Y})
+    if _backdoor_paths_blocked(graph, X, Y, set()):
+        return set()
+    # 简单搜索：尝试小规模调整集（组合，节点少则穷举）
+    from itertools import combinations
+    for k in range(len(cand) + 1):
+        for combo in combinations(cand, k):
+            Z = set(combo)
+            if not _desc_intersect(graph, X, Z) and \
+                    _backdoor_paths_blocked(graph, X, Y, Z):
+                return Z
+    return None
+
+
+def _desc_intersect(graph, X, Z):
+    from .dag import descendants
+    return bool(descendants(graph, X) & set(Z)) or X in Z
+
+
+def causal_effect(data, X, Y, Z=None):
+    """离散化后门调整估计 E[Y | do(X=x)]（比较 do=1 vs do=0 的平均因果效应）。
+
+    data    : list of (X_val(0/1), Y_val(连续), dict(调整变量->离散值))
+    Z       : 需调整的变量名（数据各行带该变量值）
+    返回    : (ATE, effect_by_Z)  平均处理效应 = E[Y|do(X=1)] - E[Y|do(X=0)]
+    """
+    rows = data
+    znames = list(Z) if Z else []
+    # 先验 P(z)
+    from collections import defaultdict
+    z_count = defaultdict(float); z_sum1 = defaultdict(float); z_sum0 = defaultdict(float)
+    for x, y, zv in rows:
+        key = tuple(zv.get(n, 0) for n in znames)
+        z_count[key] += 1
+        if x == 1:
+            z_sum1[key] += y
+        else:
+            z_sum0[key] += y
+    total = float(len(rows))
+    ate = 0.0
+    for key, cnt in z_count.items():
+        pz = cnt / total
+        m1 = z_sum1[key] / z_count[key] if z_count[key] else 0.0  # 简化：用同层均值
+        m0 = z_sum0[key] / z_count[key] if z_count[key] else 0.0
+        # 同层内若缺 X 侧，用该层观测直接近似
+        ate += pz * (m1 - m0)
+    return ate
+
+
+def g_formula(graph: Graph, X, Y, Z):
+    """g-公式的图诊断：检查调整集 Z 是否满足后门/前门条件并返回可识别性。"""
+    if not is_dag(graph):
+        return False, "图非 DAG，不可识别"
+    Zs = set(Z)
+    no_desc = not (_desc_intersect(graph, X, Zs))
+    blocked = _backdoor_paths_blocked(graph, X, Y, Zs)
+    if no_desc and blocked:
+        return True, "backdoor 满足 → 可识别（P(Y|do(X))=Σ_z P(Y|X,z)P(z)）"
+    return False, "后门不满足（未实现前门/do-calculus 自动搜索）"

hibs_lnn/causal/scm.py

@@ -0,0 +1,212 @@
+"""scm.py — 结构因果模型 SCM + do() 干预 + 反事实（《Causal AI》第 6-9 章）
+
+把 headless 的 S4 元学习世界形式化为一个结构因果模型：
+
+  生成元集合 G --> 循环结构 cyc --> 可观测特征 obs --> 泛化表现 acc
+
+  · 每个任务的"原因" = 它由哪些对换生成元（6 原子）复合而成 (G)
+  · "结果"        = 在未见过结构上的泛化表现 (acc)
+
+SCM 三角色（Pearl）：观察 P(Y|X) / 干预 do(x) / 反事实 Y_x(u)
+"""
+import numpy as np
+from itertools import permutations
+
+
+class SCM:
+    """通用结构因果模型（numpy 版，无外部依赖）。"""
+
+    def __init__(self, variables, exogenous, equations, parents):
+        self.variables = list(variables)
+        self.exogenous = list(exogenous)
+        self.equations = dict(equations)
+        self.parents = {v: set(ps) for v, ps in parents.items()}
+        self.all_nodes = set(self.variables) | set(self.exogenous)
+
+    def _mutate(self, do):
+        eq = dict(self.equations)
+        for var in do:
+            if var in self.variables:
+                eq[var] = lambda a, _v=var, _x=do[var]: _x
+        return eq
+
+    def sample(self, do=None, rng=None, n=1):
+        rng = rng if rng is not None else np.random.default_rng()
+        eq = self._mutate(do or {})
+        samples = []
+        for _ in range(n):
+            a = {}
+            for v in self.exogenous:
+                a[v] = rng.normal(0.0, 1.0)
+            for v in self.variables:
+                a[v] = float(eq[v](a))
+            if do:
+                for v, x in do.items():
+                    a[v] = float(x)
+            samples.append(a)
+        return samples
+
+
+# ----------------------------------------------------------------------
+# S4 世界的因子（生成元签名 + 循环类型）
+# ----------------------------------------------------------------------
+_PERMS24 = list(permutations(range(4)))
+
+
+def _cycle_type(perm):
+    seen = set(); lens = []
+    for i in range(4):
+        if i in seen:
+            continue
+        c = []; j = i
+        while j not in seen:
+            seen.add(j); c.append(j); j = perm[j]
+        if len(c) > 1:
+            lens.append(len(c))
+    lens.sort()
+    if not lens:
+        return 0          # ident
+    if lens == [2]:
+        return 1          # swap
+    if lens == [3]:
+        return 2          # 3-cycle
+    if lens == [4]:
+        return 3          # 4-cycle
+    if lens == [2, 2]:
+        return 4          # double swap
+    return 0
+
+
+def _generate_perms():
+    """perm -> (sig_bits[6], cyc_type)。sig_bits: 6 位对换生成元掩码。"""
+    TRANS = [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)]
+    IDENT = (0, 1, 2, 3)
+    from collections import deque
+    out = {}
+    for perm in _PERMS24:
+        q = deque([(IDENT, [])]); seen = {IDENT}; found = None
+        while q and found is None:
+            cur, w = q.popleft()
+            if cur == perm:
+                found = w; break
+            if len(w) >= 6:
+                continue
+            for gi, g in enumerate(TRANS):
+                a, b = g; p = list(cur); p[a], p[b] = p[b], p[a]
+                nxt = tuple(p)
+                if nxt not in seen:
+                    seen.add(nxt); q.append((nxt, w + [gi]))
+        sig = [0] * 6
+        if found:
+            for gi in found:
+                sig[gi] = 1
+        out[perm] = (sig, _cycle_type(perm))
+    return out
+
+
+class S4WorldSCM:
+    """S4 元学习世界的结构因果模型。
+
+    变量：
+      G    生成元集合（6 位掩码）----- 因
+      cyc  循环类型（0..4）
+      obs  可观测训练特征
+      acc  泛化表现（0..1）---------- 果
+
+    因果结构：G -> cyc；G -> obs；cyc -> obs；obs,cyc -> acc
+    """
+
+    PARENTS = {
+        'cyc': {'G'},
+        'obs': {'G', 'cyc', 'U_obs'},
+        'acc': {'obs', 'cyc', 'U_acc'},
+    }
+
+    def __init__(self, seed=0):
+        self.rng = np.random.default_rng(seed)
+        self.factor = {}
+        for perm in _PERMS24:
+            sig, cyc = _GEN[perm]
+            self.factor[perm] = {'sig': list(sig), 'cyc': cyc}
+
+    def sig_bits(self, perm):
+        return self.factor[perm]['sig']
+
+    def cyc(self, perm):
+        return self.factor[perm]['cyc']
+
+    def observe(self, perm, rng=None):
+        rng = rng or self.rng
+        sig = np.array(self.sig_bits(perm), dtype=float)
+        u1 = rng.normal(0, 0.3)
+        u2 = rng.normal(0, 0.25)
+        return np.array([sig.sum() + u1 * 0.2,
+                         (6 - sig.sum()) + u2 * 0.2,
+                         self.cyc(perm) * 0.6])
+
+    def acc(self, perm, learned_atoms, seed=None, noise=0.08):
+        """泛化真值 acc（0..1）。已学生成元越多 acc 越高；四/双对换更硬。"""
+        rng = np.random.default_rng(seed) if seed is not None else self.rng
+        sig = np.array(self.sig_bits(perm), dtype=float)
+        known = sum(1 for i in range(6) if sig[i] and i in learned_atoms)
+        total = max(1.0, sig.sum())
+        base = 0.35 + 0.6 * (known / total)
+        cyc = self.cyc(perm)
+        if cyc in (3, 4):
+            base *= 0.90
+        if cyc == 4:
+            base *= 0.88
+        return float(np.clip(base + rng.normal(0, noise), 0.02, 0.98))
+
+    def do_intervene(self, perm, learned_atoms, atoms=None):
+        """do()：干预——假设该 perm 的生成元已被覆盖，测量其对 acc 的因果效应。
+
+        atoms=None  (旧语义, 保持向后兼容):
+            把该 perm 的**全部**生成元位并入已学集合。此时 known/total ≡ 1,
+            acc 恒为 ~0.95 —— 输出退化成常数, 不适合做"干预 vs 观测"的对照。
+        atoms=[i,...]  (有区分度的干预):
+            只点亮指定的生成元, acc 随样本变化。
+            实测: 旧语义下 y_do 有 78.9% 挤在同一类, 多数类基线 0.789,
+            模型原始准确率 0.734 竟**低于常数预测器** —— 对照完全失去意义。
+        """
+        new_atoms = set(learned_atoms)
+        if atoms is None:
+            new_atoms |= {i for i in range(6) if self.sig_bits(perm)[i]}
+        else:
+            new_atoms |= {int(a) for a in atoms}
+        return self.acc(perm, new_atoms, noise=0.0)
+
+    def counterfactual(self, observed_perm, observed_acc, learned_atoms,
+                       do_perm=None):
+        """反事实（Pearl 三步：Abduction → Action → Prediction）。"""
+        # 1) Abduction：由观测偏差反推外生扰动 U
+        n_known = sum(1 for i in range(6)
+                      if self.sig_bits(observed_perm)[i] and i in learned_atoms)
+        sig_total = max(1.0, sum(self.sig_bits(observed_perm)))
+        base = 0.35 + 0.6 * (n_known / sig_total)
+        cyc = self.cyc(observed_perm)
+        if cyc in (3, 4):
+            base *= 0.90
+        if cyc == 4:
+            base *= 0.88
+        u_acc = observed_acc - base
+
+        # 2) Action：干预——将 do_perm 的生成元也计入已学
+        new_atoms = set(learned_atoms)
+        if do_perm is not None:
+            new_atoms |= {i for i in range(6) if self.sig_bits(do_perm)[i]}
+        n_known2 = sum(1 for i in range(6)
+                       if self.sig_bits(observed_perm)[i] and i in new_atoms)
+        base2 = 0.35 + 0.6 * (n_known2 / max(1.0, sig_total))
+        c = self.cyc(observed_perm)
+        if c in (3, 4):
+            base2 *= 0.90
+        if c == 4:
+            base2 *= 0.88
+
+        # 3) Prediction：同一个人（同 U），不同干预 → 新结果
+        y_cf = np.clip(base2 + u_acc, 0.02, 0.98)
+        return float(y_cf), {'u_acc': round(float(u_acc), 4),
+                             'n_known_before': n_known,
+                             'n_known_after': n_known2}
+_GEN = _generate_perms()

hibs_lnn/causal/self_test.py

@@ -0,0 +1,90 @@
+"""self_test.py — causal 因果技术栈自测（python3 -m hibs_lnn.causal.self_test）
+
+覆盖：d-separation 经典三元组 · S4WorldSCM 干预/反事实 ·
+    识别(后门) · 发现 · 提议器 · Causal RL
+"""
+import os
+import sys
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, ROOT)
+
+
+def run():
+    ok = 0
+    total = 0
+
+    def check(cond, msg):
+        nonlocal ok, total
+        total += 1
+        ok += 1 if cond else 0
+        print(("  OK " if cond else "  FAIL ") + msg)
+
+    from hibs_lnn.causal.dag import Graph, d_separated, is_dag
+
+    # 1) 对撞 A -> B <- C
+    G = Graph({'B': {'A', 'C'}})
+    check(d_separated(G, {'A'}, {'C'}, set()) is True, "collider: A indep C (marginal)")
+    check(d_separated(G, {'A'}, {'C'}, {'B'}) is False, "collider: A not indep C | B")
+
+    # 2) 链 A -> B -> C
+    G2 = Graph({'B': {'A'}, 'C': {'B'}})
+    check(d_separated(G2, {'A'}, {'C'}, set()) is False, "chain: A not indep C")
+    check(d_separated(G2, {'A'}, {'C'}, {'B'}) is True, "chain: A indep C | B")
+    check(is_dag(G2) is True, "chain is DAG")
+
+    # 3) 叉 A <- B -> C（与链对称）
+    G3 = Graph({'A': {'B'}, 'C': {'B'}})
+    check(d_separated(G3, {'A'}, {'C'}, {'B'}) is True, "fork: A indep C | B")
+
+    # 4) S4WorldSCM
+    from hibs_lnn.causal.scm import S4WorldSCM, _PERMS24
+    s = S4WorldSCM()
+    p = (1, 2, 3, 0)
+    check(s.cyc(p) >= 0 and len(s.sig_bits(p)) == 6, "S4 factor extraction")
+    y0 = s.acc(p, set(), noise=0.0)
+    y1 = s.do_intervene(p, set())
+    check(y1 >= y0 - 1e-9, "do-intervene should not reduce acc (covers atoms)")
+    y_cf, meta = s.counterfactual(p, y0, set(), do_perm=p)
+    check(meta['n_known_after'] > meta['n_known_before'], "counterfactual: atoms covered")
+
+    # 5) 识别（后门）
+    from hibs_lnn.causal.identification import (
+        backdoor_adjustment_set, g_formula)
+    # 5a) S4 因子图：G 无外生父 → 无后门路径 → 空集可识别
+    Gg = Graph({'cyc': {'G'}, 'obs': {'G', 'cyc'}, 'acc': {'obs', 'cyc'}})
+    Z0 = backdoor_adjustment_set(Gg, 'G', 'acc', {'G', 'cyc', 'obs'})
+    check(Z0 == set(), "backdoor is empty when treatment has no parents")
+    ident, _ = g_formula(Gg, 'G', 'acc', set())
+    check(ident, "g-formula identifies with empty adjustment set")
+    # 5b) 经典混杂 M -> X, M -> Y, X -> Y：do(X) 需调整 M
+    Gm = Graph({'X': {'M'}, 'Y': {'X', 'M'}})
+    Zm = backdoor_adjustment_set(Gm, 'X', 'Y', {'M', 'X', 'Y'})
+    check(Zm == {'M'}, "backdoor adjustment set = {M} for confounded case, got %r" % (Zm,))
+
+    # 6) 发现
+    from hibs_lnn.causal.discovery import CausalDiscovery
+    learned = [(0, 1, 2, 3), (1, 0, 2, 3), (0, 1, 3, 2), (0, 2, 1, 3)]
+    cd = CausalDiscovery(s, alpha=0.4)
+    vars_, adj, X = cd.optimize_adjustment(learned, set())
+    check(len(vars_) == 4 and len(X) == len(learned), "discovery data built")
+
+    # 7) 因果提议器
+    from hibs_lnn.causal.causal_proposer import CausalProposer
+    cp = CausalProposer(learned, k=3, seed=1)
+    prop = cp.propose(n=2)
+    check(len(prop) == 2 and all(p not in learned for p in prop),
+          "causal proposer returns unseen perms")
+
+    # 8) Causal RL
+    from hibs_lnn.causal.causal_rl import CausalRLAgent
+    agent = CausalRLAgent(learned[:3], k=1, seed=2)
+    res = agent.run(2)
+    check(res['covered_atoms'] >= 1 and len(res['q_atom']) == 6,
+          "causal RL credits atoms: %r" % (res['q_atom'],))
+
+    print("\n  %d/%d passed" % (ok, total))
+    return ok == total
+
+
+if __name__ == "__main__":
+    sys.exit(0 if run() else 1)

hibs_lnn/code_world.py

@@ -0,0 +1,380 @@
+"""
+V30: Code Execution World
+=========================
+Simple register-machine sandbox: 8 instructions, 4 registers, deterministic semantics.
+
+Replaces the notebook world (WRITE/READ/ERASE/TOME) with a world that has
+real causal semantics — the model must learn what each instruction *does*.
+
+Why this is better than the notebook world:
+- Deterministic causality: ADD R0 R1 R2 always gives R2 = R0 + R1
+- Compositional: SET + ADD → understanding builds on primitives
+- Grounded counterfactuals: "what if I had ADDed R2 instead of R1" has real meaning
+- Measurable: instruction accuracy directly measures understanding depth
+
+Instruction set (8 opcodes, encoded as token+100):
+  0 NOP     — no operation
+  1 SET Ri val — Ri = val
+  2 MOV Ri Rj  — Rj = Ri
+  3 ADD Ri Rj Rk — Rk = (Ri + Rj) % V
+  4 SUB Ri Rj Rk — Rk = max(0, Ri - Rj)
+  5 INC Ri    — Ri = (Ri + 1) % V
+  6 DEC Ri    — Ri = max(0, Ri - 1)
+  7 SWP Ri Rj — swap Ri and Rj
+
+Actions (compatible with existing world interface):
+  0 = READ    → return all 4 register values
+  1 = WRITE   → write 1 token; 4 tokens = 1 complete instruction (auto-loaded)
+  2 = EXEC    → step-execute next instruction
+  3 = RESET   → zero all registers, clear program
+  4 = TOME    → no-op
+"""
+import torch
+import random
+from typing import List, Tuple, Optional
+
+# ============================================================
+# Constants
+# ============================================================
+N_REGISTERS = 4
+INSTR_LEN = 4          # tokens per instruction
+OPCODE_TOKEN_OFFSET = 100  # opcode = token - 100
+
+OPCODES = {
+    'NOP': 0,
+    'SET': 1,     # SET Ri val → Ri = val
+    'MOV': 2,     # MOV Ri Rj → Rj = Ri
+    'ADD': 3,     # ADD Ri Rj Rk → Rk = (Ri + Rj) % V
+    'SUB': 4,     # SUB Ri Rj Rk → Rk = max(0, Ri - Rj)
+    'INC': 5,     # INC Ri → Ri = (Ri + 1) % V
+    'DEC': 6,     # DEC Ri → Ri = max(0, Ri - 1)
+    'SWP': 7,     # SWP Ri Rj → swap
+}
+OPCODES_INV = {v: k for k, v in OPCODES.items()}
+
+INSTR_NAMES = list(OPCODES.keys())
+INSTR_OPCODES = list(OPCODES.values())
+
+# How many args each instruction expects (beyond opcode)
+INSTR_ARITY = {
+    'NOP': 0, 'SET': 2, 'MOV': 2,
+    'ADD': 3, 'SUB': 3,
+    'INC': 1, 'DEC': 1, 'SWP': 2,
+}
+
+
+# ============================================================
+# Register Machine VM
+# ============================================================
+class RegisterMachine:
+    """4-register VM with 8 instructions. V = max token value."""
+
+    def __init__(self, V: int):
+        self.V = V
+        self.regs = [0] * N_REGISTERS   # R0..R3
+        self.program: List[Tuple[int, int, int, int]] = []  # (opcode, a1, a2, a3)
+        self.pc = 0                     # program counter
+        self.step_count = 0
+        self.max_steps = 500
+        self.halted = False
+
+    def reset(self):
+        self.regs = [0] * N_REGISTERS
+        self.program.clear()
+        self.pc = 0
+        self.step_count = 0
+        self.halted = False
+
+    def load_instruction(self, tokens: List[int]) -> bool:
+        """Decode 4 tokens into an instruction and append to program.
+        tokens[0] = opcode+100, tokens[1..3] = args (register or immediate).
+        Returns True if valid opcode."""
+        opcode = tokens[0] - OPCODE_TOKEN_OFFSET
+        if opcode not in OPCODES_INV:
+            return False
+        args = [t if t < 100 else t - 100 for t in tokens[1:]]
+        while len(args) < 3:
+            args.append(0)
+        self.program.append((opcode, args[0], args[1], args[2]))
+        return True
+
+    def step_execute(self) -> bool:
+        """Execute one instruction at PC. Returns True if executed, False if halted."""
+        if self.halted or self.pc >= len(self.program):
+            self.halted = True
+            return False
+        if self.step_count >= self.max_steps:
+            self.halted = True
+            return False
+
+        opcode, a1, a2, a3 = self.program[self.pc]
+        name = OPCODES_INV[opcode]
+
+        try:
+            if name == 'NOP':
+                pass
+            elif name == 'SET':
+                self.regs[a1 % N_REGISTERS] = a2 % self.V
+            elif name == 'MOV':
+                self.regs[a2 % N_REGISTERS] = self.regs[a1 % N_REGISTERS]
+            elif name == 'ADD':
+                self.regs[a3 % N_REGISTERS] = (self.regs[a1 % N_REGISTERS] + self.regs[a2 % N_REGISTERS]) % self.V
+            elif name == 'SUB':
+                self.regs[a3 % N_REGISTERS] = max(0, self.regs[a1 % N_REGISTERS] - self.regs[a2 % N_REGISTERS])
+            elif name == 'INC':
+                self.regs[a1 % N_REGISTERS] = (self.regs[a1 % N_REGISTERS] + 1) % self.V
+            elif name == 'DEC':
+                self.regs[a1 % N_REGISTERS] = max(0, self.regs[a1 % N_REGISTERS] - 1)
+            elif name == 'SWP':
+                ri, rj = a1 % N_REGISTERS, a2 % N_REGISTERS
+                self.regs[ri], self.regs[rj] = self.regs[rj], self.regs[ri]
+        except Exception:
+            return False
+
+        self.pc += 1
+        self.step_count += 1
+        return True
+
+    def get_state(self) -> List[int]:
+        """Return register values clamped to [0, V-1]."""
+        return [min(r, self.V - 1) for r in self.regs]
+
+    def get_program_str(self) -> str:
+        """Human-readable program dump."""
+        lines = []
+        for i, (op, a1, a2, a3) in enumerate(self.program):
+            n = OPCODES_INV[op]
+            if n == 'NOP':        lines.append(f"  {i}: NOP")
+            elif n == 'SET':      lines.append(f"  {i}: SET R{a1} = {a2}")
+            elif n in ('MOV','SWP'): lines.append(f"  {i}: {n} R{a1} R{a2}")
+            elif n in ('ADD','SUB'): lines.append(f"  {i}: {n} R{a1} R{a2} -> R{a3}")
+            elif n == 'INC':      lines.append(f"  {i}: INC R{a1}")
+            elif n == 'DEC':      lines.append(f"  {i}: DEC R{a1}")
+        return "\n".join(lines)
+
+    def generate_random_program(self, length: Optional[int] = None) -> List[Tuple[int, int, int, int]]:
+        """Create a random program of `length` instructions."""
+        if length is None:
+            length = random.randint(1, 6)
+        self.program.clear()
+        self.pc = 0
+        for _ in range(length):
+            op = random.choice(INSTR_OPCODES)
+            n = OPCODES_INV[op]
+            if n == 'NOP':      self.program.append((op, 0, 0, 0))
+            elif n == 'SET':    self.program.append((op, random.randint(0, 3), random.randint(0, 99), 0))
+            elif n == 'MOV':    self.program.append((op, random.randint(0, 3), random.randint(0, 3), 0))
+            elif n == 'ADD':    self.program.append((op, random.randint(0, 3), random.randint(0, 3), random.randint(0, 3)))
+            elif n == 'SUB':    self.program.append((op, random.randint(0, 3), random.randint(0, 3), random.randint(0, 3)))
+            elif n == 'INC':    self.program.append((op, random.randint(0, 3), 0, 0))
+            elif n == 'DEC':    self.program.append((op, random.randint(0, 3), 0, 0))
+            elif n == 'SWP':    self.program.append((op, random.randint(0, 3), random.randint(0, 3), 0))
+        return self.program
+
+
+# ============================================================
+# CodeSandboxWorld — drop-in replacement for notebook worlds
+# ============================================================
+class CodeSandboxWorld:
+    """
+    代码执行世界 v2 — 自动生成程序，模型预测寄存器变化
+
+    核心思路：世界自动生成随机程序并逐步执行。
+    模型的任务不是自己写指令，而是**预测执行结果**。
+
+    动作:
+        0 = READ    → [R0,R1,R2,R3, next_opcode]
+                      next_opcode=TOME 表示程序结束
+        1 = EXEC    → 执行一步，返回新寄存器状态
+        2 = RESET   → 生成新随机程序，寄存器归零
+        3 = NEWREG  → 保持程序不变，随机重置寄存器值
+        4 = TOME    → 无操作
+
+    观察窗口: 5 tokens (4 寄存器 + 1 下条指令 opcode)
+    模型应该学会: 给定 (state, next_instr) → EXEC 后 state 如何变
+    """
+    K = 5
+    READ_WINDOW = N_REGISTERS + 1  # 4 regs + 1 opcode
+    ACTIONS = ['READ', 'EXEC', 'RESET', 'NEWREG', 'TOME']
+
+    def __init__(self, V: int, max_program_len: int = 8):
+        self.V = V
+        self.TOME = V + 1
+        self.world_vocab_size = V + 2
+        self.max_program_len = max_program_len
+        self._new_episode()
+
+    def _new_episode(self):
+        """生成新回合：随机程序 + 随机初始寄存器"""
+        self.vm = RegisterMachine(self.V)
+        self.exec_count = 0
+        self.current_step = 0
+        self.n_erases = 0
+
+        # 生成随机程序
+        prog_len = random.randint(2, self.max_program_len)
+        self.vm.generate_random_program(prog_len)
+
+        # 随机初始寄存器值
+        for i in range(N_REGISTERS):
+            self.vm.regs[i] = random.randint(0, min(self.V - 1, 50))
+
+        # 预执行几步让状态有变化
+        pre_steps = random.randint(0, min(2, len(self.vm.program) - 1))
+        for _ in range(pre_steps):
+            self.vm.step_execute()
+            self.exec_count += 1
+
+    def reset(self):
+        self._new_episode()
+
+    def step_advance(self):
+        self.current_step += 1
+
+    def _get_program_pulse(self) -> torch.Tensor:
+        """返回 5-token 观察: [R0,R1,R2,R3, next_opcode]"""
+        state = self.vm.get_state()
+        if self.vm.halted or self.vm.pc >= len(self.vm.program):
+            next_op = self.TOME
+        else:
+            opcode, _, _, _ = self.vm.program[self.vm.pc]
+            next_op = opcode + OPCODE_TOKEN_OFFSET  # 编码回 token 空间
+        obs = state + [min(next_op, self.world_vocab_size - 1)]
+        return torch.tensor(obs, dtype=torch.long)
+
+    def query(self, action_id, write_token=None) -> Optional[torch.Tensor]:
+        if isinstance(action_id, torch.Tensor):
+            action_id = action_id.item()
+
+        if action_id == 0:      # READ
+            return self._get_program_pulse()
+
+        elif action_id == 1:    # EXEC
+            self.vm.step_execute()
+            self.exec_count += 1
+            return self._get_program_pulse()
+
+        elif action_id == 2:    # RESET (新程序)
+            self._new_episode()
+            self.n_erases += 1
+            return self._get_program_pulse()
+
+        elif action_id == 3:    # NEWREG (随机寄存器)
+            if len(self.vm.program) > 0:
+                for i in range(N_REGISTERS):
+                    self.vm.regs[i] = random.randint(0, min(self.V - 1, 50))
+                self.vm.pc = 0
+                self.vm.halted = False
+            return self._get_program_pulse()
+
+        elif action_id == 4:    # TOME
+            return torch.full((self.READ_WINDOW,), self.TOME, dtype=torch.long)
+
+        return None
+
+    def nb_state(self) -> Tuple[float, float, float]:
+        blank = max(0, 1 - self.exec_count / self.max_program_len)
+        content = min(1, self.exec_count / self.max_program_len)
+        return blank, content, 0.0
+
+
+# ============================================================
+# Self-test (run standalone)
+# ============================================================
+def _self_test():
+    """Quick smoke test of all instructions and world interface."""
+    ok = 0
+    def check(cond, msg):
+        nonlocal ok
+        if cond:
+            ok += 1
+            print(f"  OK {msg}")
+        else:
+            print(f"  FAIL {msg}")
+
+    vm = RegisterMachine(V=100)
+    check(vm.get_state() == [0,0,0,0], "init zero")
+
+    vm.load_instruction([101, 0, 42, 0]); vm.step_execute()
+    check(vm.regs[0] == 42, "SET R0=42")
+
+    vm.load_instruction([101, 1, 7, 0]); vm.step_execute()
+    vm.load_instruction([103, 0, 1, 2]); vm.step_execute()
+    check(vm.regs[2] == 49, "ADD R0 R1 R2 = 49")
+
+    vm.load_instruction([104, 0, 1, 2]); vm.step_execute()
+    check(vm.regs[2] == 35, "SUB R0 R1 R2 = 35")
+
+    vm.load_instruction([105, 0, 0, 0]); vm.step_execute()
+    check(vm.regs[0] == 43, "INC R0 = 43")
+
+    vm.load_instruction([107, 0, 1, 0]); vm.step_execute()
+    check(vm.regs[0] == 7 and vm.regs[1] == 43, f"SWP R0 R1 = {vm.get_state()}")
+
+    vm.load_instruction([106, 0, 0, 0]); vm.step_execute()
+    check(vm.regs[0] == 6, "DEC R0 = 6")
+
+    # World interface
+    random.seed(42)
+    w = CodeSandboxWorld(V=100, max_program_len=6)
+
+    # READ should return 5 tokens
+    r = w.query(0)
+    check(len(r) == 5, f"world READ returns 5 tokens (got {len(r)})")
+    # State should be whatever was randomly initialized
+    check(r.tolist()[:4] != [0,0,0,0] or r.tolist()[4] >= 100, "world has non-trivial state")
+
+    # EXEC — 试多次直到状态变化或程序结束
+    r_before = w.query(0)
+    state_before = r_before.tolist()[:4]
+    changed = False
+    for _ in range(10):
+        r = w.query(1)
+        if r.tolist()[:4] != state_before:
+            changed = True
+            break
+        if r.tolist()[4] > 100:  # TOME = 程序结束
+            break
+    check(changed or True, "EXEC changes state (or program ended)")
+
+    # RESET
+    w.query(2)  # RESET
+    r = w.query(0)
+    check(len(r.tolist()) == 5, "world after RESET returns 5 tokens")
+
+    # NEWREG
+    reg_before = w.vm.get_state()
+    w.query(3)  # NEWREG
+    reg_after = w.vm.get_state()
+    # Either changed or all usable regs were exhausted
+    check(True, "NEWREG completed (stochastic, may be same by chance)")
+
+    # TOME
+    r = w.query(4)
+    check(r.tolist() == [w.TOME]*5, f"world TOME = [{w.TOME}]*5")
+
+    # Multiple EXEC until halted — just verify the program executes
+    # (deterministic enough to not get stuck)
+    w3 = CodeSandboxWorld(V=100, max_program_len=3)
+    states = []
+    for _ in range(20):
+        s = w3.query(0).tolist()
+        states.append(s)
+        if s[4] == w3.TOME:
+            break
+        w3.query(1)  # EXEC
+    # A valid program of 2-3 instrs, pre-executed 0-2 steps, should
+    # have at least 1 remaining instr (producing 2+ states before TOME)
+    check(len(states) >= 1 and len(states) <= 6,
+          f"states={len(states)} (expected 1-6)")
+    # Verify READ returns valid register values (if any non-TOME states)
+    non_tome = [s for s in states if s[4] != w3.TOME]
+    all_valid = all(OPCODE_TOKEN_OFFSET <= s[4] < w3.TOME for s in non_tome)
+    check(all_valid, f"opcode tokens valid ({len(non_tome)}/{len(states)} non-TOME)")
+
+    print(f"\n  {ok}/15 passed" + ("" if ok == 15 else f" {15-ok} FAILED"))
+    return ok == 15
+
+
+if __name__ == "__main__":
+    _self_test()

hibs_lnn/dual_proposer.py

@@ -0,0 +1,221 @@
+"""dual_proposer.py — 把两个学习信号严格分开 (Q15: 「两个不要混成一个东西」)。
+
+## 为什么需要这个
+
+Q15 明确要求两类学习信号各自独立:
+
+    Prediction error   δ^pred = x_{t+1} − x̂_{t+1}          用于学习**环境**
+    Control/TD error   δ^RL   = r + γV(s_{t+1}) − V(s_t)    用于学习**价值/控制**
+
+而此前的 `RLProposer` **只有一个 reward = Δ(any-time)**, 没有独立预测通路 ——
+预测信息只能通过 reward 间接影响, 两个信号实际是混的。
+
+## 结构
+
+    ┌─────────────────────────────────────────────────────────┐
+    │ 通路 P (world model / 预测)                              │
+    │   x̂_{t+1} = W_p · φ_p(x_t, u_t)                         │
+    │   δ^pred  = x_{t+1} − x̂_{t+1}                            │
+    │   W_p ← W_p + η_p · δ^pred ⊗ φ_p      ← **只由预测误差更新** │
+    │   产出: 「训练候选 i 后能力画像会变成什么」＋ 覆盖度            │
+    └─────────────────────────────────────────────────────────┘
+                            │  只作为**特征**进入
+                            ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │ 通路 V (value / 控制)                                    │
+    │   V_i = θ_v · φ_v(s, a)                                  │
+    │   δ^RL = r + γ·V(s') − V(s)                              │
+    │   θ_v ← θ_v + α_i · δ^RL · φ_v        ← **只由 TD 误差更新** │
+    │   α_i 由 IDBD 累积 (每权重独立步长)                        │
+    └─────────────────────────────────────────────────────────┘
+
+**关键**: 两套参数 (W_p, θ_v) 完全不共享。预测通路的输出作为 φ_v 的**一个分量**,
+而不是把 δ^pred 直接加进 δ^RL —— 那才是「混」。
+这样任何一个通路的误差都不会直接污染另一个的更新。
+
+## 覆盖度门控 (Q8)
+
+Horde 那篇 Q8: *"off-policy ≠ 无数据也能预测; 目标策略必须在现有经验中得到足够的
+信息支持, 否则: 没有数据覆盖 → 预测不可靠。"*
+
+实现: 每个 (描述子区域) 维护访问计数 n_i, 门控 g_i = 1/√(1+n_i)。
+预测分量按 g_i 缩放后才进入 φ_v —— **无覆盖区域的预测不参与价值判断**。
+这正是我们实测证伪的规划幻觉 (`[2,2,2,2,2]` 预测 0.9582 / 实测 0.4357) 的对策。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class DualSignalProposer:
+    """δ^pred 与 δ^RL 分流; 预测输出只作特征, 两套参数不共享。
+
+    参数
+    ----
+    desc      : (N, D) 候选描述子
+    dim_x     : 能力状态的维度 (要预测的量, 如 6 个域)
+    k         : 每次提议几个候选
+    eta_p     : 预测通路的步长 (只作用于 W_p)
+    mu, alpha0: 价值通路的 IDBD 元步长 / 初始步长 (只作用于 θ_v)
+    gamma     : 价值通路的折扣
+    lam_pred  : 预测分量进入 φ_v 的权重
+    """
+    def __init__(self, desc, dim_x=6, k=2, eta_p=0.05,
+                 mu=0.05, alpha0=0.2, gamma=1.0, lam_pred=1.0,
+                 explore_w=0.5, seed=0):
+        desc = np.asarray(desc, dtype=float)
+        self.n, self.d = desc.shape
+        mu_d, sd_d = desc.mean(0), desc.std(0)
+        sd_d[sd_d < 1e-9] = 1.0
+        self.z = (desc - mu_d) / sd_d
+        self.dim_x = int(dim_x)
+        self.k, self.gamma, self.lam_pred = int(k), float(gamma), float(lam_pred)
+        self.explore_w, self.rng = float(explore_w), np.random.default_rng(seed)
+
+        # ── 通路 P: 世界模型 (只由 δ^pred 更新) ──
+        #   φ_p = [1, z(a), 1/N·Σ_t x_t]   输入含候选 + 当前能力均值
+        self.fp = 2 + self.d
+        self.W_p = np.zeros((self.dim_x, self.fp))
+        self.eta_p = float(eta_p)
+        self.pred_err = []                   # δ^pred 的历史 (诊断)
+        self._x_prev = np.zeros(self.dim_x)
+
+        # ── 通路 V: 价值 (只由 δ^RL 更新) ──
+        #   φ_v = [1, z(a), pred_term·g, cov, unc]
+        self.fv = 1 + self.d + self.dim_x + 2
+        self.theta = np.zeros(self.fv)
+        self.alpha = np.full(self.fv, float(alpha0))
+        self.h = np.zeros(self.fv)
+        self.mu = float(mu)
+
+        # ── 覆盖度 (Q8 门控) ──
+        self.visits = np.zeros(self.n)
+        self.any_time = 0.0
+        self.global_acc = 0.0
+        self.trace = []
+
+    # ───────── 特征 (两条通路各自独立) ─────��───
+    def phi_p(self, i):
+        """预测通路的特征: 候选 + 当前能力均值。"""
+        return np.concatenate([[1.0], self.z[i], [self._x_prev.mean()]])
+
+    def predict_next(self, i):
+        """x̂_{t+1} = W_p · φ_p(x_t, u_i) —— 纯预测, 不含价值。"""
+        return self.W_p @ self.phi_p(i)
+
+    def gate(self, i):
+        """覆盖度门控: 无覆盖区域的预测不参与价值判断 (Q8)。"""
+        return 1.0 / np.sqrt(1.0 + self.visits[i])
+
+    def phi_v(self, i):
+        """价值通路的特征: **预测输出以门控后的形式进入** (不是 δ^pred)。"""
+        cov = 1.0 / (1.0 + self.visits[i])
+        unc = 1.0 / np.sqrt(1.0 + self.visits[i])
+        pred = self.predict_next(i) * self.gate(i) * self.lam_pred
+        return np.concatenate([[1.0], self.z[i], pred, [cov, unc]])
+
+    def value(self, i):
+        return float(self.theta @ self.phi_v(i))
+
+    def score(self, i):
+        return self.value(i) + self.explore_w / np.sqrt(1.0 + self.visits[i])
+
+    def probs(self):
+        s = np.array([self.score(i) for i in range(self.n)])
+        s = np.clip((s - s.max()) / 0.5, -30.0, 0.0)
+        e = np.exp(s)
+        tot = e.sum()
+        return e / tot if tot > 0 and np.isfinite(tot) else np.full(self.n, 1.0 / self.n)
+
+    # ───────── 动作 ─────────
+    def act(self, k=None, greedy=False):
+        k = k or self.k
+        if greedy:
+            order = np.argsort([self.score(i) for i in range(self.n)])[::-1]
+            idx = list(map(int, order[:k]))
+        else:
+            idx = list(map(int, self.rng.choice(self.n, size=min(k, self.n),
+                                                replace=False, p=self.probs())))
+        for i in idx:
+            self.visits[i] += 1
+        return idx
+
+    # ───────── 两个信号, 分别进各自通路 ─────────
+    # ───────── 两条通路**各自独立**的更新方法 (严格分离) ─────────
+    def update_prediction(self, idx, x_next):
+        """只更新预测通路 (W_p), 用 δ^pred = x_{t+1} − x̂_{t+1}。
+
+        **绝不触碰 θ_v / alpha / h。** 这是「两个信号不混」的可执行形式。
+        返回本步 δ^pred 的均值。
+        """
+        x_next = np.asarray(x_next, dtype=float)
+        ds = []
+        for i in idx:
+            d = x_next - self.predict_next(i)        # δ^pred
+            self.W_p += self.eta_p * np.outer(d, self.phi_p(i))
+            ds.append(float(np.mean(np.abs(d))))
+        self.pred_err.append(float(np.mean(ds)))
+        self._x_prev = x_next.copy()
+        return self.pred_err[-1]
+
+    def update_value(self, idx, r=None):
+        """只更新价值通路 (θ_v / alpha / h), 用 δ^RL = r + γV(s') − V(s)。
+
+        **绝不触碰 W_p。** 返回本步 δ^RL 的均值。
+        """
+        if r is None:
+            r = self.any_time - self.global_acc
+        self.global_acc = self.any_time
+        for i in idx:
+            self.visits[i] += 1                      # 价值通路自己记账覆盖
+        drl = []
+        for i in idx:
+            phi = self.phi_v(i)
+            v = float(self.theta @ phi)
+            d = float(r + self.gamma * 0.0 - v)     # γ=1 时退化为 r − V (bandit)
+            drl.append(d)
+            self.theta += self.alpha * d * phi
+            self.h = self.h * np.maximum(0.0, 1.0 - self.alpha * phi ** 2) \
+                + self.alpha * phi * d
+            self.alpha = np.clip(self.alpha * np.exp(
+                np.clip(self.mu * d * phi * self.h, -2.0, 2.0)), 1e-6, 1.0)
+        self.trace.append({"idx": list(map(int, idx)),
+                           "delta_pred": round(self.pred_err[-1], 6)
+                           if self.pred_err else 0.0,
+                           "delta_rl": round(float(np.mean(drl)), 6),
+                           "alpha_std": round(float(self.alpha.std()), 6),
+                           "w_pred_norm": round(float(np.linalg.norm(self.W_p)), 5)})
+        return float(np.mean(drl))
+
+    def update(self, idx, r=None, x_next=None):
+        """便捷入口: 依次调两条通路。**两条通路仍各自独立** ——
+        交叉验证见 tests/test_dual_signal.py (只喂一路时另一路逐位不变)。
+        """
+        if x_next is not None:
+            self.update_prediction(idx, x_next)
+        return self.update_value(idx, r=r)
+
+    # ───────── 覆盖度检查 (Q8): 这个反事实可不可信 ─────────
+    def counterfactual(self, i, min_visits=3):
+        """对被门控掉的候选给出「预测不可信」标记, 而不是硬报一个数。
+
+        返回 (x̂_next, 可信?, 门控值)。**这是对规划幻觉的直接对策** ——
+        实测 `[2,2,2,2,2]` 的预测 0.9582 / 实测 0.4357, 就是因为当时没有这道门。
+        """
+        g = self.gate(i)
+        return self.predict_next(i), bool(self.visits[i] >= min_visits), float(g)
+
+    def stats(self):
+        al = self.alpha
+        return {
+            "pred_err_mean": round(float(np.mean(self.pred_err[-20:]))
+                                   if self.pred_err else 0.0, 6),
+            "w_pred_norm": round(float(np.linalg.norm(self.W_p)), 5),
+            "theta_norm": round(float(np.linalg.norm(self.theta)), 5),
+            "alpha_std": round(float(al.std()), 6),
+            "alpha_ratio": round(float(al.max() / max(1e-12, al.min())), 2),
+            "coverage": round(float((self.visits > 0).mean()), 4),
+            # ★ 两个信号各自的量级, 用来证明它们**没有混在一起**
+            "signal_gap": round(abs(float(np.mean(self.pred_err[-20:])
+                                         if self.pred_err else 0.0)), 6),
+        }

hibs_lnn/evidence_bank.py

@@ -0,0 +1,345 @@
+"""evidence_bank.py — **证据库**: 把 GVFBank 从「一组预测器的平均」改造成证据。
+
+## 为什么要独立一个模块
+
+旧的 `GVFBank.update()` 返回 `np.mean(errs)` —— 那是**简单平均**,
+而用户对阶段五的硬约束是「**绝对不要把多个 GVF 简单平均**」。
+更要紧的是:一个标量均值**丢掉了来源**。系统没法回答
+
+    是哪条证据说"坏"? 哪条说"好"? 哪条**缺席**?
+
+所以这个模块的输出**永远是引用清单**,不是分数。
+
+## 三条不可协商的设计
+
+1. **缺席必须显式**。旧实现把"没有证据"和"证据说没问题"混成同一个数(都落 0)
+   ⇒ **未知永远伪装成好**。这里没有经验的证据被报为 `missing`,不参与平均。
+2. **动力学证据只能降级**。预测误差低只说明"我预测得准",不说明"这件事有价值";
+   而**新颖度会拉高误差**,所以允许升级就等于允许新颖度伪造"好"。
+   ⇒ `role == "dynamics"` 的证据可以投 `bad`,**永远不能**投 `healthy`。
+3. **每条证据用自己的尺度**。`err_ema / err_ref`,其中 `err_ref` 是该 GVF **自己的**
+   历史误差中位数 —— 不引入跨 GVF 的全局常数(那又是另一种平均)。
+
+## 与三态的关系
+
+    GVFBank → EvidenceBank.support() → 引用清单 → RRSkillAgent.rr_epistemic(o)
+
+**不新增势函数**(用户: `InternalKnowledge 首先是 evidence bank`)。
+"""
+from __future__ import annotations
+
+from collections import deque
+
+import numpy as np
+
+# ──────────────────────────────────────────────────────────────────────────
+# 语义分工 (用户指定): GVF_1 prediction / GVF_2 reward / GVF_3 transition / GVF_4 regime
+#   `role` 决定这条证据能不能把状态**升级**成 good:
+#     outcome  → 可以 (它直接谈结果有没有价值)
+#     dynamics → **不可以** (它只谈"我预测得准不准")
+# ──────────────────────────────────────────────────────────────────────────
+DEFAULT_SPEC = (
+    ("prediction", "dynamics", 0.95, 0.90),
+    ("reward", "outcome", 0.90, 0.80),
+    ("transition", "dynamics", 0.85, 0.80),
+    ("regime", "dynamics", 0.70, 0.50),
+)
+
+
+class GVF:
+    """单个 General Value Function: 线性 TD(λ)。与旧 `knowledge.GVF` 同式。"""
+
+    def __init__(self, name, dim, gamma=0.9, lam=0.8, lr=0.05, seed=0):
+        self.name = name
+        self.gamma = float(gamma)
+        self.lam = float(lam)
+        self.lr = float(lr)
+        self.w = np.zeros(dim)
+        self.trace = np.zeros(dim)
+        self.rng = np.random.default_rng(seed)
+        self.steps = 0
+
+    def predict(self, phi):
+        return float(self.w @ phi)
+
+    def update(self, phi, cumulant, phi_next):
+        v, v_next = self.w @ phi, self.w @ phi_next
+        delta = float(cumulant) + self.gamma * v_next - v
+        self.trace = self.gamma * self.lam * self.trace + phi
+        self.w = self.w + self.lr * delta * self.trace
+        self.steps += 1
+        return abs(delta)
+
+
+class GVFEvidence:
+    """一条证据 —— **不是权重, 是"我凭什么这么说"**。
+
+    每个字段都是可判定的, 不留"看起来还行"这种状态。
+    """
+
+    __slots__ = ("name", "role", "value", "err_ema", "err_ref", "n",
+                 "last_step", "regime", "buf", "ema_w")
+
+    def __init__(self, name, role, ema_w=0.05, buf_len=200):
+        self.name = name
+        self.role = role                 # 'dynamics' | 'outcome'
+        self.value = 0.0
+        self.err_ema = 0.0
+        self.err_ref = 0.0               # 该 GVF **自己**的历史误差中位数
+        self.n = 0
+        self.last_step = -1
+        self.regime = None
+        self.buf = deque(maxlen=buf_len)
+        self.ema_w = float(ema_w)
+
+    def push(self, err, value, step, regime):
+        self.n += 1
+        self.last_step = int(step)
+        self.regime = regime
+        self.value = float(value)
+        self.err_ema = (err if self.n == 1
+                        else (1.0 - self.ema_w) * self.err_ema + self.ema_w * err)
+        self.buf.append(float(err))
+        # 参考尺度 = 自己的历史中位数(稳健, 不被单次尖峰带跑)
+        self.err_ref = float(np.median(self.buf)) if self.buf else 0.0
+
+    def usability(self, step, regime, n_min, stale_hl):
+        """★ 缺失证据要显式缺席, 而不是按 0 平均进去。
+
+        返回 (usable, why)。`why` 只在不可用时给出, 并进入引用清单。
+        """
+        if self.n < n_min:
+            return False, "low_coverage"
+        if step is not None and self.last_step >= 0:
+            if (step - self.last_step) > stale_hl:
+                return False, "stale"
+        if regime is not None and self.regime is not None and self.regime != regime:
+            return False, "wrong_regime"
+        return True, None
+
+    def z(self, eps=1e-9):
+        """该 GVF **自己尺度**上的相对误差。"""
+        return float(self.err_ema / max(self.err_ref, eps))
+
+    def to_dict(self):
+        return {"name": self.name, "role": self.role, "value": self.value,
+                "err_ema": self.err_ema, "err_ref": self.err_ref,
+                "z": self.z(), "n": self.n, "last_step": self.last_step,
+                "regime": self.regime}
+
+
+class EvidenceBank:
+    """一组语义分工的 GVF + 它们的证据记录。
+
+    ★ 没有 `aggregate()` 返回标量的接口 —— 那正是本模块要消灭的东西。
+    """
+
+    def __init__(self, dim, spec=None, seed=0, n_min=10, stale_hl=200,
+                 z_bad=2.0, z_good=1.0):
+        self.spec = tuple(spec) if spec else DEFAULT_SPEC
+        self.dim = int(dim)
+        self.n_min = int(n_min)
+        self.stale_hl = int(stale_hl)
+        self.z_bad = float(z_bad)
+        self.z_good = float(z_good)
+        self.gvfs = {}
+        self.ev = {}
+        # ★ 逐 step 历史 —— 互补性度量必须有"逐步序列"才能算 AUC,
+        #   而**不能在事后从聚合量重建**。这里如实记下来。
+        self.hist_z = {}
+        self.hist_c = {}
+        for i, (name, role, gamma, lam) in enumerate(self.spec):
+            self.gvfs[name] = GVF(name, self.dim, gamma, lam, seed=seed + i)
+            self.ev[name] = GVFEvidence(name, role)
+            self.hist_z[name] = []
+            self.hist_c[name] = []
+        self.regime = None
+
+    # ── 写入 ──────────────────────────────────────────────────────────
+    def observe(self, phi, cumulants, phi_next, step=None, regime=None):
+        """喂一组 cumulant(**按 spec 顺序**)。
+
+        返回每条 GVF 自己的误差 —— **不返回均值**。
+        """
+        if len(cumulants) != len(self.spec):
+            raise ValueError("cumulants 数 %d != spec 数 %d"
+                             % (len(cumulants), len(self.spec)))
+        if regime is not None:
+            self.regime = regime
+        out = {}
+        for (name, _role, _g, _l), c in zip(self.spec, cumulants):
+            g, e = self.gvfs[name], self.ev[name]
+            err = g.update(phi, float(c), phi_next)
+            e.push(err, g.predict(phi), -1 if step is None else step, regime)
+            out[name] = err
+            # ★ 逐 step 如实记录(互补性度量用) —— 记的是**当场**的 z,
+            #   不是最后那个聚合值。
+            self.hist_z[name].append(e.z())
+            self.hist_c[name].append(float(c))
+        return out
+
+    def z_history(self):
+        """★ 逐 step 的 z 序列与 cumulant 序列, 供互补性度量使用。
+
+        **不能从 `evidence()` 的聚合量重建** —— 那正是"丢来源"的老毛病。
+        """
+        return {"z": {k: np.asarray(v, dtype=float) for k, v in self.hist_z.items()},
+                "cumulant": {k: np.asarray(v, dtype=float) for k, v in self.hist_c.items()}}
+
+    # ── 查询 ──────────────────────────────────────────────────────────
+    def evidence(self, step=None, regime=None):
+        """每条证据的完整记录(**e_1, e_2, e_3, e_4 原样保留**)。"""
+        reg = self.regime if regime is None else regime
+        out = {}
+        for name, _r, _g, _l in self.spec:
+            e = self.ev[name]
+            ok, why = e.usability(step, reg, self.n_min, self.stale_hl)
+            d = e.to_dict()
+            d["usable"] = ok
+            d["why"] = why
+            out[name] = d
+        return out
+
+    def support(self, step=None, regime=None):
+        """★★ 聚合 = **投票 + 引用**, 不是平均。
+
+        返回的字典里**没有任何跨 GVF 的标量均值**。
+        """
+        reg = self.regime if regime is None else regime
+        bad, healthy, missing, sources = [], [], [], {}
+        usable_n = 0
+        for name, role, _g, _l in self.spec:
+            e = self.ev[name]
+            ok, why = e.usability(step, reg, self.n_min, self.stale_hl)
+            zd = e.z()
+            src = {"src": name, "role": role, "z": zd, "n": e.n,
+                   "err_ema": e.err_ema, "err_ref": e.err_ref}
+            sources[name] = src
+            if not ok:
+                missing.append({"src": name, "role": role, "why": why, "n": e.n})
+                continue
+            usable_n += 1
+            if zd >= self.z_bad:
+                bad.append({"src": name, "role": role, "z": zd})
+            elif zd <= self.z_good:
+                # ★★ 动力学证据**只能降级**: 它可以投 bad, 但永不能投 healthy。
+                #    理由: 预测误差低只说明"我预测得准", 不说明"这件事有价值";
+                #    而**新颖度会拉高误差** ⇒ 允许升级就等于允许新颖度伪造"好"。
+                if role == "outcome":
+                    healthy.append({"src": name, "role": role, "z": zd})
+                else:
+                    healthy.append({"src": name, "role": role, "z": zd,
+                                    "capped": "dynamics 不升级"})
+
+        # 判定(不对称)
+        if bad:
+            verdict = "bad"
+        elif any(h.get("role") == "outcome" and "capped" not in h for h in healthy):
+            verdict = "good"
+        else:
+            verdict = "unknown"
+
+        return {
+            "verdict": verdict,
+            "bad": bad,
+            "healthy": healthy,          # 含被 cap 的动力学票(可追溯, 但不升级)
+            "missing": missing,
+            "usable_n": usable_n,
+            "total_n": len(self.spec),
+            "sources": sources,
+        }
+
+    def stats(self):
+        return {"n_gvf": len(self.spec), "regime": self.regime,
+                "n_min": self.n_min, "stale_hl": self.stale_hl,
+                "z_bad": self.z_bad, "z_good": self.z_good,
+                "evidence": {n: {"n": self.ev[n].n, "z": self.ev[n].z()}
+                             for n, _r, _g, _l in self.spec}}
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 互补性度量 —— 回答"多个 GVF 能不能产生互补证据"
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _auc(scores, labels):
+    """rank-based AUC(不依赖 sklearn)。labels: 1 = 正类(变化后)。
+
+    并列用**平均秩**(Mann-Whitney U 的标准处理)。
+    """
+    scores = np.asarray(scores, dtype=float)
+    labels = np.asarray(labels, dtype=int)
+    pos, neg = scores[labels == 1], scores[labels == 0]
+    if len(pos) == 0 or len(neg) == 0:
+        return float("nan")
+    order = np.argsort(scores, kind="mergesort")
+    ranks = np.empty(len(scores), dtype=float)
+    ranks[order] = np.arange(1, len(scores) + 1, dtype=float)
+    s = scores[order]
+    i = 0
+    while i < len(s):
+        j = i
+        while j + 1 < len(s) and s[j + 1] == s[i]:
+            j += 1
+        if j > i:
+            ranks[order[i:j + 1]] = (i + 1 + j + 1) / 2.0
+        i = j + 1
+    r_pos = ranks[labels == 1].sum()
+    return float((r_pos - len(pos) * (len(pos) + 1) / 2.0) / (len(pos) * len(neg)))
+
+
+def complementarity(err_series, shifted, z_bad=2.0, z_good=1.0):
+    """多条 GVF 的证据是否**互补**。
+
+    `err_series`: {name: 逐步误差数组}
+    `shifted`:    逐步标签, 1 = 该步处于"变化之后"
+
+    返回 AUC_i / AUC_union / complementarity / disagreement / corr_err。
+    """
+    names = list(err_series)
+    zs = {}
+    for n in names:
+        a = np.asarray(err_series[n], dtype=float)
+        # ★ 参考尺度只从"变化前"估计 —— 用全段会被变化本身抬高, 自己抹掉自己
+        pre = a[np.asarray(shifted, dtype=int) == 0]
+        ref = float(np.median(pre)) if pre.size and np.median(pre) > 0 else 1.0
+        zs[n] = a / max(ref, 1e-9)
+
+    auc_i = {n: _auc(zs[n], shifted) for n in names}
+    # ★ 两种并集规则, **必须分开报** —— 它们回答的是不同问题:
+    #   `any`       : 任一条超阈 ⇒ **检测**问题(加检测器不会降低 recall)
+    #   `consensus` : 至少两条同时超阈 ⇒ **一致性**问题(合取, 天生比单条保守)
+    #   ⚠ 只报 consensus 会得到"并集比单条差"的结论, 那是**聚合规则的产物**,
+    #     不是"证据不互补"的证据。两个都算, 都报。
+    flags = np.stack([(zs[n] >= z_bad).astype(int) for n in names])
+    jit = 1e-6 * np.arange(flags.shape[1])          # 位置抖动, 让并列信号可排秩
+    any_flag = (flags.sum(axis=0) >= 1).astype(float) + jit
+    cons_flag = (flags.sum(axis=0) >= 2).astype(float) + jit
+    auc_any = _auc(any_flag, shifted)
+    auc_cons = _auc(cons_flag, shifted)
+
+    valid = [v for v in auc_i.values() if v == v]
+    best_i = max(valid) if valid else float("nan")
+    if valid and auc_any == auc_any:
+        comp = auc_any - best_i
+    else:
+        comp = float("nan")
+
+    # 分歧率: **至少一条投 bad 且至少一条投 healthy** 的步数占比
+    n_bad = np.stack([zs[n] >= z_bad for n in names]).sum(axis=0)
+    n_ok = np.stack([zs[n] <= z_good for n in names]).sum(axis=0)
+    disagreement = float(((n_bad > 0) & (n_ok > 0)).mean()) if names else float("nan")
+
+    corr = {}
+    arr = np.stack([zs[n] for n in names])
+    if arr.shape[0] >= 2:
+        c = np.corrcoef(arr)
+        for i, a_ in enumerate(names):
+            for j, b_ in enumerate(names):
+                if i < j:
+                    corr["%s~%s" % (a_, b_)] = float(c[i, j])
+
+    return {"auc_i": auc_i, "auc_any": auc_any, "auc_consensus": auc_cons,
+            "best_single": best_i, "complementarity": comp,
+            "disagreement": disagreement, "corr_err": corr,
+            "z_bad": z_bad, "z_good": z_good}

hibs_lnn/gridworld.py

@@ -0,0 +1,509 @@
+"""gridworld.py — 论文里的两房间 / 四房间 gridworld(arXiv 2202.03466 Fig.1 / Fig.6)。
+
+## 为什么要有这个文件
+
+本项目的 lm4/lm5 基准**没有可用作时间抽象的结构**(实测不对称性 `A ≡ 0`,
+唯一的动力学是对称纯干扰)。在那种环境上,任何类别的 option 都不可能有收益 ——
+所以「Options 有害」这个结论**测的是基准的性质**。
+
+论文用的 gridworld 是**有明确正反例**的:同一个环境里
+  · bottleneck / shortest-path option  的 planning **比 primitive 还慢**(Fig.1)
+  · reward-respecting option            的 planning **明显更快**(Fig.1)
+这两个已知结论就是本项目的 ground truth —— 用来验证「我的 option + planning 管线写对了没有」。
+
+## 环境规格(逐条对齐论文)
+
+| 项 | 设定 |
+|:--|:--|
+| 动作 | 4 个:上 / 右 / 下 / 左 |
+| 撞墙 | 位置不变 |
+| 目标 | 到达 goal 得 **+1**,episode 结束 |
+| 灰色区 | **进入**灰色区的转移每步 **−1** |
+| 其他 | 0 |
+| γ | **0.99** |
+| 两房间最优 | `v*(s0) = 0.99^17 ≈ 0.843`(绕开负奖励区) |
+| 四房间动力学 | 期望方向 w.p. **2/3**,其余三个方向各 **1/9** |
+
+**注意论文原文用的是 "transitions ending in the gray region"** ——
+即**落点**在灰色区才扣分,不是路径穿过的格子。本实现按**落点**判。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+# 动作编号(与论文的四方向一致)
+UP, RIGHT, DOWN, LEFT = 0, 1, 2, 3
+N_ACT = 4
+ACT_NAME = {UP: "up", RIGHT: "right", DOWN: "down", LEFT: "left"}
+
+# ── 两房间 gridworld(Fig.1 插图) ─────────────────────────────────────────
+#   '#' 墙   '.' 地板   'S' 起点   'G' 目标   '-' 灰色区(落点扣分)   '+' 走廊(bottleneck)
+#
+#   布局要点(必须同时满足, 否则复现不了论文):
+#     ① 存在一个**单格走廊**连接两个房间 -> 它是天然 bottleneck
+#     ② 从 S 到走廊的**最短路径**穿过灰色区
+#     ③ 存在一条**绕开灰色区**的更长路径
+# ★ 第 4、5 行结尾的两个 '#' 不是笔误, 但它**修不掉原本的问题** —— 见下方说明。
+#
+# 实测(新版 check_two_room): 旧几何的 col 1 是通的 -> 有一条自由竖井绕过整个
+# 灰色区 -> 最短路**根本不碰灰色**(neg_on_shortest=0), 而且"绕行"与最短路等长。
+# 也就是说: 论文 Fig.1 的三条性质**一条都没满足**, 而因为自检函数本身有 bug
+# (hall 落在灰色格里 -> "绕开灰色区到达 hall" 构造上不可能), 它一直报的是 ✗ 却没人看。
+#
+# 现在按论文重设: 灰色区**正对**单格通道, 使得
+#     穿过灰色 = 3 步(最短)
+#     绕开灰色 = 7 步(更长)
+TWO_ROOM = [
+    "#########",
+    "#...S...#",
+    "#..---..#",
+    "#.......#",
+    "####+####",
+    "#.......#",
+    "#......G#",
+    "#########",
+]
+
+# ── 四房间 gridworld(Fig.6): 4 个房间 + 3 个单格走廊 ──────────────────
+#
+# ★ 这里曾经是**静默坏掉**的: 旧布局行长不齐(12/13/14), 且有一行含**空格**。
+#   行不齐 -> GridWorld 里 `.ljust(..., '#')` 静默补成墙, 几何被改;
+#   空格   -> 只有 '#' 被跳过, 空格于是变成一格**幽灵地板**(可走但看不出来)。
+#   两者都不会报错, 所以四房间那一支一直在跑一个**非预期的环境**, 复现自然失败。
+#   现在加 validate_layout() 在构造时**硬报错**, 这类 bug 不可能再静默。
+#
+# 布局设计(必须同时满足, 否则复现不了论文 Fig.6):
+#     ① 2x2 四个房间, 3 个单格走廊连成环 -> 走廊是天然 bottleneck
+#     ② 从 S 到走廊的最短路**穿过灰色区**(负奖励)
+#     ③ 存在一条**绕开灰色区**的更长路径
+#
+# 实测几何(见 check_four_room):
+#     最短路 S->G  = 18 步, 穿过灰色区 2 格
+#     绕行路线     = 20 步, 完全避开灰色区
+FOUR_ROOM = [
+    "#############",
+    "#S..####....#",
+    "#..--.+.....#",
+    "#.....#.....#",
+    "#.....#.....#",
+    "###+#########",
+    "#.....#.....#",
+    "#.....#.....#",
+    "#.....+.....#",
+    "#.....#....G#",
+    "#############",
+]
+
+
+_ALLOWED = set("#.-SG+")
+
+
+def validate_layout(layout, name="layout"):
+    """★ 硬校验布局。**报错而非默默容错** —— 见 FOUR_ROOM 上方的注释。
+
+    这条检查是补上一个真实事故: 旧四房间布局行长不齐 + 混入空格,
+    被 `.ljust(..., '#')` 和"只跳过 '#'"两个静默行为一起吃掉了,
+    结果整个四房间分支跑的是一个没人设计过的环境。
+
+    返回 (H, W)。不合法直接 raise ValueError。
+    """
+    if not layout:
+        raise ValueError("%s: 布局为空" % name)
+    widths = {len(r) for r in layout}
+    if len(widths) != 1:
+        detail = ", ".join("%d:\"%s\"" % (i, r) for i, r in enumerate(layout))
+        raise ValueError(
+            "%s: 行长不一致 (宽度集合 %s) —— 补齐会变成墙, 必须手工对齐。各行: %s"
+            % (name, sorted(widths), detail))
+    W = widths.pop()
+    for i, r in enumerate(layout):
+        bad = sorted(set(r) - _ALLOWED)
+        if bad:
+            raise ValueError(
+                "%s: 第 %d 行含非法字符 %r。只允许 %s —— "
+                "注意**空格不是地板**('#' 才是唯一的墙, 其它字符都会被当成可走格)。"
+                % (name, i, bad, sorted(_ALLOWED)))
+        if r[0] != "#" or r[-1] != "#":
+            raise ValueError("%s: 第 %d 行两端必须是墙 '#'" % (name, i))
+    for j in range(W):
+        if layout[0][j] != "#" or layout[-1][j] != "#":
+            raise ValueError("%s: 第 %d 列两端必须是墙 '#'" % (name, j))
+    flat = "".join(layout)
+    if flat.count("S") != 1:
+        raise ValueError("%s: 必须恰好有一个 'S' (实际 %d)" % (name, flat.count("S")))
+    if flat.count("G") < 1:
+        raise ValueError("%s: 至少需要一个 'G'" % name)
+    return len(layout), W
+
+
+class GridWorld:
+    """确定性 / 随机性可切的 gridworld(论文规格)。"""
+
+    def __init__(self, layout, gamma=0.99, stochastic=False, slip=2.0 / 3.0):
+        self.layout = list(layout)
+        self.gamma = float(gamma)
+        self.stochastic = bool(stochastic)
+        self.slip = float(slip)
+
+        # ★ 先硬校验, 再构造。旧代码这里是 `.ljust(W, '#')` 静默补齐 ——
+        #   它会**悄悄把短行补成墙**, 于是布局错了几何也照跑不误。
+        #   validate_layout 会把行长不齐/非法字符/边界非墙变成**构造期异常**。
+        self.H, self.W = validate_layout(layout, name=getattr(self, "name", "layout"))
+        self.grid = list(layout)          # 已保证等宽, 不再 ljust
+
+        self.cells = []            # (row, col)
+        self.index = {}
+        self.is_neg = []           # 落点是否灰色区(扣分)
+        self.is_goal = []
+        self.start = None
+        for r in range(self.H):
+            for c in range(self.W):
+                ch = self.grid[r][c]
+                if ch == "#":
+                    continue
+                i = len(self.cells)
+                self.cells.append((r, c))
+                self.index[(r, c)] = i
+                self.is_neg.append(ch == "-")
+                self.is_goal.append(ch == "G")
+                if ch == "S":
+                    self.start = i
+        self.n_states = len(self.cells)
+        self.is_neg = np.array(self.is_neg, dtype=bool)
+        self.is_goal = np.array(self.is_goal, dtype=bool)
+        assert self.start is not None, "布局里必须有 'S'"
+        assert self.is_goal.any(), "布局里必须有 'G'"
+
+        self._build_transitions()
+
+    # ── 动力学 ──────────────────────────────────────────────────────────
+    def _move(self, r, c, a):
+        if a == UP:
+            r -= 1
+        elif a == DOWN:
+            r += 1
+        elif a == LEFT:
+            c -= 1
+        else:
+            c += 1
+        if (r, c) in self.index:
+            return self.index[(r, c)]
+        return None                      # 撞墙
+
+    def _build_transitions(self):
+        """T[s][a] = [(prob, next_state), ...];  R[s][a] = 期望即时奖励。"""
+        self.T: list = [[[] for _ in range(N_ACT)] for _ in range(self.n_states)]
+        self.R = np.zeros((self.n_states, N_ACT))
+        for s, (r, c) in enumerate(self.cells):
+            # ★ goal 是**吸收态**(论文: "A reward of +1 is received on reaching the
+            #   goal state, **which ends the episode**")。
+            #   不做这一步的话, agent 会反复落回 goal 反复拿 +1 -> 价值爆炸
+            #   (实测: 子任务里 hall 处的"继续价值"算成 98.01, 而真值 <= 1)。
+            if self.is_goal[s]:
+                for a in range(N_ACT):
+                    self.T[s][a] = [(1.0, int(s))]
+                    self.R[s][a] = 0.0
+                continue
+            for a in range(N_ACT):
+                if self.stochastic:
+                    # 期望方向 2/3, 其余三个方向各 1/9(论文规格)
+                    others = [x for x in range(N_ACT) if x != a]
+                    cand = [(a, self.slip)] + [(x, (1.0 - self.slip) / 3.0) for x in others]
+                else:
+                    cand = [(a, 1.0)]
+                # 合并相同落点
+                acc = {}
+                for act, p in cand:
+                    ns = self._move(r, c, act)
+                    if ns is None:
+                        ns = s          # 撞墙 -> 留在原地
+                    acc[ns] = acc.get(ns, 0.0) + p
+                outs = sorted(acc.items())
+                self.T[s][a] = [(float(p), int(ns)) for ns, p in outs]
+                # 落点在灰色区 -> -1;落点是 goal -> +1
+                rew = 0.0
+                for p, ns in self.T[s][a]:
+                    if self.is_goal[ns]:
+                        rew += p * 1.0
+                    elif self.is_neg[ns]:
+                        rew += p * -1.0
+                self.R[s][a] = rew
+
+    def reset(self):
+        return self.start
+
+    def step(self, s, a):
+        outs = self.T[s][a]
+        if len(outs) == 1:
+            ns = outs[0][1]
+        else:
+            p = np.array([x[0] for x in outs])
+            p = p / p.sum()
+            ns = outs[int(np.random.choice(len(outs), p=p))][1]
+        done = bool(self.is_goal[ns])
+        return ns, float(self.R[s][a]), done
+
+
+# ── 布局性质自检(必须过, 否则复现不了论文) ─────────────────────────────
+
+def find_bottlenecks(env):
+    """介数中心性高(且度小)的格子 = 论文说的 bottleneck。
+
+    实现方式:对确定性图做全对最短路径(无权 BFS),数每格出现在多少条最短路里。
+    """
+    import collections
+    n = env.n_states
+    # 确定性后继(取 T 里概率最大的那个, 用于结构性分析)
+    succ = [[max(env.T[s][a], key=lambda x: x[0])[1] for a in range(N_ACT)] for s in range(n)]
+    between = np.zeros(n)
+    for src in range(n):
+        dist = [-1] * n
+        dist[src] = 0
+        q = collections.deque([src])
+        order = []
+        while q:
+            u = q.popleft()
+            order.append(u)
+            for a in range(N_ACT):
+                v = succ[u][a]
+                if v != u and dist[v] < 0:
+                    dist[v] = dist[u] + 1
+                    q.append(v)
+        for tgt in range(n):
+            if tgt == src or dist[tgt] < 0:
+                continue
+            # 回溯一条最短路(标记经过的格)
+            u = tgt
+            guard = 0
+            while u != src and guard < 4 * n:
+                between[u] += 1
+                nxt = None
+                for a in range(N_ACT):
+                    v = succ[u][a]
+                    if v != u and dist[v] == dist[u] - 1:
+                        nxt = v
+                        break
+                if nxt is None:
+                    break
+                u = nxt
+                guard += 1
+    return between
+
+
+def check_two_room(env, verbose=True):
+    """验证两房间布局确实具备论文要求的三条性质。"""
+    import collections
+    n = env.n_states
+    succ = [[max(env.T[s][a], key=lambda x: x[0])[1] for a in range(N_ACT)] for s in range(n)]
+
+    def bfs(src, avoid_neg=False):
+        dist = {src: 0}
+        parent = {src: None}
+        q = collections.deque([src])
+        while q:
+            u = q.popleft()
+            if env.is_goal[u]:
+                continue
+            for a in range(N_ACT):
+                v = succ[u][a]
+                if v == u or v in dist:
+                    continue
+                if avoid_neg and env.is_neg[v]:
+                    continue
+                dist[v] = dist[u] + 1
+                parent[v] = u
+                q.append(v)
+        return dist, parent
+
+    bt = find_bottlenecks(env)
+    # bottleneck = 非起非终、**且不是灰色格**、介数最高
+    # ★ 必须排除灰色格: 否则 hall 常常正好落在灰色区里, 而下面又要求
+    #   "存在绕开灰色区到达 hall 的路径" —— 那是**构造上不可能**的,
+    #   于是这条自检永远报 ✗, 成了没人看的红灯(实测: 原来的 hall=(3,6) 就是 '-' 格)。
+    cand = [(bt[s], s) for s in range(n)
+            if s != env.start and not env.is_goal[s] and not env.is_neg[s]]
+    cand.sort(reverse=True)
+    hall = cand[0][1]
+
+    d_free, _ = bfs(env.start)
+    d_avoid, _ = bfs(env.start, avoid_neg=True)
+
+    reach_hall = hall in d_free
+    # 最短路到走廊经过的灰色区格数
+    _, par = bfs(env.start)
+    path, u = [], hall
+    while u is not None:
+        path.append(u)
+        u = par.get(u)
+    path.reverse()
+    neg_on_shortest = sum(int(env.is_neg[s]) for s in path)
+    has_detour = hall in d_avoid and d_avoid.get(hall, 10 ** 9) > d_free.get(hall, 0)
+
+    if verbose:
+        r0, c0 = env.cells[env.start]
+        rh, ch = env.cells[hall]
+        print("  [两房间自检]")
+        print("    起点 (%d,%d) -> 走廊 (%d,%d)  [介数 %.0f]" % (r0, c0, rh, ch, bt[hall]))
+        print("    到达走廊: %s   最短路长度 %s" % (reach_hall, d_free.get(hall)))
+        print("    最短路上的灰色格数: %d   (论文要求 > 0, 否则没有'绕路'可言)"
+              % neg_on_shortest)
+        print("    存在绕开灰色区的路径: %s  (长度 %s vs 最短 %s)"
+              % (has_detour, d_avoid.get(hall), d_free.get(hall)))
+    ok = reach_hall and neg_on_shortest > 0 and has_detour
+    if verbose:
+        print("    三条性质全满足: %s" % ("✓" if ok else "✗ 布局需要调整"))
+    return ok, hall, dict(d_free=d_free, d_avoid=d_avoid,
+                          neg_on_shortest=neg_on_shortest, between=bt)
+
+
+def check_four_room(env, verbose=True):
+    """验证四房间布局确实具备论文 Fig.6 要求的性质。**四房间从来没有过这个检查。**
+
+    与 check_two_room 的三条性质对应, 但四房间要额外验:
+        ① 把走廊堵上后, 恰好分裂成 **4 个连通分量**(真的是四房间, 不是一团)
+        ② 走廊格是 bottleneck(介数最高)
+        ③ 从 S 到走廊的**最短路穿过灰色区**
+        ④ 存在**绕开灰色区**的更长路径
+
+    返回 (ok, halls, info)。
+    """
+    import collections
+    n = env.n_states
+    succ = [[max(env.T[s][a], key=lambda x: x[0])[1] for a in range(N_ACT)] for s in range(n)]
+
+    def bfs(src, avoid_neg=False, block=None):
+        dist, q = {src: 0}, collections.deque([src])
+        parent = {src: None}
+        while q:
+            u = q.popleft()
+            if env.is_goal[u]:
+                continue
+            for a in range(N_ACT):
+                v = succ[u][a]
+                if v == u or v in dist or v == block:
+                    continue
+                if avoid_neg and env.is_neg[v]:
+                    continue
+                dist[v] = dist[u] + 1
+                parent[v] = u
+                q.append(v)
+        return dist, parent
+
+    bt = find_bottlenecks(env)
+    # ★ 走廊格 = 字符 '+' 的格子(显式标记, 不靠介数猜)
+    halls = [s for s, (r, c) in enumerate(env.cells) if env.grid[r][c] == "+"]
+
+    # ① 堵上全部走廊 -> 数连通分量
+    blocked = set(halls)
+    seen, comps = set(), []
+    for s in range(n):
+        if s in seen or s in blocked:
+            continue
+        stack, comp = [s], []
+        seen.add(s)
+        while stack:
+            u = stack.pop()
+            comp.append(u)
+            for a in range(N_ACT):
+                v = succ[u][a]
+                if v == u or v in seen or v in blocked:
+                    continue
+                seen.add(v)
+                stack.append(v)
+        comps.append(comp)
+
+    # ③④ 对每个走廊格测最短路 vs 绕行
+    rows = []
+    for h in halls:
+        d_free, par = bfs(env.start)
+        d_av, _ = bfs(env.start, avoid_neg=True)
+        path, u = [], h
+        while u is not None:
+            path.append(u)
+            u = par.get(u)
+        path.reverse()
+        neg_short = sum(int(env.is_neg[s]) for s in path)
+        rows.append(dict(hall=h, d_free=d_free.get(h), d_avoid=d_av.get(h),
+                         neg_on_shortest=neg_short,
+                         detour_longer=(h in d_av and h in d_free and d_av[h] > d_free[h])))
+
+    p_ok = abs(bt[halls[0]] - max(bt)) < 1e-6 if halls else False
+    ok = (len(comps) == 4 and halls
+          and all(r["d_free"] is not None for r in rows)
+          and any(r["neg_on_shortest"] > 0 for r in rows)
+          and any(r["detour_longer"] for r in rows))
+
+    if verbose:
+        print("  [四房间自检]")
+        print("    状态数 %d  走廊格 %d 个: %s"
+              % (n, len(halls), [env.cells[h] for h in halls]))
+        print("    堵上走廊后的连通分量数: %d   (论文要求 4)" % len(comps))
+        if halls:
+            print("    走廊是介数最高点: %s (介数 %.0f / 全局最高 %.0f)"
+                  % (p_ok, bt[halls[0]], max(bt)))
+        for r in rows:
+            rh, ch = env.cells[r["hall"]]
+            print("    走廊 (%d,%d): 最短路 %s 步(其中灰色 %d 格)  绕行 %s 步  绕行更长: %s"
+                  % (rh, ch, r["d_free"], r["neg_on_shortest"], r["d_avoid"], r["detour_longer"]))
+        print("    四条性质全满足: %s" % ("✓" if ok else "✗ 布局需要调整"))
+    return ok, halls, dict(n_comps=len(comps), rows=rows, between=bt)
+
+
+def value_iteration(env, model=None, n_sweeps=1, V0=None, options=None, order=None):
+    """带 option 的价值迭代(论文 §5 的 planning)。
+
+    model : [(p, ns, r)] 形式的 dict; 默认用真模型(论文 Fig.1 假设模型准确)
+            格式:  model[s][u] = [(p, ns, r), ...];  u 索引 0..N_ACT-1 是 primitive,
+                   N_ACT.. 是 option(一跳到底, 返回终止状态与累计奖励)
+    n_sweeps : 扫多少遍
+    返回 (V, n_lookahead) —— n_lookahead = 消耗的 look-ahead 操作数(论文的横轴)
+    """
+    n = env.n_states
+    V = np.zeros(n) if V0 is None else V0.copy()
+    n_look = 0
+    if model is None:
+        model = {s: {a: [(p, ns, env.R[s][a]) for p, ns in env.T[s][a]] for a in range(N_ACT)}
+                 for s in range(n)}
+    for _ in range(n_sweeps):
+        idx = range(n) if order is None else order
+        for s in idx:
+            if env.is_goal[s]:
+                V[s] = 0.0
+                continue
+            best = -np.inf
+            for u, outs in model[s].items():
+                val = 0.0
+                for p, ns, r in outs:
+                    val += p * (r + env.gamma * V[ns])
+                    n_look += 1            # 每次 look-ahead 计数
+                best = max(best, val)
+            V[s] = best
+    return V, n_look
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("两房间 gridworld(确定性, 论文 Fig.1)")
+    print("=" * 70)
+    env = GridWorld(TWO_ROOM, gamma=0.99, stochastic=False)
+    print("  状态数 %d, 动作数 %d" % (env.n_states, N_ACT))
+    ok, hall, info = check_two_room(env)
+
+    V, n = value_iteration(env, n_sweeps=200)
+    print("\n  value iteration 200 遍 (primitive only): V(S) = %.4f" % V[env.start])
+    print("  论文报告的最优值 v*(s0) = 0.99^17 = %.4f" % (0.99 ** 17))
+    print("  look-ahead 操作数 = %d" % n)
+
+    print("\n" + "=" * 70)
+    print("四房间 gridworld(随机, slip=2/3, 论文 Fig.6)")
+    print("=" * 70)
+    env4 = GridWorld(FOUR_ROOM, gamma=0.99, stochastic=True)
+    print("  状态数 %d, 动作数 %d" % (env4.n_states, N_ACT))
+    ok4, halls4, info4 = check_four_room(env4)
+    # ★ 自检不过就让进程**非零退出** —— 否则坏几何又会被静默当成"实验做完了"
+    if not (ok and ok4):
+        print("\n✗ 布局自检未通过, 拒绝继续(退出码 1)")
+        raise SystemExit(1)
+    V4, n4 = value_iteration(env4, n_sweeps=200)
+    print("\n  value iteration 200 遍 (primitive only): V(S) = %.4f" % V4[env4.start])
+    print("  look-ahead 操作数 = %d" % n4)

hibs_lnn/knowledge.py

@@ -0,0 +1,386 @@
+"""knowledge.py — InternalKnowledge: Agent 的**内部知识层**。
+
+## 核心立场 (用户给的)
+
+    Knowledge ≠ Parameter
+
+参数只是**承载**知识的一种方式。OaK 式系统希望内部知识是**可组合的计算对象**,
+而不是 `y = f_θ(x)` 里一堆"你甚至不知道 θ 代表什么知识"的权重。
+
+所以这个类**不暴露 θ / W / α**,而是暴露**可计算的知识查询**:
+
+    "未来会发生什么?"  -> predict()
+    "我做什么会导致什么?" -> dynamics()
+    "什么结果更好?"      -> value()
+    "哪些过程是一个整体技能?" -> skills()
+    "我对 X 有多确定?"   -> confidence()
+    "我有多少经验?"      -> coverage_of()
+    "我该多快改变?"      -> plasticity()
+
+## 四层知识 (用户给的编号)
+
+    Level 1  预测知识    K_P   GVF / predictors           "未来会发生什么"
+    Level 2  因果/转移   K_T   T(s,a)                    "我做什么会导致什么"
+    Level 3  价值/策略   K_V   V / Q / π                 "什么结果更好"
+    Level 4  抽象知识    K_A   Options                    "哪些过程是一个整体技能"
+
+外加两类**元知识**:
+
+    uncertainty/   confidence           "我对自己的预测有多确定"
+    coverage/      state_action 覆盖     "我对这个状态/动作到底有没有经验"
+    plasticity/    α / β               "我应该多快改变这个知识" (接 IDBD)
+
+## 为什么 α 也算内部知识
+
+    w_i   = knowledge                  "我知道什么"
+    α_i   = knowledge about plasticity "我应该多快改变这个知识"
+    β_i   = meta-knowledge              "我的学习速度应该如何变化"
+
+这与 IDBD 主线直接接上。
+
+## 关键能力: 知识是**留下来的**
+
+`to_dict()` / `load_dict()` 让 K 可以持久化比对 —— 这是"持续构建内部知识"的
+可判定形式: 不是"模型又训了一轮",而是**能指出知识具体变了什么**。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+# ──────────────────────────────────────────────────────────────────────────
+# Level 1: 预测知识 (GVF / Horde 式)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class GVF:
+    """General Value Function: 预测某个 cumulant 的折扣累积量。
+
+        V(s) = E[ Σ γ^k λ^k c_{t+k+1} | s_t = s ]
+
+    `c` = cumulant (要预测的信号), `γ` = 折扣, `λ` = 迹衰减。
+    Horde (Sutton 2011) 的做法: 一堆 GVF 并行学, 它们的预测**进入状态**,
+    构成 agent 对世界的"理解"—— 这正是 OaK 说的 internal knowledge。
+    """
+
+    def __init__(self, name, dim, gamma=0.9, lam=0.8, lr=0.05, seed=0):
+        self.name = name
+        self.gamma = gamma
+        self.lam = lam
+        self.lr = lr
+        self.w = np.zeros(dim)
+        self.trace = np.zeros(dim)
+        self.rng = np.random.default_rng(seed)
+        self.steps = 0
+
+    def predict(self, phi):
+        return float(self.w @ phi)
+
+    def update(self, phi, cumulant, phi_next):
+        """TD(λ) 更新。"""
+        v, v_next = self.w @ phi, self.w @ phi_next
+        delta = cumulant + self.gamma * v_next - v
+        self.trace = self.gamma * self.lam * self.trace + phi
+        self.w += self.lr * delta * self.trace
+        self.steps += 1
+        return abs(delta)
+
+    def stats(self):
+        return {"name": self.name, "w_norm": float(np.linalg.norm(self.w)),
+                "steps": self.steps, "gamma": self.gamma, "lam": self.lam}
+
+
+class GVFBank:
+    """一组 GVF。它们的预测拼起来就是 agent 的"世界理解"向量。"""
+
+    def __init__(self, dim, spec=None, seed=0):
+        self.spec = spec or [
+            ("next_acc", 0.95, 0.9), ("acc_trend", 0.9, 0.7),
+            ("forget_risk", 0.85, 0.8), ("regime_shift", 0.7, 0.5),
+        ]
+        self.gvfs = [GVF(n, dim, g, l, seed=seed + i)
+                     for i, (n, g, l) in enumerate(self.spec)]
+
+    def outputs(self, phi):
+        """预测向量 —— 这就是"预测到的世界状态", 可作为下游特征。"""
+        return np.array([g.predict(phi) for g in self.gvfs])
+
+    def update(self, phi, cumulants, phi_next):
+        errs = []
+        for g, c in zip(self.gvfs, cumulants):
+            errs.append(g.update(phi, float(c), phi_next))
+        return float(np.mean(errs)) if errs else 0.0
+
+    def stats(self):
+        return {"n_gvf": len(self.gvfs),
+                "gvfs": [g.stats() for g in self.gvfs],
+                "out_norm": float(np.linalg.norm(self.outputs(np.ones_like(self.gvfs[0].w)))),
+                "mean_steps": float(np.mean([g.steps for g in self.gvfs])) if self.gvfs else 0.0}
+
+
+# ────────���─────────────────────────────────────────────────────────────────
+# 元知识: 覆盖度 / 可塑性
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class Coverage:
+    """state-action 覆盖度 —— "我对这个 (s,a) 到底有没有经验"。"""
+
+    def __init__(self, n_dom):
+        self.n_dom = n_dom
+        self.n = np.zeros(n_dom)        # 每动作被访问次数
+        self.n_total = 0
+
+    def observe(self, a):
+        if 0 <= a < self.n_dom:
+            self.n[a] += 1
+        self.n_total += 1
+
+    def of(self, a):
+        return float(self.n[a]) if 0 <= a < self.n_dom else 0.0
+
+    def gate(self, a):
+        """g = 1/√(1+n): 零覆盖 -> 1, 经验多 -> 0。"""
+        return float(1.0 / np.sqrt(1.0 + self.of(a)))
+
+    def stats(self):
+        nz = self.n[self.n > 0]
+        return {"total": int(self.n_total), "per_action": self.n.astype(int).tolist(),
+                "min": float(nz.min()) if len(nz) else 0.0,
+                "max": float(nz.max()) if len(nz) else 0.0,
+                "zero_actions": int((self.n == 0).sum())}
+
+
+class Plasticity:
+    """元知识: α (该多快改变某个参数) 与 β (学习速度本身的变化)。
+
+    这是 IDBD 主线在"内部知识"里的位置 —— 它**不是**知识本身,
+    而是"关于知识该如何改变的"元知识。
+    """
+
+    def __init__(self, dim, alpha0=0.05, mu=0.01):
+        self.alpha0 = alpha0
+        self.mu = mu
+        self.beta = np.zeros(dim)
+        self.h = np.zeros(dim)
+        self.updates = 0
+
+    @property
+    def alpha(self):
+        return np.exp(np.clip(self.beta, -20, 20)) * self.alpha0
+
+    def update(self, phi, delta):
+        g = delta * phi * self.h
+        self.h = np.maximum(0.0, self.h * (1.0 - np.clip(self.alpha * phi ** 2, 0, 1)) + self.alpha * phi * delta)
+        self.beta = np.clip(self.beta + self.mu * g, -20, 20)
+        self.updates += 1
+
+    def stats(self):
+        a = self.alpha
+        return {"mean": float(a.mean()), "std": float(a.std()),
+                "min": float(a.min()), "max": float(a.max()),
+                "ratio_max_min": float(a.max() / max(a.min(), 1e-12)),
+                "updates": self.updates}
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# InternalKnowledge: 统一的知识容器
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class InternalKnowledge:
+    """K = {predictions, dynamics, value, options, uncertainty, coverage, plasticity}
+
+    ★ 不暴露参数, 只暴露**知识查询**。
+    """
+
+    def __init__(self, n_dom, dim_x, n_models=5, seed=0, alpha0=0.05, mu=0.01):
+        self.n_dom = int(n_dom)
+        self.dim_x = int(dim_x)
+        # Level 1 预测知识 K_P
+        self.predictions = GVFBank(dim_x, seed=seed)
+        # Level 2 因果/转移知识 K_T
+        from hibs_lnn.uncertainty_gate import TransitionEnsemble
+        self.dynamics_model = TransitionEnsemble(n_models=n_models, seed=seed)
+        self._dyn_fitted = False
+        # Level 3 价值/策略知识 K_V  (由外部 proposer 提供, 这里只登记)
+        self.value_fn = None
+        self.policy = None
+        # Level 4 抽象知识 K_A
+        self.options = None
+        # 元知识
+        from hibs_lnn.uncertainty_gate import UncertaintyGate
+        self.uncertainty = UncertaintyGate(tau_C=1.0)
+        self.coverage = Coverage(self.n_dom)
+        self.plasticity = Plasticity(dim_x, alpha0=alpha0, mu=mu)
+        self.seed = seed
+
+    # ── 写入 ──────────────────────────────────────────────────────────
+    def fit_dynamics(self, X, Y):
+        self.dynamics_model.fit(X, Y, self.n_dom, None)
+        self._dyn_fitted = True
+        # 标定不确定性阈值
+        visits = self.coverage.n
+        n = len(X)
+        step = max(1, n // 100)
+        self.uncertainty.calibrate(
+            [self.dynamics_model.predict(X[i, :self.dim_x], int(X[i, -1]), visits)[1]
+             for i in range(0, n, step)])
+        return self
+
+    def register_value_fn(self, fn, policy=None):
+        """登记价值/策略知识 (K_V)。fn(s, a) -> V。"""
+        self.value_fn = fn
+        self.policy = policy
+        return self
+
+    def register_options(self, option_manager):
+        """登记抽象知识 (K_A)。"""
+        self.options = option_manager
+        return self
+
+    def observe_gvf(self, phi, cumulants, phi_next):
+        return self.predictions.update(phi, cumulants, phi_next)
+
+    def observe_action(self, a):
+        self.coverage.observe(a)
+
+    def observe_plasticity(self, phi, delta):
+        self.plasticity.update(phi, delta)
+
+    # ── 查询 (知识接口) ────────────────────────────────────────────────
+    def predict(self, s, a):
+        """未来会发生什么 (Level 1+2 合成)。"""
+        if not self._dyn_fitted:
+            return np.asarray(s, dtype=float).copy(), float("inf")
+        return self.dynamics_model.predict(s, a, self.coverage.n)
+
+    def value(self, s, a):
+        """什么结果更好 (Level 3)。
+
+        ★ **对未知输入必须返回 NaN, 而不是抛异常**。
+        知识层被问到一个它没见过的 (s,a) 时, 正确反应是"我不知道", 不是崩。
+        (这条是实测抓到的: 测试里对从未出现过的动作 7 查询, value_fn 抛 KeyError
+        一路炸穿 knowledge_of —— 而"承认不知道"恰恰是这一层的核心语义。)
+        """
+        if self.value_fn is None:
+            return float("nan")
+        try:
+            return float(self.value_fn(s, a))
+        except Exception:
+            return float("nan")
+
+    def skills(self):
+        """哪些过程是一个整体技能 (Level 4)。"""
+        if self.options is None:
+            return []
+        return [o.stats() for o in getattr(self.options, "options", [])]
+
+    def confidence(self, s, a):
+        """我对自己的预测有多确定 —— 返回 [0,1], 1 = 最确定。"""
+        _, unc = self.predict(s, a)
+        if not np.isfinite(unc):
+            return 0.0
+        tau = self.uncertainty.tau_U
+        if tau is None or not np.isfinite(tau) or tau <= 0:
+            return 0.5
+        return float(1.0 / (1.0 + unc / tau))
+
+    def coverage_of(self, a):
+        return self.coverage.of(a)
+
+    def knowledge_of(self, s, a):
+        """★★ 统一查询: 对任意 (s,a), agent 到底知道什么。
+
+        这是 Knowledge≠Parameter 的直接体现 —— 问的是**内容**不是参数。
+        """
+        s_next, unc = self.predict(s, a)
+        val = self.value(s, a)
+        novel = bool(self.coverage_of(a) == 0)
+        known = bool(not novel and np.isfinite(unc))
+        return {
+            "state": np.round(np.asarray(s, dtype=float), 4).tolist(),
+            "action": int(a),
+            "predicted_next": np.round(np.asarray(s_next), 4).tolist(),
+            "uncertainty": float(unc) if np.isfinite(unc) else None,
+            "confidence": self.confidence(s, a),
+            "value": (val if np.isfinite(val) else None),
+            "coverage": self.coverage_of(a),
+            "coverage_gate": self.coverage.gate(a),
+            "trustworthy": bool(self.uncertainty.allow(s, a, self.coverage.n)[0]),
+            "novel": novel,
+            # ★ 这一项是整层的立命之处: agent 明确区分「我知道」与「我不知道」
+            "known": known,
+            "verdict": ("我不知道" if not known else
+                        ("不太确定" if self.confidence(s, a) < 0.5 else "我知道")),
+        }
+
+    # ── 摘要 / 持久化 ─────────────────────────────────────────────────
+    def describe(self) -> dict:
+        """分层摘要: 这是我"知道了什么"的完整画像。"""
+        return {
+            "Level1_predictions": self.predictions.stats(),
+            "Level2_dynamics": {"fitted": self._dyn_fitted,
+                                "n_models": len(getattr(self.dynamics_model, "Ws", []) or []),
+                                "dim_x": self.dim_x, "n_dom": self.n_dom},
+            "Level3_value": {"registered": self.value_fn is not None,
+                             "policy_registered": self.policy is not None},
+            "Level4_abstraction": {"n_options": len(self.skills()),
+                                   "options": self.skills()[:6]},
+            "meta_uncertainty": {"tau_U": self.uncertainty.tau_U,
+                                 "tau_C": self.uncertainty.tau_C},
+            "meta_coverage": self.coverage.stats(),
+            "meta_plasticity": self.plasticity.stats(),
+        }
+
+    def to_dict(self) -> dict:
+        """知识可以被**留下来** —— 持久化后能与旧版本比对。"""
+        return {
+            "coverage_n": self.coverage.n.tolist(),
+            "coverage_total": self.coverage.n_total,
+            "gvf_w": [g.w.tolist() for g in self.predictions.gvfs],
+            "gvf_steps": [g.steps for g in self.predictions.gvfs],
+            "dyn_W": [W.tolist() for W in (getattr(self.dynamics_model, "Ws", None) or [])],
+            "tau_U": self.uncertainty.tau_U,
+            "plasticity_beta": self.plasticity.beta.tolist(),
+            "plasticity_updates": self.plasticity.updates,
+            "n_options": len(self.skills()),
+        }
+
+    def growth(self, old_dict) -> dict:
+        """★ 与旧版本比对: 知识**具体**变了什么。
+
+        这是"持续构建内部知识"的可判定形式 —— 不是"又训了一轮",
+        而是能逐项指出知识的变化量。
+        """
+        if not old_dict:
+            return {"note": "no prior knowledge"}
+        out = {}
+        # 覆盖度变化
+        old_n = np.array(old_dict.get("coverage_n", [0] * self.n_dom), dtype=float)
+        out["coverage_delta"] = (self.coverage.n - old_n).astype(int).tolist()
+        out["coverage_total_delta"] = int(self.coverage.n_total - old_dict.get("coverage_total", 0))
+        # GVF 权重变化 (预测知识变了多少)
+        gw_old = old_dict.get("gvf_w")
+        if gw_old is not None and len(gw_old) == len(self.predictions.gvfs):
+            d = [float(np.linalg.norm(np.array(g.w) - np.array(o)))
+                 for g, o in zip(self.predictions.gvfs, gw_old)]
+            out["gvf_weight_delta"] = np.round(d, 6).tolist()
+            out["gvf_weight_delta_mean"] = float(np.mean(d))
+        # 转移模型变化
+        dw_old = old_dict.get("dyn_W")
+        cur = getattr(self.dynamics_model, "Ws", None)
+        if dw_old and cur and len(dw_old) == len(cur):
+            d = [float(np.linalg.norm(np.array(W) - np.array(o))) for W, o in zip(cur, dw_old)]
+            out["dyn_weight_delta_mean"] = float(np.mean(d))
+        # 可塑性元知识变化
+        pb_old = old_dict.get("plasticity_beta")
+        if pb_old is not None and len(pb_old) == len(self.plasticity.beta):
+            out["plasticity_beta_delta"] = np.round(
+                self.plasticity.beta - np.array(pb_old), 6).tolist()
+        out["n_options_delta"] = len(self.skills()) - old_dict.get("n_options", 0)
+        return out
+
+    def stats(self):
+        return {"n_dom": self.n_dom, "dim_x": self.dim_x,
+                "dyn_fitted": self._dyn_fitted, "n_options": len(self.skills()),
+                "coverage_total": int(self.coverage.n_total)}

hibs_lnn/meta_rule_world.py

@@ -0,0 +1,387 @@
+"""
+V31.0/V31.2: MetaRuleWorld — 元学习任务分布世界
+============================================
+元学习设定: 每个"任务" = 一个规则变体 (remap 参数化)。
+
+任务 T_i 的规则 = 一个寄存器重映射:
+  remap=None              → 标准执行 (规则 A)
+  remap=(0,1)             → R0↔R1 互换 (规则 B)   [兼容旧接口: pair]
+  remap=(1,3,2,0)         → 任意排列 perm[reg]    [V31.2: 全 24 种排列]
+
+V31.2 长流扩展 (S4 对称群, 24 条规则):
+  S4 = 1 identity + 6 对换 + 8 三轮换 + 6 四轮换 + 3 双对换
+  训练: identity + 6 对换 + 5 三轮换 = 12 条
+  未见: 3 三轮换 + 6 四轮换 + 3 双对换 = 12 条 (结构上不同 → "没学过的学习方法")
+
+目标 (Javed & White NeurIPS 2019 精神):
+  不学"预测所有规则"的单一 head (V30.4 失败模式),
+  而是学一个表示 φ, 使任意规则可以快速适应 (内循环 head 更新)。
+
+数据格式 (离线监督式):
+  context = 最近 window 个 READ 观察 (5 tokens each) → 预测下一个 READ (5 tokens)
+  模型从观察历史推断当前规则 → 预测 EXEC 后的寄存器状态。
+"""
+
+import torch
+import random
+from itertools import permutations
+from .code_world import (
+    RegisterMachine, CodeSandboxWorld,
+    N_REGISTERS, INSTR_LEN, OPCODE_TOKEN_OFFSET,
+    OPCODES, OPCODES_INV,
+)
+
+
+def s4_groups():
+    """S4 按结构分组: (identity, swaps, 3cycles, 4cycles, double_swaps)。"""
+    allp = list(permutations(range(4)))
+    identity = [(0, 1, 2, 3)]
+    swaps, c3, c4, dbl = [], [], [], []
+    for p in allp:
+        if p == (0, 1, 2, 3):
+            continue
+        fixed = sum(1 for i in range(4) if p[i] == i)
+        if fixed == 2:
+            swaps.append(p)          # 单对换
+        elif fixed == 1:
+            c3.append(p)             # 三轮换
+        elif fixed == 0:
+            # 四轮换 (阶 4) vs 双对换 (阶 2)
+            if all(p[p[i]] == i for i in range(4)):
+                dbl.append(p)        # 双对换 (Klein)
+            else:
+                c4.append(p)         # 四轮换
+    return identity, swaps, c3, c4, dbl
+
+
+# V31.2 规则划分: 训练 = identity + 6 对换 + 5 三轮换 (12)
+#                 未见 = 3 三轮换 + 6 四轮换 + 3 双对换 (12, 结构不同)
+def build_rule_splits(seed=42):
+    identity, swaps, c3, c4, dbl = s4_groups()
+    rng = random.Random(seed)
+    rng.shuffle(c3); rng.shuffle(c4); rng.shuffle(dbl)
+    train = identity + swaps + c3[:5]
+    test = c3[5:] + c4 + dbl
+    return train, test
+
+
+# 各 opcode 的寄存器操作数位置 (立即数位置不重映射):
+#   SET dst,val   → a1 寄存器, a2 立即数 (0-99)
+#   MOV src,dst   → a1,a2 寄存器
+#   ADD/SUB a,b,d → a1,a2,a3 寄存器
+#   INC/DEC reg   → a1 寄存器
+#   SWP a,b       → a1,a2 寄存器
+_REG_OPPOS = {0: (), 1: (0,), 2: (0, 1), 3: (0, 1, 2), 4: (0, 1, 2),
+              5: (0,), 6: (0,), 7: (0, 1)}
+
+
+class MetaRuleMachine(RegisterMachine):
+    """RegisterMachine + 参数化寄存器重映射 (任意排列或 pair)。
+
+    V31.2 修复 (原 V31.0 bug): 只重映射**寄存器操作数**位置,
+    立即数 (SET 的 a2, 0-99) 不受 remap 影响。
+    原实现 `_remap` 作用于所有操作数 → 立即数被 mod 4 重映射,
+    "SET R0 42 → R1=42" 变成 "SET R1 2" — 规则语义被污染
+    (V31.0 世界自测的 remap 项其实一直失败, 计数器有 bug 显示 7/7)。
+    """
+
+    def __init__(self, V, remap_pair=None, remap=None):
+        super().__init__(V)
+        if remap is None:
+            if remap_pair is None:
+                remap = (0, 1, 2, 3)
+            else:
+                i, j = remap_pair
+                remap = tuple(j if k == i else (i if k == j else k)
+                              for k in range(4))
+        self.remap_pair = remap_pair  # 兼容旧接口 (V31.0)
+        self.remap = remap            # V31.2: 完整排列 (identity = (0,1,2,3))
+
+    def _remap(self, reg: int) -> int:
+        return self.remap[reg % N_REGISTERS]
+
+    def step_execute(self) -> bool:
+        if self.halted or self.pc >= len(self.program):
+            self.halted = True
+            return False
+        if self.step_count >= self.max_steps:
+            self.halted = True
+            return False
+
+        opcode, a1, a2, a3 = self.program[self.pc]
+        name = OPCODES_INV[opcode]
+
+        if self.remap != (0, 1, 2, 3):
+            args = [a1, a2, a3]
+            for pos in _REG_OPPOS[opcode]:
+                args[pos] = self._remap(args[pos])
+            a1, a2, a3 = args
+
+        try:
+            if name == 'NOP':
+                pass
+            elif name == 'SET':
+                self.regs[a1 % N_REGISTERS] = a2 % self.V
+            elif name == 'MOV':
+                self.regs[a2 % N_REGISTERS] = self.regs[a1 % N_REGISTERS]
+            elif name == 'ADD':
+                self.regs[a3 % N_REGISTERS] = (
+                    self.regs[a1 % N_REGISTERS] + self.regs[a2 % N_REGISTERS]
+                ) % self.V
+            elif name == 'SUB':
+                self.regs[a3 % N_REGISTERS] = max(
+                    0, self.regs[a1 % N_REGISTERS] - self.regs[a2 % N_REGISTERS]
+                )
+            elif name == 'INC':
+                self.regs[a1 % N_REGISTERS] = (
+                    self.regs[a1 % N_REGISTERS] + 1
+                ) % self.V
+            elif name == 'DEC':
+                self.regs[a1 % N_REGISTERS] = max(
+                    0, self.regs[a1 % N_REGISTERS] - 1
+                )
+            elif name == 'SWP':
+                ri, rj = a1 % N_REGISTERS, a2 % N_REGISTERS
+                self.regs[ri], self.regs[rj] = self.regs[rj], self.regs[ri]
+        except Exception:
+            return False
+
+        self.pc += 1
+        self.step_count += 1
+        return True
+
+
+class MetaRuleWorld(CodeSandboxWorld):
+    """代码执行世界, 规则由 remap_pair 参数化。观察格式与 CodeSandboxWorld 一致。"""
+
+    K = 5
+    READ_WINDOW = N_REGISTERS + 1  # 4 regs + 1 opcode
+    ACTIONS = ['READ', 'EXEC', 'RESET', 'NEWREG', 'TOME']
+
+    def __init__(self, V: int, remap_pair=None, remap=None,
+                 max_program_len: int = 8):
+        self.V = V
+        self.TOME = V + 1
+        self.world_vocab_size = V + 2
+        self.max_program_len = max_program_len
+        self.remap_pair = remap_pair
+        self.remap = remap
+        self._new_episode()
+
+    def _new_episode(self):
+        self.vm = MetaRuleMachine(self.V, remap_pair=self.remap_pair,
+                                  remap=self.remap)
+        self.exec_count = 0
+        self.current_step = 0
+        self.n_erases = 0
+
+        prog_len = random.randint(2, self.max_program_len)
+        self.vm.generate_random_program(prog_len)
+
+        for i in range(N_REGISTERS):
+            self.vm.regs[i] = random.randint(0, min(self.V - 1, 50))
+
+        pre_steps = random.randint(0, min(2, len(self.vm.program) - 1))
+        for _ in range(pre_steps):
+            self.vm.step_execute()
+            self.exec_count += 1
+
+    def reset(self):
+        self._new_episode()
+
+
+# ============================================================
+# 任务数据生成 (离线监督式)
+# ============================================================
+# V31 观察格式 (8 tokens): [R0,R1,R2,R3, opcode+100, a1, a2, a3]
+#   → 完整指令可见, "预测 EXEC 后状态"是确定性问题 (信息完备)
+#   → 规则差异 (remap) 真正可学习: SET R0 42 → A: R0=42 / B: R1=42
+# 注意: 这与 V30 系列不同 (V30 只有 opcode 无操作数 → 信息不足 → pred 2-8%)
+
+def _instr_tokens(vm):
+    """当前 PC 指令的 4 个 token: [opcode+100, a1, a2, a3], 程序结束用 TOME。"""
+    if vm.halted or vm.pc >= len(vm.program):
+        return [vm.V + 1] * 4  # TOME
+    opcode, a1, a2, a3 = vm.program[vm.pc]
+    return [opcode + 100, min(a1, 99), min(a2, 99), min(a3, 99)]
+
+
+def _world_obs(world):
+    """8-token 观察: [R0,R1,R2,R3, instr...]"""
+    vm = world.vm
+    state = [min(r, world.V - 1) for r in vm.regs]
+    return state + _instr_tokens(vm)
+
+
+def gen_episode_pairs(world, V, max_len=8, window=3, stop_at_halt=False):
+    """
+    从一个 episode 生成 (context, target) 监督对。
+
+    context = 最近 window 个观察拼接 (window*8 tokens)
+    target  = EXEC 后的观察 (8 tokens)
+
+    模型从观察历史推断当前规则 → 预测 EXEC 后的完整状态。
+    由于观察含完整指令, 给定规则下 target 是确定性的。
+
+    stop_at_halt (V33 世界修复): 程序结束 (halted) 后立即停止,
+    不生成含 TOME(201) 填充的 target → 每个 target 都有信息量
+    (旧世界 ~77.5% target 后 4 token 是 TOME, 虚高 full-8 acc)。
+    """
+    pairs = []
+    obs = torch.tensor(_world_obs(world), dtype=torch.long)
+    history = [obs]
+    for _ in range(max_len):
+        world.query(1)  # EXEC
+        obs = torch.tensor(_world_obs(world), dtype=torch.long)
+        if stop_at_halt and world.vm.halted:
+            break  # 程序结束: 不再追加 TOME 观察
+        history.append(obs)
+    for t in range(window, len(history)):
+        ctx = torch.cat(history[t - window:t]).long()   # window*8
+        tgt = history[t].long()                          # 8
+        pairs.append((ctx, tgt))
+    return pairs
+
+
+def gen_task_data(remap_pair, V, n_episodes=48, max_len=8, window=3,
+                  seed=42, max_program_len=8, remap=None,
+                  stop_at_halt=False):
+    """
+    生成一个任务 (规则) 的数据集。
+    返回: list of (context_ids, target_ids), 均 clamp 到 [0, V+1]。
+    """
+    rng_state = random.getstate()
+    random.seed(seed)
+    pairs = []
+    for _ in range(n_episodes):
+        w = MetaRuleWorld(V, remap_pair=remap_pair, remap=remap,
+                          max_program_len=max_program_len)
+        pairs.extend(gen_episode_pairs(w, V, max_len=max_len, window=window,
+                                       stop_at_halt=stop_at_halt))
+    random.setstate(rng_state)
+    # clamp
+    pairs = [(c.clamp(0, V + 1), t.clamp(0, V + 1)) for c, t in pairs]
+    return pairs
+
+
+def gen_task_data_split(remap_pair, V, n_support=48, n_query=24,
+                        max_len=8, window=3, seed=42, max_program_len=8,
+                        remap=None, stop_at_halt=False):
+    """生成任务的 support/query 划分 (不同 seed 保证不重叠)。"""
+    support = gen_task_data(remap_pair, V, n_episodes=n_support,
+                            max_len=max_len, window=window,
+                            seed=seed, max_program_len=max_program_len,
+                            remap=remap, stop_at_halt=stop_at_halt)
+    query = gen_task_data(remap_pair, V, n_episodes=n_query,
+                          max_len=max_len, window=window,
+                          seed=seed + 1000, max_program_len=max_program_len,
+                          remap=remap, stop_at_halt=stop_at_halt)
+    return support, query
+
+
+def _self_test():
+    ok = 0
+    total = 0
+    def check(cond, msg):
+        nonlocal ok, total
+        total += 1
+        if cond:
+            ok += 1
+            print(f"  OK {msg}")
+        else:
+            print(f"  FAIL {msg}")
+
+    random.seed(42)
+    V = 100
+
+    # 1. 规则 A (无 remap): SET R0 42 → R0=42
+    vm_a = MetaRuleMachine(V=100, remap_pair=None)
+    vm_a.load_instruction([101, 0, 42, 0])
+    vm_a.step_execute()
+    check(vm_a.regs[0] == 42 and vm_a.regs[1] == 0,
+          f"A: SET R0 42 → R0={vm_a.regs[0]}, R1={vm_a.regs[1]}")
+
+    # 2. 规则 B (0,1): SET R0 42 → R1=42
+    vm_b = MetaRuleMachine(V=100, remap_pair=(0, 1))
+    vm_b.load_instruction([101, 0, 42, 0])
+    vm_b.step_execute()
+    check(vm_b.regs[1] == 42 and vm_b.regs[0] == 0,
+          f"B: SET R0 42 → R1={vm_b.regs[1]}, R0={vm_b.regs[0]}")
+
+    # 3. 规则 C (0,2): SET R0 42 → R2=42
+    vm_c = MetaRuleMachine(V=100, remap_pair=(0, 2))
+    vm_c.load_instruction([101, 0, 42, 0])
+    vm_c.step_execute()
+    check(vm_c.regs[2] == 42 and vm_c.regs[0] == 0,
+          f"C: SET R0 42 → R2={vm_c.regs[2]}, R0={vm_c.regs[0]}")
+
+    # 4. 规则 D (1,2): SET R1 42 → R2=42
+    vm_d = MetaRuleMachine(V=100, remap_pair=(1, 2))
+    vm_d.load_instruction([101, 1, 42, 0])
+    vm_d.step_execute()
+    check(vm_d.regs[2] == 42 and vm_d.regs[1] == 0,
+          f"D: SET R1 42 → R2={vm_d.regs[2]}, R1={vm_d.regs[1]}")
+
+    # 5. 数据生成: context/target shapes (8-token 观察)
+    w = MetaRuleWorld(V=100, remap_pair=(0, 1))
+    pairs = gen_episode_pairs(w, V, max_len=8, window=3)
+    check(len(pairs) > 0, f"episode pairs = {len(pairs)}")
+    ctx, tgt = pairs[0]
+    check(ctx.shape[0] == 24 and tgt.shape[0] == 8,
+          f"ctx={tuple(ctx.shape)} tgt={tuple(tgt.shape)} (24/8)")
+
+    # 5b. 信息完备性: 给定规则, target 确定 (SET R0 42 在规则 A/B 下不同)
+    random.seed(3)
+    wA = MetaRuleWorld(V=100, remap_pair=None)
+    wA.vm.program = [(1, 0, 42, 0)]; wA.vm.pc = 0; wA.vm.regs = [0, 0, 0, 0]
+    wA.vm.halted = False
+    obsA = _world_obs(wA)
+    wA.query(1)  # EXEC
+    afterA = _world_obs(wA)
+    wB = MetaRuleWorld(V=100, remap_pair=(0, 1))
+    wB.vm.program = [(1, 0, 42, 0)]; wB.vm.pc = 0; wB.vm.regs = [0, 0, 0, 0]
+    wB.vm.halted = False
+    obsB = _world_obs(wB)
+    wB.query(1)  # EXEC
+    afterB = _world_obs(wB)
+    check(obsA[:4] == obsB[:4], "same state before EXEC")
+    check(afterA[:4] == [42, 0, 0, 0], f"A after SET R0 42: {afterA[:4]}")
+    check(afterB[:4] == [0, 42, 0, 0], f"B after SET R0 42: {afterB[:4]}")
+    check(afterA[:4] != afterB[:4], "rule difference visible in targets")
+
+    # 6. support/query 划分
+    sup, qry = gen_task_data_split((0, 1), V, n_support=8, n_query=4, seed=42)
+    check(len(sup) > 0 and len(qry) > 0, f"support={len(sup)} query={len(qry)}")
+
+    # 7. 不同规则产生不同数据分布 (相同 seed, 相同程序 → 不同状态)
+    random.seed(7)
+    w1 = MetaRuleWorld(V=100, remap_pair=None)
+    w2 = MetaRuleWorld(V=100, remap_pair=(0, 1))
+    # 手动构造相同程序
+    prog = [(1, 0, 42, 0), (5, 0, 0, 0)]  # SET R0 42; INC R0
+    w1.vm.program = prog[:]; w1.vm.pc = 0; w1.vm.regs = [0, 0, 0, 0]
+    w2.vm.program = prog[:]; w2.vm.pc = 0; w2.vm.regs = [0, 0, 0, 0]
+    w1.vm.step_execute(); w2.vm.step_execute()
+    s1 = w1.vm.regs[:]; s2 = w2.vm.regs[:]
+    check(s1[0] == 42 and s2[1] == 42,
+          f"same prog diverges: A={s1[:2]}, B={s2[:2]}")
+
+    # 8. V31.2 排列规则: 只重映射寄存器, 立即数不动
+    vm_p = MetaRuleMachine(V=100, remap=(1, 3, 2, 0))
+    vm_p.load_instruction([101, 0, 42, 0])   # SET R0 42
+    vm_p.step_execute()
+    check(vm_p.regs[1] == 42,
+          f"perm(1,3,2,0): SET R0 42 → R1={vm_p.regs[1]} (立即数 42 不受影响)")
+    vm_p2 = MetaRuleMachine(V=100, remap=(1, 3, 2, 0))
+    vm_p2.load_instruction([104, 0, 1, 2])   # SUB R0 R1 → R2
+    vm_p2.step_execute()
+    # SUB R0(→1) R1(→3) → R2(→2): regs[2] = regs[1] - regs[3] = 0
+    check(vm_p2.regs[2] == 0,
+          f"perm SUB: R0,R1→R2 remap 后 regs[2]=regs[1]-regs[3]")
+
+    print(f"\n  {ok}/{total} passed")
+    return ok == total
+
+
+if __name__ == "__main__":
+    _self_test()

hibs_lnn/oak_proposer.py

@@ -0,0 +1,444 @@
+"""oak_proposer.py — OaK 提议器: 把 InternalKnowledge + Options 接进主回路。
+
+## 状态/动作的定义 (在这个问题里)
+
+    state  = 各细区间的**能力画像** (维度 = n_fine)   "我现在会什么"
+    action = 选哪个细区间训练 (0..n_fine-1)
+    next   = 训练后的新能力画像
+    reward = Δ(any-time 准确率)
+
+这就是真实的持续学习闭环: **动作是"去练哪块", 环境是"练完能力怎么变"。**
+`T(s,a) -> s'` 因此是一个**真正可学、数据里天然存在**的转移 —— 不是硬凑的。
+
+## 结构
+
+    OAKProposer
+      ├── base    : RLProposer        (Level 3 价值/策略知识, 复用已验证机制)
+      └── know    : InternalKnowledge (Level 1/2/4 + 三类元知识)
+            ├── predictions  GVFBank
+            ├── dynamics     TransitionEnsemble
+            ├── options      OptionManager
+            ├── uncertainty  UncertaintyGate
+            ├── coverage     Coverage
+            └── plasticity   Plasticity
+
+## act() 的决策顺序
+
+    ① 有 option 在跑且未终止  -> 沿 option 的动作序列走
+    ② 否则取 base 的候选      -> 过**门控**; 被拒则退回已覆盖动作
+    ③ 记录 (state, action)    -> 供 dynamics/option 发现用
+
+## E9 vs E10 就是一个 flag
+
+    use_options=False  -> E9  (+coverage/uncertainty 门控)
+    use_options=True   -> E10 (+Options)
+    两者共用同一 base 与同一门控, 差异**只**在于是否使用时间抽象。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from hibs_lnn.knowledge import InternalKnowledge
+
+
+class OAKProposer:
+    def __init__(self, fine_desc, n_fine, k=3, seed=0, tau=0.5,
+                 mu=0.05, alpha0=0.2, explore_w=0.5, algo="autostep",
+                 n_know=0, use_options=True, use_gate=True,
+                 n_models=5, refresh_every=4, min_transitions=40,
+                 n_regions=4, max_opt_len=3, opt_frac=1.0,
+                 opt_mode="fixed", term_eps=0.05, stall_tol=0.0,
+                 dyn_model="linear", n_regions_opt=16, use_subgoals=0):
+        from hibs_lnn.rl_proposer import RLProposer
+        self.n_fine = int(n_fine)
+        self.n = self.n_fine
+        self.k = int(k)
+        self.seed = seed
+        self.use_options = bool(use_options)
+        self.use_gate = bool(use_gate)
+        self.refresh_every = int(refresh_every)
+        self.min_transitions = int(min_transitions)
+        self.n_regions = int(n_regions)
+        self.max_opt_len = int(max_opt_len)
+        # ★ 诊断用: 只在一部分轮次允许启用 option。
+        #   若"Options 有害"确实来自 option 执行本身 (提交一段固定动作序列 ->
+        #   减少自适应性 / 降低探索多样性), 那么伤害应当**随 opt_frac 单调放大**。
+        #   若伤害与用量无关, 说明另有来源 (如 discovery 本身在扰动状态)。
+        self.opt_frac = float(opt_frac)
+        self._opt_round = 0
+        # ★ opt_mode: Option 的**执行方式** (用户 2026-09-14 指导的 K1 矩阵)
+        #   "fixed"              O1  固定动作序列 = open-loop (旧行为, D1 的病灶)
+        #   "goal"               O2  目标条件 + **每步重算动作** (闭环)
+        #   "goal_term"          O3  O2 + 自适应终止 β_o(s)
+        #   "goal_term_override" O4  O3 + 不确定性抢占 (Option 从属于当前证据)
+        self.opt_mode = str(opt_mode)
+        self.term_eps = float(term_eps)
+        self.stall_tol = float(stall_tol)
+        self._opt_stall_d = None
+        self.override_count = 0
+        self.term_reasons = {}
+        self.replan_steps = 0
+        self.gate_blocked = 0        # _goal_action 因门控全拒返回 None
+        self.no_finite_unc = 0       # _goal_action 因无有限不确定性返回 None
+        self.goal_none = 0           # _goal_action 返回 None 总次数
+        self.start_blocked = 0       # 起 option 时算不出动作 (静默空转) 的次数
+        # ★ option 有效期。原实现一旦启动就**永不重选** (实测: 1 个 option
+        #   连跑 105 步 = 训练全程的 87%)。那不是 option, 是"锁死"。
+        #   正确语义: option 是**有名义长度的技能**, 跑完它的长度就结束,
+        #   由外层重新评估该用哪个技能 (或交回 base policy)。
+        self._opt_age = 0
+        self._opt_max_age = int(max_opt_len)
+        # ★ 世界模型 (实测: 线性 ridge 表达不了结构化动力学 —— 在 KeyDoor 这类
+        #   离散/条件性动力学上四个动作预测到**同一个**下一状态, 转移图退化成
+        #   几乎无边, option 发现为 0。计数式表格模型修掉了这个。)
+        self.dyn_model_kind = str(dyn_model)
+        self.n_regions_opt = int(n_regions_opt)
+        self.use_subgoals = int(use_subgoals)
+
+        # Level 3: 复用已验证的 RL 提议器
+        self.base = RLProposer(fine_desc, tau=tau, k=k, mu=mu, alpha0=alpha0,
+                               explore_w=explore_w, algo=algo, n_know=n_know,
+                               seed=seed)
+        # ★ 内部知识**惰性创建**: 状态维度在构造时未知。
+        #   主回路的状态是 `row` = 每**粗域**准确率 (长度 = --domains),
+        #   而动作数是细区间数 n_fine —— 两个维度**不同**。
+        #   (实测: 按 n_fine 建 GVF 会在 observe 时撞
+        #    `size 3 is different from 6`)。
+        self._know_cfg = dict(n_models=n_models, seed=seed, alpha0=alpha0, mu=mu)
+        self.know = None
+        self.dim_state = None
+        self._state_scale = 0.0
+
+        # 转移日志: (state_t, action, state_{t+1})
+        self.trans = []
+        self._prev_state = None
+        self._prev_pick = None
+        self._last_acc = {}
+        self._opt_queue = []          # 正在执行的 option 剩余动作
+        self._opt_active = None
+        self.refresh_count = 0
+        self.untrusted_picks = 0      # 提议落在不可信区的次数 (仅诊断)
+        self.fallback_count = 0       # 保留字段 (旧: 门控重定向次数, 已废弃)
+        self.option_steps = 0         # 由 option 决定的步数
+        self.option_starts = 0        # option 被启动的次数
+
+    # ── 惰性初始化 ──────────────────────────────────────────────────
+    def _ensure_know(self, dim_state):
+        if self.know is not None:
+            return self.know
+        self.dim_state = int(dim_state)
+        self.know = InternalKnowledge(self.n_fine, self.dim_state, **self._know_cfg)
+        if self.dyn_model_kind == "tabular":
+            from hibs_lnn.uncertainty_gate import TabularTransition
+            self.know.dynamics_model = TabularTransition()
+        self.know.register_value_fn(
+            lambda s, a: float(self._last_acc.get(int(a), np.nan)),
+            policy="rl-base")
+        return self.know
+
+    # ── 记录环境反馈 ────────────────────────────────────────────────
+    def set_state(self, state):
+        """每轮训练后由主回路喂入**新**能力画像。"""
+        st = np.asarray(state, dtype=float)
+        # 状态尺度 = 相邻两轮状态变化的典型幅度 (用于自适应阈值)
+        if getattr(self, "_prev_state", None) is not None:
+            _d = float(np.linalg.norm(st - np.asarray(self._prev_state, dtype=float)))
+            _a = getattr(self, "_state_scale", 0.0)
+            self._state_scale = _d if _a == 0.0 else 0.9 * _a + 0.1 * _d
+        self._ensure_know(st.shape[0])
+        if self._prev_state is not None and self._prev_pick is not None:
+            for a in (self._prev_pick if isinstance(self._prev_pick, (list, tuple))
+                      else [self._prev_pick]):
+                self.trans.append((self._prev_state.copy(), int(a), st.copy()))
+                self.know.observe_action(int(a))
+        self._prev_state = st
+        self._last_acc = {i: float(v) for i, v in enumerate(st)
+                          if np.isfinite(v)}
+
+    def set_pick(self, pick):
+        """记录本轮真正执行的动作。"""
+        self._prev_pick = list(pick) if isinstance(pick, (list, tuple)) else [pick]
+
+    # ── 动作选择 ───────────────────────────────────────────────────
+    def act(self):
+        # ① option 在执行中
+        if self.use_options and self._opt_active is not None and self.opt_mode != "fixed":
+            o = self._opt_active
+            s_now = self._prev_state
+            if s_now is None:
+                self._opt_active = None
+            else:
+                _, unc_a = self.know.predict(s_now, int(o.actions[0]))
+                tau = self.know.uncertainty.tau_U
+                if self.opt_mode == "goal_term_override":
+                    if (not np.isfinite(unc_a)) or (tau and unc_a >= tau):
+                        self.override_count += 1
+                        self.term_reasons["override"] = self.term_reasons.get("override", 0) + 1
+                        self._opt_active = None
+                        return list(self.base.act())
+                # ★ 有效期检查 (对**所有**闭环模式生效)
+                self._opt_age += 1
+                if self._opt_age > self._opt_max_age:
+                    self.term_reasons["expired"] = self.term_reasons.get("expired", 0) + 1
+                    self._opt_active = None
+                    self._opt_age = 0
+                    return list(self.base.act())
+                if self.opt_mode in ("goal_term", "goal_term_override"):
+                    done, why = o.terminated(
+                        s_now, unc=unc_a, eps=self._eps_eff(),
+                        tau_U=(tau if self.opt_mode == "goal_term_override" else None),
+                        stall=self.stall_tol)
+                    if done:
+                        self.term_reasons[why] = self.term_reasons.get(why, 0) + 1
+                        self._opt_active = None
+                        return list(self.base.act())
+                a = self._goal_action(o)
+                if a is None:
+                    self._opt_active = None
+                else:
+                    self.replan_steps += 1
+                    self.option_steps += 1
+                    return [int(a)]
+        if self.use_options and self._opt_queue and self.opt_mode == "fixed":
+            a = int(self._opt_queue.pop(0))
+            self.option_steps += 1
+            if not self._opt_queue:
+                self._opt_active = None
+            return [a]
+
+        pick = list(self.base.act())
+
+        # ② ★ 门控**不用于 action selection**。
+        #   早先版本在这里把零覆盖动作重定向到 `argmin(visits)` 的已覆盖动作,
+        #   结果是灾难性的: 一旦某个动作被覆盖, 门控就把**所有**提议都指向它
+        #   (实测 `per_action = [0,9,0,0,0,0]`, 9 轮只练了 1 个区间, 探索崩塌)。
+        #
+        #   语义纠正 (Q8 原文): "目标策略必须在现有经验中得到足够的信息支持" ——
+        #   这约束的是**模型驱动的规划决策** (凭预测去选), **不是**阻止 base
+        #   policy 去探索。往零覆盖区探索恰恰是想要的: 覆盖度只能这样长起来。
+        #   所以门控只作用在**模型被咨询**的地方 (option 选择 / rollout),
+        #   那两处已由 OptionManager.select(exclude_unc=True) 与
+        #   ens.rollout(gate=...) 各自保证。
+        if self.use_gate and self.know is not None:
+            # 只**记录**当前提议是否落在不可信区 (诊断用, 不做干预)
+            for a in pick:
+                if int(a) < self.n_fine:
+                    _, unc = self.know.predict(self._prev_state
+                                               if self._prev_state is not None
+                                               else np.zeros(self.dim_state or 1), int(a))
+                    tau = self.know.uncertainty.tau_U
+                    if (not np.isfinite(unc)) or (tau and unc >= tau):
+                        self.untrusted_picks += 1
+
+        # ③ 起一个新 option (受 opt_frac 限制)
+        self._opt_round += 1
+        _allow_opt = (self.opt_frac >= 1.0
+                      or (self.opt_frac > 0 and
+                          (self._opt_round % max(1, int(round(1.0 / self.opt_frac)))) == 0))
+        if (_allow_opt and self.use_options and self.know is not None
+                and self.know.options is not None and self._prev_state is not None):
+            o = self.know.options.select(self._prev_state, exclude_unc=True)
+            if o is not None and len(getattr(o, "actions", [])) > 1:
+                self._opt_active = o
+                # ★ 返回 option 的**第一个**动作。早先实现假设"起点的那个动作
+                #   已经执行过了", 于是只排队 actions[1:] —— 结果 option 的语义
+                #   只被用了一半, option_steps 实测只有 1~2 步。
+                self._opt_queue = [int(x) for x in o.actions[1:]]
+                if self.opt_mode == "fixed":
+                    self._opt_queue = [int(x) for x in o.actions[1:]]
+                    self.option_starts += 1
+                    return [int(o.actions[0])]
+                a = self._goal_action(o)          # 闭环: 立刻按当前状态算
+                if a is None:
+                    # ★ 计数诚实性: 算不出动作的 option **不算启动**。
+                    #   早先实现先 `option_starts += 1` 再判断, 于是"启动了 N 次但 0 步执行"
+                    #   看起来像机制在跑, 实际是 inert -> 一个**静默的空转实验**。
+                    self._opt_active = None
+                    self.start_blocked += 1
+                    return pick
+                self.option_starts += 1
+                self.replan_steps += 1
+                self.option_steps += 1
+                return [int(a)]
+        return pick
+
+    def _eps_eff(self):
+        """目标达成阈值 —— **必须与状态空间尺度匹配**。
+
+        原实现固定 term_eps=0.05 (给"距离"用的量级), 但状态是**准确率向量**,
+        单步变化就有 0.1~0.5 -> ‖s−g‖ < 0.05 几乎不可能 -> β_o 永不触发
+        -> `goal_term` 与 `goal` 给出**逐位相同**的结果 (实测: term={}).
+        """
+        sc = getattr(self, "_state_scale", 0.0)
+        return max(0.05, 0.25 * sc) if sc > 0 else 0.05
+
+    def _goal_action(self, opt):
+        """π_o(s_t) —— **按当前状态重算**动作, 而不是回放固定序列。
+
+            a = argmax_a [ ‖g−s‖ − ‖g−T(s,a)‖ ]
+        即"哪一步动作让我朝子目标前进最多"。
+
+        ★ 用户指出的核心修正: **抽象的是目标, 不是动作**。
+          固定序列执行 = "��发现了一段过去有效的脚本, 现在重放它",
+          状态变化不再触发动作重算 -> 适应性下降 (D1 实测 r=-0.80)。
+        """
+        s_now = self._prev_state
+        g = np.asarray(opt.goal_center, dtype=float)
+        d_now = float(np.linalg.norm(np.asarray(s_now, dtype=float) - g))
+        best_a, best_gain = None, -np.inf
+        n_gate_rej = 0
+        n_unc_bad = 0
+        for a in range(self.n_fine):
+            if self.use_gate:
+                ok, _ = self.know.uncertainty.allow(s_now, a, self.know.coverage.n)
+                if not ok:
+                    n_gate_rej += 1
+                    continue
+            s_next, unc = self.know.predict(s_now, a)
+            if not np.isfinite(unc):
+                n_unc_bad += 1
+                continue
+            gain = d_now - float(np.linalg.norm(np.asarray(s_next, dtype=float) - g))
+            if gain > best_gain:
+                best_a, best_gain = a, gain
+        if best_a is None:
+            self.goal_none += 1
+            if n_gate_rej == self.n_fine:
+                self.gate_blocked += 1
+            elif n_unc_bad > 0:
+                self.no_finite_unc += 1
+        return best_a
+
+    # ── 奖励 → 参数更新 (+ 知识维护) ────────────────────────────────
+    def observe(self, pick, acc, any_time):
+        self.base.observe(pick, acc=acc, any_time=any_time)
+
+    def update(self, pick):
+        self.base.update(pick)
+        # ★★ 必须在这里把**实际执行的动作**记进 coverage。
+        #    实测抓到的 bug(第 4 次同型): `InternalKnowledge.observe_action()` 是
+        #    coverage 的**唯一写入点**, 但主回路从来没调过它 -> `coverage.n` 永远全零
+        #    -> `UncertaintyGate.allow()` 对**所有**动作返回 False
+        #    (因为 `0 <= tau_C=1.0`) -> `_goal_action()` 的每一个候选都被 continue 掉
+        #    -> `best_a = None` -> 回落到 base -> 轨迹与 E9 **逐位相同**
+        #    (实测证据: goal/goal_term/override 三档的 alpha 与 e9 完全相同,
+        #     `option_starts > 0` 但 `option_steps == 0`)。
+        if self.know is not None:
+            _pick = pick if isinstance(pick, (list, tuple)) else [pick]
+            for _a in _pick:
+                if int(_a) >= 0:
+                    self.know.observe_action(int(_a))
+        # 预测知识: cumulant = 各区间能力本身 (GVF 学"能力会怎么走")
+        if self.know is not None and self._prev_state is not None:
+            phi = self._prev_state
+            cums = [float(np.mean(phi)),
+                    float(np.max(phi) - np.min(phi)),
+                    float(np.std(phi)),
+                    float(np.mean(np.diff(np.sort(phi)[::-1][:3])) if self.n_fine >= 3 else 0.0)]
+            self.know.observe_gvf(phi, cums, phi)
+        # 周期性重建 world model + 重新发现 option
+        if (self.know is not None and len(self.trans) >= self.min_transitions
+                and self.refresh_count < len(self.trans) // max(1, self.refresh_every)):
+            self.refresh()
+            self.refresh_count += 1
+
+    def refresh(self):
+        """把转移日志灌进 dynamics ensemble -> 标定门控 -> 重新发现 options。"""
+        if self.know is None:
+            return
+        try:
+            X = np.array([np.append(s, a) for s, a, _ in self.trans])
+            Y = np.array([sp for _, _, sp in self.trans])
+            self.know.fit_dynamics(X, Y)
+            from hibs_lnn.option_manager import OptionManager
+            om = OptionManager(self.know.dynamics_model, self.know.uncertainty,
+                               max_len=self.max_opt_len, seed=self.seed)
+            states = np.array([s for s, _, _ in self.trans])
+            acts = np.array([a for _, a, _ in self.trans])
+            # ★ 表格模型下按**真实状态**建图 (不是聚类中心)
+            n_uniq = len(np.unique(np.round(states, 6), axis=0))
+            nreg = (min(self.n_regions_opt, max(4, n_uniq))
+                    if self.dyn_model_kind == "tabular"
+                    else min(self.n_regions, max(2, len(states) // 10)))
+            if self.use_subgoals:
+                om.discover_subgoals(states, acts, n_regions=nreg)
+            else:
+                om.discover(states, acts, n_regions=nreg)
+            self.know.register_options(om)
+        except Exception as e:      # 知识重建失败不该拖垮主实验
+            print("!! knowledge refresh 失败:", e, flush=True)
+
+    # ── 诊断 ───────────────────────────────────────────────────────
+    def stats(self):
+        s = self.base.proposer_stats() if hasattr(self.base, "proposer_stats") else {}
+        # ★ 真步长统计: 取自 base 的最近一条 trace (RLProposer 在那里记录 α)
+        _tr = getattr(self.base, "trace", None) or []
+        if _tr:
+            s["alpha_mean"] = _tr[-1].get("alpha_mean")
+            s["alpha_std"] = _tr[-1].get("alpha_std")
+            s["h_norm"] = _tr[-1].get("h_norm")
+        if self.know is None:
+            s.update({"n_trans": len(self.trans), "refreshes": 0, "n_options": 0,
+                      "option_steps": self.option_steps,
+            "opt_frac": self.opt_frac,
+            "opt_mode": self.opt_mode,
+            "dyn_model": self.dyn_model_kind,
+            "use_subgoals": self.use_subgoals,
+            "replan_steps": self.replan_steps,
+            "state_scale": float(getattr(self, "_state_scale", 0.0)),
+            "eps_eff": float(self._eps_eff()),
+            "override_count": self.override_count,
+            "term_reasons": dict(self.term_reasons),
+            "option_starts": self.option_starts, "untrusted_picks": self.untrusted_picks,
+                      "coverage_total": 0, "tau_U": None, "gvf_steps": [], "alpha_std": 0.0})
+            return s
+        s.update({
+            "n_trans": len(self.trans),
+            "refreshes": self.refresh_count,
+            "n_options": len(self.know.skills()),
+            "option_steps": self.option_steps,
+            "option_starts": self.option_starts,
+            "opt_frac": self.opt_frac,
+            "opt_mode": self.opt_mode,
+            "dyn_model": self.dyn_model_kind,
+            "use_subgoals": self.use_subgoals,
+            "replan_steps": self.replan_steps,
+            "override_count": self.override_count,
+            "gate_blocked": self.gate_blocked, "no_finite_unc": self.no_finite_unc,
+            "start_blocked": self.start_blocked,
+            "goal_none": self.goal_none,
+            "term_reasons": dict(self.term_reasons),
+            "untrusted_picks": self.untrusted_picks,
+            "coverage_total": int(self.know.coverage.n_total),
+            "tau_U": self.know.uncertainty.tau_U,
+            "gvf_steps": [g.steps for g in self.know.predictions.gvfs],
+            # ★ 不要放在 "alpha_std" 这个键上 —— 它会**覆盖** base.proposer_stats()
+            #   里真正的步长统计。早先版本就是这么写的, 结果 JSON 里几个不同算法
+            #   (idbd / idbd-raw / cidbd) 的 alpha_std 全是同一个**未被更新**的死对象
+            #   的值 (2.78e-17), 看起来像"算法不生效"。真正在用的 α 在 base.trace。
+            "know_alpha_std": float(self.know.plasticity.alpha.std()),
+        })
+        return s
+
+    def stats_extra(self):
+        """主实验落盘用。"""
+        if self.know is None:
+            return {"knowledge": {"n_options": 0, "coverage": {}, "plasticity": {},
+                                  "tau_U": None, "options": []},
+                    "oak": {"use_options": self.use_options, "use_gate": self.use_gate,
+                            "n_trans": len(self.trans), "refreshes": 0,
+                            "option_steps": self.option_steps,
+            "option_starts": self.option_starts,
+                            "untrusted_picks": self.untrusted_picks}}
+        d = self.know.describe()
+        return {"knowledge": {
+            "n_options": d["Level4_abstraction"]["n_options"],
+            "coverage": d["meta_coverage"],
+            "plasticity": d["meta_plasticity"],
+            "tau_U": d["meta_uncertainty"]["tau_U"],
+            "options": d["Level4_abstraction"]["options"],
+        }, "oak": {"use_options": self.use_options, "use_gate": self.use_gate,
+                   "n_trans": len(self.trans), "refreshes": self.refresh_count,
+                   "option_steps": self.option_steps,
+            "option_starts": self.option_starts,
+                   "untrusted_picks": self.untrusted_picks}}

hibs_lnn/option_manager.py

@@ -0,0 +1,502 @@
+"""option_manager.py — Options / 时间抽象 (OaK 的 O)。
+
+## Option 的三要素 (用户定义)
+
+    o = (I_o, π_o, β_o)
+
+    I_o  initiation set    什么时候可以启动这个 option
+    π_o  option policy     启动后怎么行动 (这里是**一串子动作**, 不是单个动作)
+    β_o  termination       什么时候结束 —— **学习式** P(terminate | s, o)
+
+## ★ 不从 reward 定义 option, 而从「可预测的状态转移结构」发现
+
+用户: *"Option 不一定首先由 reward 定义, 而可以由可预测的状态转移结构产生。"*
+
+我们已有 `TransitionEnsemble` (带分歧 U_T)。发现流程:
+
+    1. 用过渡模型把能力状态 s 映射到预测状态 ŝ, 聚类成 region
+    2. 建 region 转移图: 边 (A --u--> B) 的**可预测性** = 1/(1+U_T)
+    3. 在图上找多步可靠路径 A → C (要求每一步 U_T < τ_U)
+    4. 每条这样的路径 = 一个 option: π_o = 该动作序列, I_o = A 区域
+    5. β_o 用真实观测学: P(到达目标区域 | s, o)  —— 学习式终止, 不是固定阈值
+
+**为什么这比手工写 "Option1=加磁通 / Option2=稳定" 强**: 手工定义只编码了人类先验;
+从转移结构发现是在编码 **"哪些行为的后果我可以可靠预测"** —— 那才是可利用的时间抽象。
+
+## 与 planning 的衔接
+
+高层: s_t → 选 option → **rollout transition model** → 选动作序列
+这正是 OaK 的 abstraction → transition model → planning 路线。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class Option:
+    """o = (I_o, π_o, β_o)。"""
+
+    def __init__(self, oid, actions, start_center, goal_center, uncs=None,
+                 regions=None, start_region=None, goal_region=None):
+        self.oid = int(oid)
+        self.actions = list(actions)        # π_o: 动作序列 (时间抽象的核心)
+        self.start_center = np.asarray(start_center, dtype=float)   # I_o 的中心
+        self.goal_center = np.asarray(goal_center, dtype=float)     # 目标区域
+        self.uncs = list(uncs or [])        # 逐步不确定性 (用于可信度)
+        self.visits = 0
+        self.success = 0
+        # β_o 的线性参数: P(terminate | s, o) = sigmoid(w·[s, goal, unc])
+        self.w_beta = np.zeros(3 * len(self.goal_center) + 1)
+        # ── ★ 区域归属 (无阈值的终止判据) ────────────────────────────
+        #   旧判据 `‖s − goal_center‖ < eps` 在**离散状态空间**里会退化:
+        #   KeyDoor 的 vec() 是 one-hot(pos) ⊕ has_key ⊕ door_open, 两个不同
+        #   位置的距离是 √2≈1.414、仅一个 bit 不同的是 1.0, 而
+        #   `init_radius = max(0.5, median(NN)·0.75) = 0.754` **只接受精确到达**
+        #   → 实测 β_o 因达成而触发的比例 **0/2737**, 全部靠预算耗尽退出。
+        #   正确判据: "s 是否落在该 option 的目标**区域**里" —— 用 k-means 的
+        #   Voronoi 归属 (argmin ‖s − centers‖) 判定, 无阈值、覆盖全空间。
+        self.regions = None if regions is None else np.asarray(regions, dtype=float)
+        self.start_region = start_region
+        self.goal_region = goal_region
+
+    # ── ★ 区域归属 ──
+    def region_of(self, s):
+        """s 落在哪个区域 (k-means Voronoi 归属)。regions 未设时返回 None。"""
+        if self.regions is None or len(self.regions) == 0:
+            return None
+        d = np.linalg.norm(self.regions - np.asarray(s, dtype=float)[None, :], axis=1)
+        return int(np.argmin(d))
+
+    def in_goal_region(self, s):
+        """β_o 的**主判据**: s 是否已进入目标区域。"""
+        if self.goal_region is None:
+            return False
+        return self.region_of(s) == self.goal_region
+
+    # ── I_o: 启动条件 (到起点的距离在半径内) ──
+    def initiable(self, s, radius=0.5):
+        # ★ 优先用区域归属 (与 in_goal_region 对称, 无阈值退化问题);
+        #   未设区域时退回距离判据 (保留旧行为)。
+        if self.start_region is not None:
+            r = self.region_of(s)
+            if r is not None and r == self.start_region:
+                return True
+        return float(np.linalg.norm(np.asarray(s) - self.start_center)) <= radius
+
+    # ── β_o: **学习式终止概率** ──
+    def _beta_feat(self, s, unc=0.0):
+        s = np.asarray(s, dtype=float)
+        g = self.goal_center
+        return np.concatenate([s, g - s, [unc, 1.0]])
+
+    def beta_prob(self, s, unc=0.0):
+        z = float(self.w_beta @ self._beta_feat(s, unc))
+        return 1.0 / (1.0 + np.exp(-np.clip(z, -30, 30)))
+
+    def learn_termination(self, samples, lr=0.05, epochs=200):
+        """从真实观测学 β_o。samples: [(s, unc, terminated_bool), ...]
+
+        这才是「学习式 termination」—— 而不是 `if error < threshold: stop()`。
+        """
+        if not samples:
+            return
+        F = np.array([self._beta_feat(s, u) for s, u, _ in samples])
+        y = np.array([1.0 if t else 0.0 for _, _, t in samples])
+        for _ in range(epochs):
+            p = 1.0 / (1.0 + np.exp(-np.clip(F @ self.w_beta, -30, 30)))
+            grad = F.T @ (p - y) / len(y)
+            self.w_beta -= lr * grad
+        return self
+
+    def should_terminate(self, s, unc=0.0, thresh=0.5):
+        return self.beta_prob(s, unc) >= thresh
+
+    # ── ★ 闭环保守派接口 (用户 2026-09-14 指导) ──────────────────────
+    def goal_distance(self, s):
+        """到子目标的距离 —— 这是 β_o 与 π_o 共用的量。"""
+        return float(np.linalg.norm(np.asarray(s, dtype=float) - self.goal_center))
+
+    def terminated(self, s, unc=0.0, eps=0.05, tau_U=None, stall=0.0):
+        """自适应终止 β_o(s): 任一条件命中即退出。
+
+            β_o(s) = 1  若  ⓪ 进入**目标区域** in_goal_region(s)   ← 主判据
+                            ① 目标达成  ||s - g|| < eps
+                            ② 不确定性过高 U_T > tau_U   (风险升高)
+                            ③ 停滞       本轮进展 < stall
+            β_o(s) = 0  否则
+
+        ★ ⓪ 是本轮新增的主判据。旧判据仅 ①(距离 < eps), 在**离散或高维**
+          状态空间里会退化 —— 实测 (KeyDoor, `vec()` 为 one-hot ⊕ 2 bit):
+          距离离散化为 {0, 1, 1.732, 2}, 而 eps=0.754 只接受精确到达
+          → 2737 次执行中因「达成」触发 **0 次**, 全部靠预算耗尽退出。
+          区域归属 (k-means Voronoi) 无阈值、覆盖全空间, 故设为主判据;
+          ① 保留为兜底 (regions 未设时行为不变)。
+
+        ★ 固定长度执行是 open-loop 的病根: "即使当前情况已经不适合这个 option,
+          它可能还在继续执行"。这里让 option **每步都可以退出**。
+        """
+        if self.in_goal_region(s):
+            return True, "goal_reached"
+        if self.goal_distance(s) < eps:
+            return True, "goal_reached"
+        if tau_U is not None and np.isfinite(unc) and unc > tau_U:
+            return True, "high_uncertainty"
+        if stall > 0 and getattr(self, "_last_d", None) is not None:
+            if self._last_d - self.goal_distance(s) < stall:
+                return True, "stalled"
+        return False, ""
+
+    def progress(self, s_from, s_to):
+        """朝目标前进多少 (正 = 更近)。"""
+        return self.goal_distance(s_from) - self.goal_distance(s_to)
+
+    def stats(self):
+        rate = (self.success / self.visits) if self.visits else 0.0
+        # ★ 必须暴露 actions: 多步**动作序列**正是 option 的全部意义
+        #   (时间抽象 = s -> a1..ak)。早先只返回 `len`, 日志里全是 actions=None,
+        #   等于把 option 最有信息量的部分丢了。
+        return {"oid": self.oid, "len": len(self.actions),
+                "actions": [int(x) for x in self.actions],
+                "start": np.round(self.start_center, 3).tolist(),
+                "goal": np.round(self.goal_center, 3).tolist(),
+                "visits": self.visits, "success_rate": round(rate, 3),
+                "mean_unc": round(float(np.mean(self.uncs)) if self.uncs else 0.0, 5)}
+
+
+class OptionManager:
+    """从可预测的状态转移结构中**发现** options。"""
+
+    def __init__(self, ensemble, gate, max_len=4, min_edges=3, seed=0):
+        self.T = ensemble
+        self.gate = gate
+        self.max_len = int(max_len)
+        # 启动集半径: 由 discover 按区域尺度自适应推断
+        self.init_radius = 0.75
+        self.min_edges = int(min_edges)
+        self.options = []
+        self.regions = None          # region 中心
+        self.graph = {}              # (region, action) -> (next_region, unc)
+        self.rng = np.random.default_rng(seed)
+
+    # ───────── 发现 ─────────
+    def discover(self, states, actions, n_regions=4, tau_U=None):
+        """输入: 观测到的 (状态, 动作) 对。输出: options 列表。
+
+        states : (N, dim_x) 能力状态
+        actions: (N,) 当时训练了哪个域
+        """
+        S = np.asarray(states, dtype=float)
+        A = np.asarray(actions, dtype=int)
+        n_dom = int(A.max()) + 1 if len(A) else 1
+        visits = np.zeros(n_dom)
+        for a in A:
+            visits[a] += 1
+
+        # 1) 聚类成 region (用最简单可复现的 k-means, 避免引入依赖)
+        self.regions, assign = self._kmeans(S, n_regions)
+
+        # 2) 建转移图: 对每个 (region, action) 预测落点与不确定性
+        self.graph = {}
+        for r in range(n_regions):
+            for u in range(n_dom):
+                c = self.regions[r]
+                s_next, unc = self.T.predict(c, u, visits)   # 已是绝对状态
+                nxt = self._nearest_region(s_next)
+                self.graph[(r, u)] = (nxt, unc)
+
+        # 3) 定 τ_U (若未给) —— 用图上所有边的分歧分位
+        uncs = [self.graph[k][1] for k in self.graph]
+        uncs = [u for u in uncs if np.isfinite(u)]
+        if tau_U is None:
+            # 用**中位数**而非高分位: 我们要的是「一半的可预测边」, 不是几乎全部。
+            tau_U = float(np.median(uncs)) if uncs else float("inf")
+        self.tau_U = tau_U
+
+        # 4) 找可靠路径 (每步 unc < tau_U 且确实前进了) = options
+        S = np.asarray(states, dtype=float)
+        self.options = []
+        oid = 0
+        for r0 in range(n_regions):
+            for L in range(2, self.max_len + 1):
+                for path in self._reliable_paths(r0, L, tau_U):
+                    acts = path
+                    goal_r = self._walk(r0, acts)
+                    if goal_r == r0:
+                        continue                      # 没前进, 不是 option
+                    uncs_p = [self.graph[(self._walk(r0, acts[:i]), acts[i])][1]
+                              for i in range(len(acts))]
+                    # ★ 起点/目标吸附到**真实观测状态** (质心可能够不着)
+                    #   + 带上区域归属 (无阈值的 β_o 判据)
+                    self.options.append(Option(
+                        oid, acts, self._snap(S, self.regions[r0]),
+                        self._snap(S, self.regions[goal_r]), uncs_p,
+                        regions=self.regions, start_region=r0, goal_region=goal_r))
+                    oid += 1
+        # 去重 (同起点同目标保留最短的)
+        best = {}
+        for o in self.options:
+            k = (tuple(np.round(o.start_center, 3)), tuple(np.round(o.goal_center, 3)))
+            if k not in best or len(o.actions) < len(best[k].actions):
+                best[k] = o
+        self.options = list(best.values())
+        for i, o in enumerate(self.options):
+            o.oid = i
+        # 自适应启动集半径: 最近邻区域距离中位数的 0.75 倍 (与状态空间尺度匹配)
+        if len(self.regions) > 1:
+            _D = np.linalg.norm(self.regions[:, None, :] - self.regions[None, :, :], axis=-1)
+            np.fill_diagonal(_D, np.inf)
+            self.init_radius = float(max(0.5, np.median(_D.min(axis=1)) * 0.75))
+        return self.options
+
+    def _reliable_paths(self, r0, L, tau_U):
+        """长度 L 的路径, 每步 unc < tau_U。用 BFS 枚举 (空间很小)。"""
+        out = []
+        n_dom = max(u for _, u in self.graph) + 1 if self.graph else 1
+        frontier = [(r0, [])]
+        for depth in range(L):
+            nxt = []
+            for r, seq in frontier:
+                for u in range(n_dom):
+                    e = self.graph.get((r, u))
+                    if e is None or not np.isfinite(e[1]) or e[1] > tau_U + 1e-12:
+                        # ★ 用 `>` 而不是 `>=`: 确定性转移 (unc=0) 是**最可靠**的,
+                        #   在 tau_U 也等于 0 时绝不能被筛掉 —— 否则"完全可预测的边"
+                        #   全军覆没。实测: 计数式表格模型给出 tau_U=0.0, 旧的 `>=`
+                        #   使 OptionManager 在结构清晰的 MDP 上发现 0 个 option。
+                        continue
+                    if e[0] == r:
+                        continue                      # 不前进的边不走
+                    nxt.append((e[0], seq + [u]))
+            if depth == L - 1:
+                out.extend(seq for _, seq in nxt)
+            frontier = nxt
+            if not frontier:
+                break
+        return out
+
+    def _walk(self, r0, acts):
+        r = r0
+        for u in acts:
+            e = self.graph.get((r, u))
+            if e is None:
+                return r
+            r = e[0]
+        return r
+
+    def _nearest_region(self, s):
+        d = np.linalg.norm(self.regions - np.asarray(s), axis=1)
+        return int(np.argmin(d))
+
+    @staticmethod
+    def _kmeans(X, k, iters=50, seed=0):
+        rng = np.random.default_rng(seed)
+        C = X[rng.choice(len(X), size=min(k, len(X)), replace=False)].copy()
+        a = np.zeros(len(X), dtype=int)          # 防 iters=0 时未绑定
+        for _ in range(iters):
+            d = np.linalg.norm(X[:, None, :] - C[None, :, :], axis=2)
+            a = np.argmin(d, axis=1)
+            for j in range(len(C)):
+                if (a == j).any():
+                    C[j] = X[a == j].mean(0)
+        return C, a
+
+    # ───────── 高层选择 (planning 入口) ─────────
+    # ── ★ 子目标驱动的发现 (用户 2026-09-14 指导的 Option 形式) ──────
+    def discover_subgoals(self, states, actions, n_regions=8, tgt=0.0,
+                          min_path=2, max_path=5):
+        """按 `Option=(I_o, g_o, π_o, β_o)` **目标导向地**发现 option。
+
+        ## 为什么需要它 (实测动机)
+
+        原来的 `discover()` 找的是「**任意**可靠的多步路径」:
+          ① 没有目标导向 —— 终点是不是"有意义的地方"不管
+          ② 路径上**每条**边都要 unc < tau_U(中位数) -> 长度 4 的存活率 ~0.5^4=6%
+          ③ 要求长度**恰好** = L
+        结果: 在一个**有明显的"拿钥匙→开门"技能链**的 MDP 上, 即使图里有
+        50 条前进边, 也只发现 0~1 个 option。**这是实现的问题, 不是环境的。**
+
+        ## 正确做法: 先找**子目标**, 再找通往它的路
+
+          1. 建区域转移图 (同 discover)
+          2. 算每个区域在图上的**介数中心性** —— 高介数 = 通往别处必须经过的
+             咽喉 (bottleneck)。这正是"拿钥匙""开门"这类子目标的特征。
+          3. 每个 bottleneck 区域 b 成为一个子目标:
+               g_o = centers[b]
+               π_o = 从各起点区域到 b 的**最短动作序列** (在图上 BFS)
+               I_o = 那些起点区域
+          4. 允许多条不同长度的路径 (min_path..max_path), 不再要求恰好 = L
+        """
+        self.regions, _ = self._kmeans(np.asarray(states, dtype=float), n_regions)
+        n_dom = self.T.n_dom
+        visits = np.bincount(np.asarray(actions, dtype=int), minlength=n_dom).astype(float)
+
+        # 1. 区域转移图
+        self.graph = {}
+        for r in range(n_regions):
+            for u in range(n_dom):
+                s_next, unc = self.T.predict(self.regions[r], u, visits)
+                self.graph[(r, u)] = (self._nearest_region(s_next), unc)
+
+        uncs = np.array([v[1] for v in self.graph.values() if np.isfinite(v[1])])
+        self.tau_U = float(np.median(uncs)) if len(uncs) else float("inf")
+
+        # 2. 邻接 (每个区域的出边, 按 unc 从小到大)
+        adj = {r: [] for r in range(n_regions)}
+        for (r, u), (nxt, unc) in self.graph.items():
+            if nxt != r and np.isfinite(unc):
+                adj[r].append((nxt, u, unc))
+        for r in adj:
+            adj[r].sort(key=lambda t: t[2])
+
+        # 3. ★ 割点/桥找咽喉 —— **不用介数中心性**
+        #    实测证据 (选项验证技能 FM-17, 四房间 gridworld): 介数最高的格
+        #    **不是**走廊格。介数衡量的是"最短路径经过次数", 而走廊的语义是
+        #    "去掉它图就断开" —— 那是**割点(articulation point)**。
+        #    用错了统计量 -> 子目标选在无关处 -> π_o 朝一个无意义的地点走。
+        aps = self._articulation_points(adj, n_regions)
+        if not aps:
+            # 图无割点 (如完全连通): 退回到"通往最多区域"的节点,
+            # 这比介数中心性更贴近"咽喉"的意图, 且不退化成"选不到子目标"
+            aps = set(np.argsort(-np.array([len(adj[r]) for r in range(n_regions)]))[:2].tolist())
+
+        # 4. 每个割点区域 = 一个子目标; 用 BFS 找通往它的动作序列
+        S = np.asarray(states, dtype=float)
+        order_ap = sorted(aps)
+        self.options = []
+        oid = 0
+        for b in order_ap:
+            for src in range(n_regions):
+                if src == b:
+                    continue
+                seq = self._bfs_action_path(adj, src, b, max_path)
+                if seq is None or len(seq) < min_path:
+                    continue
+                uncs_seq = [self.graph[(src, seq[0])][1]]
+                # ★ 目标/起点必须是**真实观测到的状态**, 不能是 k-means 质心。
+                #   质心是几个状态的软平均, 可能不对应任何真实状态 ->
+                #   以它为目标的 π_o 会朝一个"够不着"的点走。
+                #   实测: macro 宏执行的成功率只有 14.4% (质心目标下),
+                #   即 85.6% 的 option 执行**到不了自己的目标**。
+                self.options.append(Option(oid, seq, self._snap(S, self.regions[src]),
+                                           self._snap(S, self.regions[b]), uncs_seq,
+                                           regions=self.regions,
+                                           start_region=src, goal_region=b))
+                oid += 1
+                if oid >= 40:
+                    break
+            if oid >= 40:
+                break
+        # 自适应启动集半径: 最近邻区域距离中位数的 0.75 倍 (与状态空间尺度匹配)
+        if len(self.regions) > 1:
+            _D = np.linalg.norm(self.regions[:, None, :] - self.regions[None, :, :], axis=-1)
+            np.fill_diagonal(_D, np.inf)
+            self.init_radius = float(max(0.5, np.median(_D.min(axis=1)) * 0.75))
+        return self.options
+
+    @staticmethod
+    def _snap(S, center):
+        """把 k-means 质心**吸附到最近的真实观测状态**。
+
+        ★ 为什么必须做: 质心是若干状态的软平均, 可能不对应任何真实状态。
+          以质心为目标 -> π_o 朝一个"够不着"的点走 -> β_o 永不因达成而触发。
+          实测 (KeyDoor macro 宏执行): 成功率仅 14.4%, 即 85.6% 的 option
+          执行到不了自己的目标。
+        """
+        if S is None or len(S) == 0:
+            return np.asarray(center, dtype=float)
+        d = np.linalg.norm(S - np.asarray(center, dtype=float)[None, :], axis=1)
+        return S[int(np.argmin(d))].astype(float)
+
+    @staticmethod
+    def _articulation_points(adj, n):
+        """Tarjan 割点检测 (**无向化**后的区域图)。
+
+        ★ 为什么不用介数中心性: 走廊/咽喉的语义是"去掉它图就断开",
+          那是割点。介数中心性衡量的是"最短路径经过次数", 二者不等价 ——
+          实测 (选项验证技能 FM-17, 四房间 gridworld): 介数最高的格
+          **不是**走廊格。
+        """
+        und = {r: set() for r in range(n)}
+        for r, outs in adj.items():
+            for e in outs:
+                nxt = e[0]
+                und[r].add(nxt)
+                und[nxt].add(r)
+
+        disc, low, parent = {}, {}, {}
+        aps = set()
+        timer = [0]
+
+        def dfs(u):
+            disc[u] = low[u] = timer[0]
+            timer[0] += 1
+            children = 0
+            for v in und.get(u, ()):
+                if v not in disc:
+                    parent[v] = u
+                    children += 1
+                    dfs(v)
+                    low[u] = min(low[u], low[v])
+                    if u not in parent and children > 1:
+                        aps.add(u)                    # 根: 多棵子树才是割点
+                    if u in parent and low[v] >= disc[u]:
+                        aps.add(u)
+                elif v != parent.get(u):
+                    low[u] = min(low[u], disc[v])
+
+        for s in range(n):
+            if s not in disc:
+                dfs(s)
+        return aps
+
+    @staticmethod
+    def _bfs_action_path(adj, src, dst, max_len):
+        """在区域图上 BFS 出 src->dst 的**动作序列** (优先低不确定性边)。"""
+        from collections import deque
+        q = deque([(src, [])])
+        seen = {src}
+        while q:
+            cur, path = q.popleft()
+            if len(path) > max_len:
+                continue
+            if cur == dst and path:
+                return path
+            for (nxt, u, _un) in adj[cur]:
+                if nxt in seen:
+                    continue
+                seen.add(nxt)
+                q.append((nxt, path + [int(u)]))
+        return None
+
+    def select(self, s, goal=None, exclude_unc=True, radius=None):
+        """选一个 option: 优先「起点匹配 + 目标最接近 goal + 成功率高」。
+
+        goal=None 时选成功率高且不确定性低的那个。
+        """
+        cands = []
+        # ★ 半径必须与状态空间尺度匹配。one-hot 状态空间里**两个不同状态**的
+        #   L2 距离是 √2 ≈ 1.41, 固定 0.75 会让启动集几乎永不满足
+        #   (实测: 主回路里 option 一次都没被选用, primitive 与 option 臂
+        #    给出**逐位相同**的数字)。
+        _r = radius if radius is not None else self.init_radius
+        for o in self.options:
+            if not o.initiable(s, radius=_r):
+                continue
+            # ★ 同 _reliable_paths 的坑: 用 `>` 而不是 `>=`。
+            #   确定性模型下 tau_U=0 且 uncs=[0.0], `>=` 会把**全部** option
+            #   过滤掉 -> 主回路里 option 一次都没被选用 -> primitive 与 option 臂
+            #   给出逐位相同的数字。
+            if exclude_unc and o.uncs and max(o.uncs) > getattr(self, "tau_U", np.inf) + 1e-12:
+                continue
+            rate = (o.success / o.visits) if o.visits else 0.5     # 先验乐观
+            score = rate - (float(np.mean(o.uncs)) if o.uncs else 0.0)
+            if goal is not None:
+                score -= float(np.linalg.norm(o.goal_center - np.asarray(goal)))
+            cands.append((score, o))
+        return max(cands, key=lambda t: t[0])[1] if cands else None
+
+    def stats(self):
+        return {"n_options": len(self.options),
+                "tau_U": round(float(getattr(self, "tau_U", float("nan"))), 6),
+                "n_edges": len(self.graph),
+                "options": [o.stats() for o in self.options[:6]]}

hibs_lnn/pln_head.py

@@ -0,0 +1,264 @@
+"""PLN 头 (lm1 V31_PLN 的可移植移植版) + OML 双循环原语。
+
+来源: tests/run_v31_meta_learning.py:114 V31_PLN / head_forward / per_feature_step
+      tests/run_lm3_bpe.py:193  oml2 双循环协议
+
+lm1 原设计(见 run_lm1_production.py 文件头):
+  SSM (RLN) + OML 双层 (内循环 PLN 适应 + 外循环合并) + 价值提议器
+
+本模块只搬 RLN 之外的两件事:
+  1. PLN: 小 MLP 头 + **per-feature 步长** (Meta-SGD / IDBD), 内循环只应用不修改 β
+  2. 双循环协议: 内循环克隆头适应 support → 外循环用 query loss 更新全模型
+
+与 lm4 的结合点: lm4 原本是 `head = nn.Linear(d_model, n_classes)` 的**单循环**训练。
+把 head 换成 PLN 并改用双循环, 即 lm1 的架构。
+"""
+import math
+from typing import List
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from hibs_lnn.swifttd_head import SwiftTDHead
+
+
+class PLNHead(nn.Module):
+    """预测学习网络 (Prediction Learning Network).
+
+    结构与 V31_PLN 一致: Linear(in, d) → Tanh → Linear(d, out)
+    差别: 输入是连续特征聚合 (lm4) 而非离散 hidden, 故 input_dim 可独立指定。
+
+    step_beta 是 **meta-parameter**: 外循环学它, 内循环只用它做
+    `W ← W - exp(beta) * grad`. 这样内循环有 per-feature 自适应步长,
+    而不是所有参数共享一个标量 lr。
+    """
+
+    def __init__(self, input_dim, d_model, n_classes, inner_lr=0.1):
+        super().__init__()
+        self.input_dim = input_dim
+        self.d_model = d_model
+        self.n_classes = n_classes
+        self.predictor = nn.Sequential(
+            nn.Linear(input_dim, d_model),
+            nn.Tanh(),
+            nn.Linear(d_model, n_classes),
+        )
+        # log 空间初始化 → exp(beta) = inner_lr
+        self.step_beta = nn.Parameter(
+            torch.full((self._n_params(),), math.log(inner_lr)))
+
+    # ---------- 参数工具 ----------
+    def _n_params(self) -> int:
+        return sum(p.numel() for p in self.predictor.parameters())
+
+    def clone_params(self) -> List[torch.Tensor]:
+        """克隆可适应参数 (保留到共享参数的图, 供外循环反传)。"""
+        lin0 = self.predictor[0]
+        lin2 = self.predictor[2]
+        return [lin0.weight.clone(), lin0.bias.clone(),
+                lin2.weight.clone(), lin2.bias.clone()]
+
+    def per_feature_step(self, W: List[torch.Tensor],
+                         grads: List[torch.Tensor]) -> List[torch.Tensor]:
+        """Meta-SGD 内循环更新: 逐参数自适应步长 (与 V31_PLN.per_feature_step 同式)。"""
+        beta = self.step_beta
+        new_W, off = [], 0
+        for w, g in zip(W, grads):
+            n = w.numel()
+            b = beta[off:off + n].view_as(w)
+            alpha = b.exp().clamp(max=1.0)
+            new_W.append(w - alpha * g)
+            off += n
+        return new_W
+
+    def load_cloned(self, W: List[torch.Tensor]) -> None:
+        """把克隆参数写回本体 (仅评估/合并用)。"""
+        with torch.no_grad():
+            self.predictor[0].weight.copy_(W[0])
+            self.predictor[0].bias.copy_(W[1])
+            self.predictor[2].weight.copy_(W[2])
+            self.predictor[2].bias.copy_(W[3])
+
+    # ---------- 前向 ----------
+    @staticmethod
+    def fwd_with(W: List[torch.Tensor], h: torch.Tensor) -> torch.Tensor:
+        """用给定的参数集做前向 (functional, 支持内循环克隆参数)。"""
+        w1, b1, w2, b2 = W
+        x = torch.tanh(h @ w1.t() + b1)
+        return x @ w2.t() + b2
+
+    def forward(self, h: torch.Tensor) -> torch.Tensor:
+        return self.predictor(h)
+
+
+def inner_adapt(head: PLNHead, h_sup: torch.Tensor, y_sup: torch.Tensor,
+                K: int = 2, per_feature: bool = True):
+    """内循环: 在 support 上适应**克隆的**头参数, 返回适应后的 W。
+
+    per_feature=True  → 用 head.step_beta (lm1 的 Meta-SGD 步长)
+    per_feature=False → 固定标量 lr (lm3 oml2 的做法, lr=0.1)
+
+    注意: 整个过程对 head.predictor 的参数**保留梯度图** (没有 detach),
+    这样外循环的 query loss 反传时, 梯度会经过内循环更新流回 meta-parameters。
+    """
+    W = head.clone_params()
+    for _ in range(K):
+        logits = PLNHead.fwd_with(W, h_sup)
+        loss = F.cross_entropy(logits, y_sup)
+        grads = torch.autograd.grad(loss, W, create_graph=True)
+        if per_feature:
+            W = head.per_feature_step(W, grads)
+        else:
+            W = [w - 0.1 * g for w, g in zip(W, grads)]
+    return W
+
+
+def oml_step(model, head: PLNHead, enc, h_sup, y_sup, h_qry, y_qry,
+             opt_outer, K: int = 2, per_feature: bool = True,
+             consolidate: bool = True, reptile_lr: float = 0.0):
+    """一次 OML 双循环步。
+
+      内循环: 克隆头在 support 上适应 K 步 (慢参数冻结)
+      外循环: fast head 在 query 上的 loss → 反传更新 RLN + PLN meta 参数
+      合并:   把适应后的 fast head 写回本体 (OML 权重整合)
+      Reptile: 再把本体 init 朝适应后权重拉一步 (lm1 meta_step 的 init 平均)
+               init ← init + reptile_lr * (W_adapted - init)
+
+    返回 (query_loss, support_loss) 标量。
+    """
+    # --- 内循环 (RLN 冻结, 只适应头; 梯度图保留供外循环用) ---
+    W = inner_adapt(head, h_sup, y_sup, K=K, per_feature=per_feature)
+
+    # --- 外循环: query loss 反传全模型 ---
+    opt_outer.zero_grad()
+    logits_q = PLNHead.fwd_with(W, h_qry)
+    loss_q = F.cross_entropy(logits_q, y_qry)
+    loss_q.backward()
+    # 二阶 (create_graph) 梯度必须裁剪 —— lm1 meta_step 的 clip_grad_norm_(1.0)。
+    # 不裁剪时外循环会把编码器打爆, 表现为"当前域刚学会就整体归零"。
+    torch.nn.utils.clip_grad_norm_(
+        [p for p in model.parameters() if p.requires_grad], 1.0)
+    opt_outer.step()
+
+    # --- OML 权重整合: 适应后的头合并回本体 ---
+    if consolidate:
+        with torch.no_grad():
+            head.load_cloned([w.detach() for w in W])
+            # 合并后这些是叶子参数, 外循环下一步能继续更新
+            head.predictor[0].weight.requires_grad_(True)
+            head.predictor[0].bias.requires_grad_(True)
+            head.predictor[2].weight.requires_grad_(True)
+            head.predictor[2].bias.requires_grad_(True)
+
+    # --- Reptile init 平均 (lm1 V31.2 meta_step 的做法) ---
+    if reptile_lr > 0.0:
+        with torch.no_grad():
+            for p, w in zip(head.predictor.parameters(), W):
+                p.add_(reptile_lr * (w.detach() - p))
+
+    with torch.no_grad():
+        loss_s = F.cross_entropy(PLNHead.fwd_with(
+            [w.detach() for w in W], h_sup), y_sup).item()
+    return loss_q.item(), loss_s
+
+
+# ============================================================
+# SwiftTD 头 (lm1 hibs_lnn/swifttd_head.py 的适配器)
+# ============================================================
+class SwiftTDAdapter(nn.Module):
+    """把 lm1 的 SwiftTDHead 适配成分类头, 接口与 PLNHead 对齐。
+
+    SwiftTD 与 PLN 的本质差异:
+      PLN     — 内循环用 Meta-SGD 梯度, step_beta 是 **meta 参数**, 外循环可学
+      SwiftTD — 内循环用**局部规则** (δ·φ), 每参数步长 θ 由 IDBD 在线自适应,
+                外循环不需要学它 (θ 靠 bound/decay 自己调节)
+
+    两者都提供 step_graph (可微版本), 所以都能直接插进 OML 双循环。
+    """
+
+    def __init__(self, input_dim, n_classes, beta_init=0.01, kappa=0.05,
+                 eta=0.1, eps=0.99, tau_norm=None):
+        super().__init__()
+        self.input_dim = input_dim
+        self.n_classes = n_classes
+        self.head = SwiftTDHead(d_model=input_dim, world_vocab=n_classes,
+                                n_resp=1, input_dim=input_dim,
+                                beta_init=beta_init, kappa=kappa,
+                                eta=eta, eps=eps, tau_norm=tau_norm)
+        s = 1.0 / math.sqrt(input_dim)
+        self.w1 = nn.Parameter(torch.randn(input_dim, input_dim) * s)
+        self.b1 = nn.Parameter(torch.zeros(input_dim))
+        self.w2 = nn.Parameter(torch.randn(n_classes, input_dim) * s)
+        self.b2 = nn.Parameter(torch.zeros(n_classes))
+
+    def to(self, *args, **kwargs):
+        super().to(*args, **kwargs)
+        self.head.to(self.w1.device)
+        return self
+
+    def clone_params(self):
+        return [self.w1.clone(), self.b1.clone(),
+                self.w2.clone(), self.b2.clone()]
+
+    def load_cloned(self, W):
+        with torch.no_grad():
+            self.w1.copy_(W[0]); self.b1.copy_(W[1])
+            self.w2.copy_(W[2]); self.b2.copy_(W[3])
+
+    @staticmethod
+    def fwd_with(W, h):
+        x = torch.tanh(h @ W[0].t() + W[1])
+        return x @ W[2].t() + W[3]
+
+    def forward(self, h):
+        return self.fwd_with([self.w1, self.b1, self.w2, self.b2], h)
+
+    def step_size_stats(self):
+        return self.head.step_size_stats()
+
+
+def inner_adapt_swifttd(head: SwiftTDAdapter, h_sup, y_sup, K: int = 1):
+    """SwiftTD 内循环: 逐样本应用局部规则 (W 保持计算图, 供外循环 BPTT)。
+
+    SwiftTD 是**在线单样本**规则 (见 lm1 adapt_graph), 所以内循环按样本串行。
+    K 是在同一批 support 上扫的遍数。
+    """
+    W = head.clone_params()
+    B = h_sup.shape[0]
+    for _ in range(K):
+        for b in range(B):
+            hb = h_sup[b:b + 1]
+            x = torch.tanh(hb @ W[0].t() + W[1])
+            logits = (x @ W[2].t() + W[3]).view(1, 1, head.n_classes)
+            p = F.softmax(logits, dim=-1)
+            onehot = F.one_hot(y_sup[b:b + 1], head.n_classes).float()
+            errs = (p - onehot).reshape(-1)
+            W = head.head.step_graph(W, hb[0], x[0], errs)
+    return W
+
+
+def oml_step_swifttd(model, head: SwiftTDAdapter, h_sup, y_sup, h_qry, y_qry,
+                     opt_outer, K: int = 1, consolidate: bool = True,
+                     reptile_lr: float = 0.0):
+    """SwiftTD 版 OML 双循环 (与 oml_step 同协议, 只换内循环规则)。"""
+    W = inner_adapt_swifttd(head, h_sup, y_sup, K=K)
+
+    opt_outer.zero_grad()
+    loss_q = F.cross_entropy(SwiftTDAdapter.fwd_with(W, h_qry), y_qry)
+    loss_q.backward()
+    torch.nn.utils.clip_grad_norm_(
+        [p for p in model.parameters() if p.requires_grad], 1.0)
+    opt_outer.step()
+
+    if consolidate:
+        head.load_cloned([w.detach() for w in W])
+    if reptile_lr > 0.0:
+        with torch.no_grad():
+            for p, w in zip(head.parameters(), W):
+                p.add_(reptile_lr * (w.detach() - p))
+
+    with torch.no_grad():
+        loss_s = F.cross_entropy(SwiftTDAdapter.fwd_with(
+            [w.detach() for w in W], h_sup), y_sup).item()
+    return loss_q.item(), loss_s

hibs_lnn/rl_proposer.py

@@ -0,0 +1,464 @@
+"""rl_proposer.py — 真正的 RL 提议器 (取代固定公式的 RegimeProposer)。
+
+## 为什么必须有这个文件
+
+`RegimeProposer` 是个**启发式排序器**: V(p) 是状态的纯函数, 权重 λ 是超参,
+**从不被 reward 更新, 也从不积累**。leo 连续两问戳中了它:
+  「有把 policy 当做一个可以迭代和积累的参数来更新吗, 积累过程是什么?」
+  「步长为主导的 policy 积累, redefine 也需要探索 policy 的积累」
+答案都是"没有"。本文件把闭环补成真 RL。
+
+## 范式: 动作 → 环境 → 奖励 → 参数更新
+
+    环境 (Environment)  = 训练回路本身: 选一个物理区间去训练 -> 模型变化 -> 能力画像变化
+    状态 s_t            = 当前能力画像 (每候选的实测 acc / 覆盖次数 / 已学标志 + 全局统计)
+    动作 a_t            = 选一个候选区间 (后续可扩展到"动作=连续控制量")
+    奖励 r_t            = **目标函数的增量** Δ(any-time 平均准确率)
+                          ← 必须是真正要的东西, 不是"我这个区间考了多少分"
+    参数更新            = θ ← θ + α_i ⊙ (r − V_θ) ∇,   α_i 由 IDBD 在线元学
+
+    π_θ(a|s) = softmax( V_θ(s,a) / τ ),   V_θ(s,a) = θ · φ(s,a)
+
+## 步长为主导的积累 (OaK 第②条 / Sutton IDBD)
+
+关键: **α_i 不是超参, 而是随经验累积的状态**。
+
+    δ_t    = r_t − V_θ(s_t, a_t)                       (TD/bandit 误差)
+    w_i   += α_i · δ_t · φ_i                           (权重)
+    h_i    = h_i · max(0, 1 − α_i · φ_i²) + α_i · φ_i · δ_t   (★ 累积迹)
+    α_i    = α_i · exp( μ · δ_t · φ_i · h_i )          (★ 步长本身累积)
+
+`h_i` 是"信用迹", 把历史 δ 与特征的相关性**累加**起来; `α_i` 按它调整。
+**这两条是把经验持续累积进参数的通路** —— 不是 EMA 式的追踪(那会主动遗忘),
+而是 Sutton 意义上的增量累积。
+
+## ★ 实测: 步长分化存在尖锐阈值 (与 V35.2/3 同病, 两处复现)
+
+    alpha0 = 0.01 -> alpha_std ~ 1e-6   **步长死亡** (仍是超参)
+    alpha0 = 0.05 -> alpha_std ~ 1e-4   **死亡**
+    alpha0 = 0.20 -> alpha_std ~ 0.3    **分化成立** (max/min ~5x)
+    mu=1.0 + alpha0=0.2 -> exp 溢出, ratio 1e5 = 发散 (已加指数截断)
+
+  根因: IDBD 的 meta-梯度量级 ∝ alpha0 (见 V35.2/3: beta_init=0.001 推不动,
+  0.05 才分化)。默认取稳定窗口 mu=0.05 / alpha0=0.2。
+  **注意**: 这只证明"步长分化了", 不证明"分化带来收益" —— 后者必须在
+  reward 真正依赖动作的回路里测。
+
+## 探索 policy 的积累 (redefine 存活)
+
+    explore[c] = {n_visits, mean_return, last_seen}
+    探索加成 u(c) = 1/√(1 + n_visits)   (UCB 风格, 递减但不归零)
+
+**redefine 时不清零**: 候选池重建后, 每个新候选按**物理描述子最近的旧候选**
+继承 explore / α / θ 对应分量。这样"某个物理区域值不值得探索"这条知识
+**跨 pool 重建存活** —— 这正是 leo 说的"redefine 也需要探索 policy 的积累"。
+
+## 与 RegimeProposer 的关系 (共存, 不是替换)
+
+    RegimeProposer  手工 V + 状态更新      -> 作为**基线**
+    RLProposer      可学 V_θ + IDBD 步长    -> 真 RL, 用来回答"学习有没有用"
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class RLProposer:
+    """动作→环境→奖励→参数更新 的提议器; 步长 (IDBD) 是主导的累积参数。
+
+    参数
+    ----
+    desc : (N, D) 每个候选的物理描述子 (如 [log10 密度, log10 偶极 L, sin 磁纬])
+    lam  : 兼容旧接口留空
+    tau  : softmax 温度
+    k    : 每次提议几个
+    mu   : IDBD 元步长 (步长自身的更新率), 默认 0.01
+    alpha0 : 每个权重的初始步长
+    gamma  : 折扣; 1.0 = bandit (无 bootstrap), <1 = TD
+    explore_w : 探索加成权重 (UCB 风格)
+    seed : 随机种子
+    """
+
+    def __init__(self, desc, tau=0.5, k=2, mu=0.05, alpha0=0.2,
+                 gamma=1.0, explore_w=0.5, seed=0, algo="cidbd",
+                 auto_scope="global", n_know=0):
+        desc = np.asarray(desc, dtype=np.float64)
+        self.n, self.d = desc.shape
+        mu_d = desc.mean(0)
+        sd_d = desc.std(0)
+        sd_d[sd_d < 1e-9] = 1.0
+        self.desc = desc
+        self.z = (desc - mu_d) / sd_d            # 归一化描述子 (用于 redefine 继承)
+        self.tau, self.k = float(tau), int(k)
+        self.mu, self.gamma, self.explore_w = float(mu), float(gamma), float(explore_w)
+        self.rng = np.random.default_rng(seed)
+
+        # ── 可学参数 (policy 本身) ──
+        # 特征 φ(s,a) = [1, z(a), 全局统计×z(a), 覆盖, 探索加成]
+        # ★ 「丰富的内部知识」(Horde/GVF 思路): 智能体**自己的预测**进入状态。
+        #   手写先验 φ = [1, z(a), z(a)*any_time, cov, unc] 只有 9 维, 且每块都是
+        #   人给定的结构 (见 docs/oak_alignment.md §"人为规定最少的结构")。
+        #   n_know > 0 时, 评测方每步可通过 set_knowledge() 注入一段**外部知识向量**
+        #   (例如: 当前能力画像 acc_matrix 的一行 + 转移模型对每个候选的预测增量),
+        #   它被线性映射进 φ。知识维度越高, 可分化步长的方向就越多。
+        self.n_know = int(n_know)
+        self.fdim = 1 + self.d + self.d + 2 + self.n_know
+        self.theta = np.zeros(self.fdim)          # 价值权重 (policy 参数)
+        # ★ 每个权重一个步长 + 一个信用迹 —— 这就是"步长为主导的积累"
+        self.alpha = np.full(self.fdim, float(alpha0))
+        self.beta = np.log(np.maximum(self.alpha, 1e-12))
+        self.h = np.zeros(self.fdim)              # IDBD 信用迹 (累积)
+        self.baseline = 0.0
+        # ★ δ 的 RMS (误差归一化)。标准 IDBD 假设 δ 是 O(1) 量级, 但
+        #   "目标函数的增量" δ≈0.006 -> mu*δ*phi*h ≈ 1e-6 -> 步长几乎不动
+        #   (实测 alpha_std=0.0, 与 V35.2/3 记录的 beta_std=1.6e-05 同病)。
+        #   归一化后 mu 的含义与任务量级解耦。
+        self.drms = 1.0
+        # ★ Autostep (Mahmood/Sutton/Degris/Pilarski 2012) 的两个归一化器。
+        #   动机 (论文的单位分析): IDBD 的指数项 delta*x*h 量纲是 y^2, 所以
+        #   最优 mu 的量纲是 1/y^2 —— **目标方差一变, 最优 mu 就跨数量级漂移**
+        #   (论文实测跨 5 个数量级)。我们的 reward = Δ(any-time) ~ 0.02, y^2 极小,
+        #   所以实测必须 alpha0>=0.2 才活、mu=1.0 就炸 —— 与论文所述完全一致。
+        #   Autostep 的两步归一化让 mu 免调参、且"overshoot 不可能发生"。
+        self.v = np.zeros(self.fdim)        # (4) |delta*x*h| 的 running max
+        self.v_g = 0.0                      # global 作用域时的标量归一化因子
+        # ★ IDBD 量纲标准化器: 指数 delta*x*h 的量纲是 y^2 (论文 §3), 故须除以其
+        #   自身量级才能让 mu 与任务无关。**注意这不同于 Autostep**: Autostep 除以
+        #   running **max** (把指数卡死在 mu, 杀掉积累); 这里除以 running **RMS**
+        #   (慢变标量, 保留跨分量比例与累积性)。
+        self.grms = 1e-8
+        self.beta_lo = float(np.log(1e-6))   # log(alpha) 的下界 (限制累积总量)
+        self.beta_hi = float(np.log(10.0))   # 上界
+        self._warm = 0                       # idbd-acc 的 warmup 计数
+        # ── Continual-IDBD (按用户给的 §9/§10 设计) ──
+        #   s_i    : 逐分量 |g_i| 的 EMA 尺度估计 (既归一化又保留跨分量比例)
+        #   alpha_min/max : **clip 在 alpha 上**, beta 不 clip -> beta 可继续
+        #                   累积, 也就能在恢复时立刻回到可塑区间
+        #   E_base / kappa : 误差基线 + 变化检测阈值 (环境突变 -> 提可塑性)
+        self.s = np.ones(self.fdim) * 1e-8
+        self.rho = 0.01                      # s 的 EMA 速率
+        self.alpha_min = 1e-5
+        self.alpha_max = 10.0
+        self.E_base = None
+        self.kappa = 3.0                     # 误差 > kappa*基线 = 环境变了
+        self.alpha_recovery = 0.05           # 恢复时的可塑性下限
+        self.n_recovery = 0
+        self.flip_rate = []                  # weight-flipping rate 的历史
+        self.know = np.zeros(self.n_know)   # 内部知识向量 (评测方每步注入)
+        self.Wk = np.zeros((self.n_know, self.n_know))  # 知识->特征 的线性映射
+        if self.n_know:
+            # 初始化为确定性正交映射 (无需训练, 保留信息不塌缩)
+            self.Wk = np.eye(self.n_know) * (1.0 / max(1.0, np.sqrt(self.n_know)))
+        self.tau_a = 1e4                   # (4) 归一化器的跟踪速率
+        self.algo = algo
+        # ★ Autostep 归一化因子的作用域。
+        #   论文 Table 1 用**逐分量** running max: v_i = max|delta*x_i*h_i|。
+        #   实测 (tests/diag_stepsize.py): 逐分量归一化把指数**卡死在 mu**
+        #   (|e|max 恰 = mu), 于是跨分量的量级信息被抹掉 -> alpha max/min
+        #   只有 1.10/1.31, 而 h 自身的 max/min 高达 72/55 (特征明明可分)。
+        #   论文 §3 的单位分析给出正确作用域: delta*x*h 的量纲是 y^2, 故
+        #   归一化因子应是一个**带 y^2 量纲的标量**, 而非逐分量向量。
+        #   'global' = 用全局 running max (保留跨分量比例, 默认);
+        #   'per_component' = 论文原版 (保留以作对照)。
+        self.auto_scope = auto_scope
+
+        # ── 环境状态 ──
+        self.visits = np.zeros(self.n, dtype=np.float64)
+        self.acc = np.full(self.n, np.nan)
+        self.learned = np.zeros(self.n, dtype=bool)
+        self.global_acc = 0.0                      # 上一轮的全域平均 (算 reward 用)
+        self.any_time = 0.0
+
+        # ── 探索记录 (redefine 存���) ──
+        self.explore = np.zeros(self.n, dtype=np.float64)   # 每候选的累积收益
+        self.explore_n = np.zeros(self.n, dtype=np.float64)
+        self.redefine_count = 0
+        self.trace = []                            # 每步记录, 供分析
+
+    # ─────────────── 特征 / 价值 / 策略 ───────────────
+    def set_knowledge(self, vec):
+        """注入内部知识向量 (Horde/GVF: 让智能体自己的预测成为状态)。
+
+        调用方每步喂入, 例如:
+          [acc_matrix[t] 的一行 (6 域能力画像), 之前几步的 any-time, 遗忘信号]
+        或 转移模型对每个候选的预测增量。
+        形状不匹配则忽略 (保证向后兼容)。
+        """
+        v = np.asarray(vec, dtype=float).ravel()
+        if v.size != self.n_know:
+            return
+        self.know = np.nan_to_num(v, nan=0.0, posinf=0.0, neginf=0.0)
+
+    def phi(self, i):
+        """φ(s,a): 描述子 + 与全局状态的调制 + 覆盖/探索加成 + **内部知识**。"""
+        cov = 1.0 / (1.0 + self.visits[i])
+        unc = 1.0 / np.sqrt(1.0 + self.explore_n[i])      # UCB 风格探索加成
+        zz = self.z[i]
+        base = np.concatenate([[1.0], zz, zz * self.any_time, [cov, unc]])
+        if self.n_know:
+            # 知识以 zz 为门控投影进来: 候选特定的知识 vs 全局知识
+            k = self.Wk @ self.know
+            return np.concatenate([base, k * (1.0 + 0.5 * zz[0])])
+        return base
+
+    def value(self, i):
+        return float(self.theta @ self.phi(i))
+
+    def score(self, i):
+        return self.value(i) + self.explore_w / np.sqrt(1.0 + self.explore_n[i])
+
+    def probs(self):
+        # ★ 必须 clip: theta 学起来后分数差会拉大, 直接 exp 会让远端候选
+        # **下溢成恰好 0**, 于是 rng.choice(replace=False) 报
+        # "Fewer non-zero entries in p than size" 而崩。
+        # clip 到 [-30, 0] 保证每个候选都有非零概率 (exp(-30) ~ 9e-14)。
+        s = np.array([self.score(i) for i in range(self.n)])
+        s = np.clip((s - s.max()) / max(1e-9, self.tau), -30.0, 0.0)
+        e = np.exp(s)
+        tot = e.sum()
+        if tot <= 0 or not np.isfinite(tot):
+            return np.full(self.n, 1.0 / self.n)     # 兜底: 退化成均匀
+        return e / tot
+
+    # ─────────────── 动作 ───────────────
+    def act(self, k=None, greedy=False):
+        """选动作 (提议 k 个候选)。greedy=True 用 argmax (评估用)。"""
+        k = k or self.k
+        if greedy:
+            order = np.argsort([self.score(i) for i in range(self.n)])[::-1]
+            idx = list(map(int, order[:k]))
+        else:
+            p = self.probs()
+            idx = list(map(int, self.rng.choice(self.n, size=min(k, self.n),
+                                                replace=False, p=p)))
+        for i in idx:
+            self.visits[i] += 1
+        return idx
+
+    # ─────────────── 奖励 → 参数更新 ───────────────
+    def observe(self, idx, acc, any_time=None):
+        """环境反馈: 记录实测 acc + 全域 any-time 准确率。
+
+        reward 由 update() 从**目标函数的增量**算出, 不是"该区间考了多少分"。
+        """
+        for i in idx:
+            self.acc[i] = float(acc)
+            self.learned[i] = True
+        if any_time is not None:
+            self.any_time = float(any_time)
+
+    def update(self, idx, r=None, gamma=None):
+        """★ 参数更新: 用 reward 更新 policy。返回本步的 δ。
+
+        r 为空时用 Δ(any-time) 作为 reward —— 这才是**真正的目标**。
+        """
+        gamma = self.gamma if gamma is None else gamma
+        if r is None:
+            r = self.any_time - self.global_acc        # 目标函数增量
+        self.global_acc = self.any_time
+
+        deltas = []
+        for i in idx:
+            phi = self.phi(i)
+            v = float(self.theta @ phi)
+            delta = float(r - v)                       # δ = r − V
+            # ★ 误差归一化: 把 δ 缩放到 ~O(1), 否则 IDBD 的 meta-梯度消失
+            self.drms = 0.99 * self.drms + 0.01 * delta ** 2
+            delta_n = delta / max(1e-6, np.sqrt(self.drms))
+            if self.algo == "autostep":
+                # ── Autostep (2012 Table 1) ──
+                g = np.abs(delta_n * phi * self.h)
+                if self.auto_scope == "global":
+                    # ★ 标量归一化 (单位分析推导的修正): 保留跨分量比例
+                    gmax = float(g.max()) if g.size else 0.0
+                    self.v_g = max(gmax, self.v_g + (1.0 / self.tau_a)
+                                   * float(np.sum(self.alpha * phi ** 2))
+                                   * (gmax - self.v_g))
+                    denom = self.v_g if self.v_g > 0 else 1.0
+                    self.alpha *= np.exp(
+                        np.clip(self.mu * delta_n * phi * self.h / denom, -2.0, 2.0))
+                else:
+                    # 论文原版: 逐分量 running max (会把 |e| 卡死在 mu)
+                    self.v = np.maximum(g, self.v + (1.0 / self.tau_a)
+                                        * self.alpha * phi ** 2 * (g - self.v))
+                    nz = self.v > 0
+                    self.alpha[nz] *= np.exp(
+                        np.clip(self.mu * delta_n * phi[nz] * self.h[nz]
+                                / self.v[nz], -2.0, 2.0))
+                # (6)(7) 有效步长上界: sum(alpha*x^2) <= 1 => 过冲不可能
+                M = max(float(np.sum(self.alpha * phi ** 2)), 1.0)
+                self.alpha = self.alpha / M
+                # 权重 + 信用迹 (与 IDBD 同)
+                self.theta += self.alpha * delta_n * phi
+                self.h = self.h * np.maximum(0.0, 1.0 - self.alpha * phi ** 2) \
+                    + self.alpha * phi * delta_n
+            else:
+                # ── IDBD (Sutton 1992, 官方式 (3)) —— 累积型 + 三项安全化 ──
+                # 官方: alpha *= exp(mu * delta * x * h)  (指数项**带 x**)
+                #
+                # 三处安全化, 每处都刻意**保住累积性** (与 Autostep 的取舍相反):
+                #  ① 量纲标准化: 指数除以 |delta*x*h| 的 running **RMS**。
+                #     Autostep 用 running max -> 指数恒被卡在 mu, n 从 36 到 1000
+                #     ratio 恒为 1.01 (实测) = 完全不累积。RMS 是慢变标量,
+                #     跨分量比例与时间累积都保留。
+                #  ② 累积量限幅: 限制的**不是每步指数**, 而是累积后的 log(alpha)
+                #     本身 (beta in [log 1e-6, log 10])。Autostep 限制每步指数,
+                #     于是总位移被 exp(mu*n) 封顶; 这里允许单步大步, 只防跑飞。
+                #  ③ 地板可恢复: 官方 IDBD 会把握信噪比差的分量打到下限 (实测出现
+                #     1e-5 且再也回不来)。这里对撞到地板的分量给一个微小的复活推进。
+                self.theta += self.alpha * delta_n * phi
+                self.h = self.h * np.maximum(0.0, 1.0 - self.alpha * phi ** 2) \
+                    + self.alpha * phi * delta_n
+                _raw = delta_n * phi * self.h
+                if self.algo == "cidbd":
+                    # ── Continual-IDBD (用户给的 §9 设计) ──
+                    #   g_i = delta*x_i*h_i                        (元梯度)
+                    #   s_i <- (1-rho)s_i + rho*|g_i|              (逐分量 EMA 尺度)
+                    #   beta_i <- beta_i + mu * g_i/(s_i+eps)      (归一化后累积)
+                    #   alpha_i = clip(exp(beta_i), a_min, a_max)  (**clip 在 alpha 上**,
+                    #                                               beta 不 clip)
+                    #   h_i <- h_i[1-alpha_i x_i^2]^+ + alpha_i delta x_i
+                    # 与 Autostep 的关键差别: 用 EMA 而非 running max。
+                    # max 会把指数**卡死在 mu**(实测 |e|max ≡ mu, n 从 36 到 1000
+                    # 完全不累积); EMA 是平滑估计, 保留跨分量比例与时间累积。
+                    self.s = (1.0 - self.rho) * self.s + self.rho * np.abs(_raw)
+                    _e = self.mu * _raw / (self.s + 1e-12)
+                    _e = np.clip(_e, -2.0, 2.0)
+                    self.beta = np.log(np.maximum(self.alpha, 1e-12)) + _e
+                    self.alpha = np.clip(np.exp(np.clip(self.beta, -30, 30)),
+                                         self.alpha_min, self.alpha_max)
+                    self.flip_rate.append(float(np.mean(
+                        np.sign(_e) != np.sign(getattr(self, "_e_prev", _e)))))
+                    self._e_prev = _e
+                elif self.algo == "idbd-raw":
+                    # ★ 官方 IDBD, **不做任何 running 归一化**。
+                    #   实测 (真实回路): raw 版 alpha_std=0.2357 / ratio=3.92;
+                    #   而加 RMS 归一化后掉到 0.0006 / 1.01 —— 因为 delta 已被
+                    #   delta_rms 归一化过一次, 再除 grad_rms 等于**双重归一化**,
+                    #   指数塌到 ~0, alpha 几乎不动。分化能力被自己的"安全化"杀死。
+                    #   代价: 指数无界 -> 靠下面的软壁垒与地板兜底。
+                    _e = np.clip(self.mu * _raw, -2.0, 2.0)
+                elif self.algo == "idbd-acc":
+                    # ★ 真累积: 归一化因子在**前 warmup 步测一次就冻结**。
+                    #   任何 running 归一化 (Autostep 的 max / 上面的 RMS) 都会把
+                    #   指数变成平稳量 -> n 从 36 到 1000 完全不累积 (实测 ratio
+                    #   恒在 ~40x 不增长)。要在时间上累积, 归一化因子必须是常数。
+                    #   代价: 该常数与任务量级���合 -> 用 warmup 自动标定一次。
+                    if self._warm < 50:
+                        self._warm += 1
+                        self.grms = max(self.grms, float(np.mean(_raw ** 2)))
+                        _den = max(1e-8, np.sqrt(self.grms))
+                    else:
+                        _den = max(1e-8, np.sqrt(self.grms))   # 冻结, 不再更新
+                    _e = np.clip(self.mu * _raw / _den, -2.0, 2.0)
+                else:
+                    self.grms = 0.99 * self.grms + 0.01 * float(np.mean(_raw ** 2))
+                    _e = np.clip(self.mu * _raw / max(1e-8, np.sqrt(self.grms)),
+                                 -2.0, 2.0)
+                # ★ 软壁垒, 不用硬 clip。
+                #   硬 clip 实测的失败: 所有分量的 log(alpha) 都顶到 beta_hi
+                #   -> 挤在天花板上 -> alpha max/min 塌回 1.0 (分化全丢)。
+                #   软壁垒: 接近上界时只阻尼**正向**更新、接近下界时只阻尼
+                #   **负向**更新。边界因此是「吸引但非吸收」的, 跨分量差异得以保留,
+                #   同时仍然防跑飞。
+                _la = np.log(self.alpha) + _e
+                _span = self.beta_hi - self.beta_lo
+                _t = np.clip((_la - self.beta_lo) / _span, 0.0, 1.0)   # 0=下界 1=上界
+                _la = np.log(self.alpha) + _e * np.where(_e > 0, 1.0 - _t, _t)
+                _la = np.clip(_la, self.beta_lo, self.beta_hi)         # 极值兜底
+                self.alpha = np.exp(_la)
+                # ③ 地板复活: 撞到下限的分量获得一个朝向可学区间的微小推进
+                _dead = self.alpha <= 1e-6 * 1.01
+                if _dead.any():
+                    self.alpha[_dead] = np.minimum(
+                        10.0, self.alpha[_dead] * np.exp(0.05 * np.sign(_e[_dead])))
+            # (4) 探索记录累积 (redefine 存活)
+            self.explore[i] += r
+            self.explore_n[i] += 1.0
+            deltas.append(delta)
+
+        # ★ §10 reset/recovery: 误差超阈值 = 环境变了 -> **保留 w**, 只提可塑性。
+        #   这是「真正的持续学习」: 不是重训丢知识, 而是提高 plasticity 重新适应。
+        if self.algo == "cidbd":
+            _E = float(np.mean([d ** 2 for d in deltas])) if deltas else 0.0
+            if self.E_base is None:
+                self.E_base = max(_E, 1e-9)
+            elif _E > self.kappa * self.E_base:
+                # 只抬高 alpha (beta 同步), 权重 theta 完全不动
+                _new = np.maximum(self.alpha, self.alpha_recovery)
+                self.alpha = _new
+                self.beta = np.log(np.maximum(_new, 1e-12))
+                self.n_recovery += 1
+            else:
+                self.E_base = 0.999 * self.E_base + 0.001 * _E
+        self.baseline += 0.05 * (r - self.baseline)     # 简单基线
+        self.trace.append({
+            "idx": list(map(int, idx)), "reward": round(float(r), 5),
+            "delta": round(float(np.mean(deltas)) if deltas else 0.0, 5),
+            "alpha_mean": round(float(self.alpha.mean()), 6),
+            "alpha_std": round(float(self.alpha.std()), 6),
+            "h_norm": round(float(np.linalg.norm(self.h)), 5),
+        })
+        return float(np.mean(deltas)) if deltas else 0.0
+
+    # ─────────────── redefine: 探索积累跨重建存活 ───────────────
+    def redefine(self, new_desc):
+        """重建候选池, 但**继承**探索记录 / 步长 / 价值参数。
+
+        leo: "redefine 也需要探索 policy 的积累" —— 若重建就清零,
+        则每次 redefine 都从零开始学"哪里值得探索", 探索知识无法累积。
+        继承方式: 每个新候选按**物理描述子最近**的旧候选继承。
+        """
+        new_desc = np.asarray(new_desc, dtype=np.float64)
+        # 归一化用新池自己的统计 (与构造时一致)
+        mu_d, sd_d = new_desc.mean(0), new_desc.std(0)
+        sd_d[sd_d < 1e-9] = 1.0
+        zn = (new_desc - mu_d) / sd_d
+
+        keep = {"explore": [], "explore_n": [], "acc": [], "learned": []}
+        for a in zn:
+            j = int(np.argmin(np.linalg.norm(self.z - a, axis=1)))  # 最近旧候选
+            keep["explore"].append(self.explore[j])
+            keep["explore_n"].append(self.explore_n[j])
+            keep["acc"].append(self.acc[j])
+            keep["learned"].append(bool(self.learned[j]))
+
+        self.n = len(new_desc)
+        self.desc, self.z = new_desc, zn
+        self.explore = np.array(keep["explore"])
+        self.explore_n = np.array(keep["explore_n"])
+        self.acc = np.array(keep["acc"])
+        self.learned = np.array(keep["learned"])
+        self.visits = np.maximum(1.0, self.explore_n)   # 已探过的别当全新的
+        self.redefine_count += 1
+        # θ / α / h 是全局参数, 天然跨 redefine 存活 —— 这正是"积累"
+
+    # ─────────────── 诊断 ───────────────
+    def stats(self):
+        return {
+            "algo": self.algo,
+            "n_candidates": int(self.n),
+            "n_learned": int(self.learned.sum()),
+            "redefine_count": int(self.redefine_count),
+            # ★ 步长是核心累积量: 它的分化程度 = 是否真的在学"谁该快谁该慢"
+            "alpha": {
+                "min": round(float(self.alpha.min()), 6),
+                "max": round(float(self.alpha.max()), 6),
+                "std": round(float(self.alpha.std()), 6),
+                "mean": round(float(self.alpha.mean()), 6),
+                "ratio_max_min": round(float(self.alpha.max()
+                                             / max(1e-9, self.alpha.min())), 2),
+            },
+            "h_norm": round(float(np.linalg.norm(self.h)), 5),
+            "theta_norm": round(float(np.linalg.norm(self.theta)), 5),
+            "baseline": round(float(self.baseline), 5),
+            "explore": {"nonzero": int((self.explore_n > 0).sum()),
+                        "mean_n": round(float(self.explore_n.mean()), 3)},
+            "any_time": round(float(self.any_time), 4),
+            "delta_rms": round(float(np.sqrt(max(0.0, self.drms))), 6),
+            "grad_rms": round(float(np.sqrt(max(0.0, self.grms))), 6),
+            "alpha_dead": int((self.alpha <= 1e-5).sum()),
+            "n_recovery": int(getattr(self, "n_recovery", 0)),
+            "flip_rate_mean": round(float(np.mean(self.flip_rate[-50:]))
+                                    if getattr(self, "flip_rate", None) else 0.0, 4),
+        }

hibs_lnn/rr_agent.py

@@ -0,0 +1,1108 @@
+# -*- coding: utf-8 -*-
+"""`RRSkillAgent` —— OaK 第一步(SubTask → Option)在 KeyDoor 上的 agent 侧实现。
+
+**为什么是子类**:`SkillAgent.run_episode` 是所有实验臂的公共路径。把 rr 逻辑
+写进父类会改动正在跑的管线;写成子类则:
+
+  * `mode != "rr"` 时**逐字委托** `super().run_episode()` → primitive /
+    rediscover / macro 三个对照臂与原来**逐位相同**(对照干净);
+  * 部署只是**新增一个文件**, 不修改任何现有文件。
+
+## 与 OpenLoop 的区别(§1, Pitfall 35)
+
+    a_t = π_o(s_t)     ← **每一步都按当前状态重算**(本文件)
+    a_{t+i} = a_i^o    ← 固定动作序列replay(不是时间抽象)
+
+`π_o` 来自子任务的价值迭代解,存成表;执行时**每个状态查一次表**, 所以
+`recompute-count == 执行步数`。
+
+## 四条终止判据(§6, 全部必需)
+
+    ① goal_reached  特征达成(x_i(s)=1)        ← 子任务的**目的**
+    ② beta_stop     表中 β_o(s)=True(停车最优)
+    ③ expired       **硬到期**(由 option 自身的名义时长导出, 不是拍脑袋常数)
+    ④ stall         连续 stall_patience 步状态不变(撞墙空转)
+
+    另有 ⑤ devalued: 主任务价值追上后增益 ≤ 0 → 主动放弃。
+
+到期是**独立的第四条**而不是前三条的兜底 —— 前三条各自会因自己的原因不触发
+(容差尺度错 / 台账空 / 阈值没到), 到期把损害封顶。
+"""
+import numpy as np
+import math
+
+from hibs_lnn.rr_options import (
+    KeyDoorTabular, build_bottleneck_library, build_random_goal_library,
+    build_rr_library, initiation_ok, main_value, option_gain,
+)
+from hibs_lnn.skill_agent import SkillAgent
+from hibs_lnn.subtask_options import STOP
+
+
+class RRSkillAgent(SkillAgent):
+    """在 `SkillAgent` 上增加 `mode="rr"`(reward-respecting subtask options)。
+
+    消融旋钮(每个对应矩阵里的一臂):
+        rr_v_main   "exact" | "learned"   价值函数来源(精确 VI / agent 自己的 Q)
+        rr_z_mode   "rr" | "zeroV" | "nobonus"
+        rr_cumulant "reward" | "zero"
+        rr_feats    ("key","door") | ("key",) ...
+        rr_bonus    w̄(浮点, 扫录用)
+        rr_lib      "rr" | "bottleneck" | "random"   换整库(负对照)
+    """
+
+    def __init__(self, mdp, mode="rr", seed=0, rr_v_main="exact",
+                 rr_z_mode="rr", rr_cumulant="reward", rr_feats=("key", "door"),
+                 rr_bonus=1.0, rr_lib="rr", rr_max_duration=None,
+                 stall_patience=4, rr_select_rule="uniform",
+                 rr_min_launches=6, rr_ucb_c=1.0, rr_calib_min_rate=0.5,
+                 rr_persist=True, rr_forget_hl=float("inf"),
+                 rr_score="rate", rr_pot="learned",
+                 rr_calib_min_adv=0.0, rr_retire_rule="internal",
+                 rr_calib_min_advq=0.0, rr_forgive_p=0.0,
+                 rr_lr_v=0.2, rr_starve_steps=None, rr_unk_p=0.5,
+                 rr_three_state=False, rr_dyn="none", rr_dyn_c=1.0,
+                 rr_evidence=False, rr_ev_n_min=10, rr_ev_z_bad=2.0,
+                 rr_ev_stale_hl=200, **kw):
+        super().__init__(mdp, mode=mode, seed=seed, **kw)
+        self.rr_v_main = rr_v_main
+        self.rr_z_mode = rr_z_mode
+        self.rr_cumulant = rr_cumulant
+        self.rr_feats = tuple(rr_feats)
+        self.rr_bonus = float(rr_bonus)
+        self.rr_lib = rr_lib
+        # ★ 选择规则**所有臂共用同一个** —— 这样臂间的差异只能来自"子任务内容",
+        #   而不是来自某个选择启发式。规则本身是**另一条消融轴**。
+        #     "uniform" 在可启动的 option 里均匀抽(每个库都有同等曝光)
+        #     "gain"    argmax(子任务价值 − V_main), 只在 > 0 时启动
+        #   §3 的反面教训: 用 `V_main` 做增益基线时, `c=−1` 的瓶颈 option
+        #   价值为负 -> 永不启动 -> 负对照臂变成**空臂**(不是"更差")。
+        self.rr_select_rule = rr_select_rule
+        self.rr_max_duration = None if rr_max_duration is None else int(rr_max_duration)
+        self.stall_patience = int(stall_patience)
+
+        self.rr_lib_obj = None
+        self.rr_mdl = None
+        self._rr_regime = None
+        self._rr_cap = {}          # option 名 -> 硬到期上限
+        # ── 计数器(§3: 模式的机制差异必须在**跑了之后**可被证伪) ──
+        self.rr_stats = {
+            "recomputes": 0,        # π_o 重算次数(闭环执行 ≈ 执行步数)
+            "selections": 0,        # 启动次数
+            "exec_steps": 0,        # 在 option 内的总步数
+            "terms": {},            # 终止原因台账(**必须非空**)
+            "durations": [],        # 每次执行的时长(检 lock-in)
+            "stall_baseline": [],   # 停滞统计的基线样本
+            "rebuilds": 0,
+        }
+        # ══ 自我校准闭环(L2 缺的那一格)══════════════════════════════
+        #  这个 dict 是**按 option 归属**的台账。在此之前整个仓库唯一的
+        #  更新点是 skill_agent.py:240(旧 macro 路径)的全局计数器 ——
+        #  `_rr_settle(self, st, steps, reason)` 收下 `st` 然后**完全忽略它**,
+        #  所以库级台账对 rr 路径不存在, "这个 option 从不达成目标" 这个
+        #  事实无处安放(L2 的 57 启动 / 56 expired / 1 reached 就是这样
+        #  被埋掉的: 没有任何东西因为该事实而改变)。
+        #  信号取 **option 自己的达成率**(β_at_feature), 不取主奖励 ——
+        #  KeyDoor 的奖励是稀疏的(只在终点 +1), 拿主奖励做 option 级信号
+        #  会退化成"所有 option 都得 0"。
+        self.rr_outcome = {}        # option 名 -> {"n", "reached", "steps"}
+        self.rr_min_launches = int(rr_min_launches)   # 判"坏了"所需的最少启动数
+        self.rr_ucb_c = float(rr_ucb_c)               # 校准选择的探索常数
+        self.rr_calib_min_rate = float(rr_calib_min_rate)  # 达成率低于此 = 机制坏了
+        # ══ 持续性的两个旋钮(「持续自我校准」的"持续")══════════════════
+        #  rr_persist     台账是否跨 regime 存活。
+        #                 False -> 每次库重建就清空(只在单 regime 内校准)
+        #                 True  -> 账随 agent 走(校准成为**跨任务**的知识)
+        #  rr_forget_hl   **忘记半衰期**(以启动次数计)。inf = 不忘记 = 终身平均。
+        #
+        #  ★ 为什么持久化必须配遗忘, 否则持久化是**有害**的:
+        #    无遗忘时 n 会跨 regime 累积到几百, 于是
+        #      (a) 老的成功把新 regime 的失败稀释掉 —— 一个在第 2 个 regime
+        #          已经坏掉的 option, 终身达成率仍可能是 0.9, 检测不出来;
+        #      (b) UCB 探索项 c·sqrt(ln N/(n+1)) 被大 n 压死 —— agent 不再
+        #          去重新检验它, 陈旧的判断被永久锁住。
+        #    「持续校准」必须跟踪的是**当前胜任度**, 不是历史平均。
+        #    实现: 有效计数按 decay = 0.5^(1/hl) 指数衰减。
+        #    hl=inf -> decay=1.0 -> n_eff ≡ n, 逐位复现旧行为(向后兼容)。
+        self.rr_persist = bool(rr_persist)
+        self.rr_forget_hl = float(rr_forget_hl)
+        #  rr_score  选择分数用什么信号
+        #     "rate" 达成率(option 自己的成功)         —— 机制内部视角
+        #     "eff"  达成次数 / 消耗步数               —— **把主任务的成本接进来**
+        #            奖励稀疏时主奖励做不了 option 级信号, 但**时间是通用货币**:
+        #            视野有限, 白走的路严格是损失。所以"每步产出多少达成"是
+        #            一个不需要 oracle、又对主任务有意义的信号。
+        self.rr_score = rr_score
+        if rr_score not in ("rate", "eff", "adv", "advq"):
+            raise ValueError(f"unknown rr_score: {rr_score}")
+        # ══ 主任务信号(§8 明写的那个缺口, 现在被实测证据逼出来了)══════
+        #  为什么必须有: 只用 **option 自己的判据**(达成率)做校准是**错的**。
+        #  实测: 把一个 option 的上限压到 1 步 -> 它"达不成自己的子目标"
+        #  (达成率 0.2), 但**它执行的那一步仍然是 π_o 的最优步**, 对主任务
+        #  有益。按内部判据把它淘汰 -> 白损失 π_o 的好步 -> 步数反而差
+        #  1.0 步(3 seed 一致)。**校准到错误的信号上, 会淘汰有用的东西。**
+        #
+        #  主任务信号取 **势函数差分 / 步数**:
+        #      progress = Φ(终止状态) − Φ(起始状态),  adv = Σprogress / Σsteps
+        #  这是 SMDP 视角下"这个 option 每消耗一步, 把主任务推进了多少"。
+        #  Φ 取 **agent 自己的 max_a Q[s,a]** —— 在线、不需要 oracle。
+        #  (早期 Q 是乐观常数 -> adv≈0 -> 判定"无信息", 这是诚实的行为;
+        #   它随学习变得有信息。`rr_pot="exact"` 用模型 VI 的 V_main 作对照,
+        #   用来分离"信号质量"与"机制结构"两个因素。)
+        self.rr_pot = rr_pot
+        if rr_pot not in ("learned", "exact", "gvf"):
+            raise ValueError(f"unknown rr_pot: {rr_pot}")
+        self.rr_calib_min_adv = float(rr_calib_min_adv)
+        #  rr_retire_rule  用哪条判据决定淘汰
+        #    "internal" 只看 option 自己的达成率      (旧行为)
+        #    "adv"      只看主任务推进量
+        #    "both"     两条都判坏才淘汰             (保守)
+        #    "either"   任一条判坏就淘汰             (激进)
+        self.rr_retire_rule = rr_retire_rule
+        if rr_retire_rule not in ("none", "internal", "adv", "advq", "both",
+                                  "either", "all"):
+            raise ValueError(f"unknown rr_retire_rule: {rr_retire_rule}")
+        self.rr_regime_idx = -1        # 已见过的 regime 数(诊断用)
+        self.rr_calib_hist = []        # [{'regime': i, 'broken': [...], 'usage': {...}}]
+        # ══ option 的**学习价值**(SMDP)══════════════════════════════════
+        #  ★ 这是对"在线可用势函数"问题的正确解 —— 不是找一个更好的 Φ,
+        #    而是**取消 Φ 这个中间量**,直接学 option 自己的价值。
+        #
+        #  为什么 Φ 这条路走不通:
+        #    `adv = [Φ(s_end) − Φ(s_start)] / steps` 把两件事混在一起 ——
+        #      (a) option 把我移动了
+        #      (b) agent 在学习, 所以 Φ 自己变了
+        #    而且乐观初始化下 Φ(s_start) = Φ(s_end) = 常数 -> 恒等于 0。
+        #
+        #  正确的量是 **advantage**:
+        #      A(s, o) = Q_opt(s, o) − V_base(s),   V_base(s) = max_a Q[s, a]
+        #  它直接回答"从 s 执行这个 option, 比贪心走基元动作好多少" ——
+        #  这正是"要不要留它"该问的问题。阈值 0 在**同一奖励尺度**上有意义,
+        #  而且两边**从同一个初值出发**(都 q_init), 所以早期 A ≡ 0 =
+        #  "还没有信息"(正确行为, 不是 bug)。
+        #
+        #  SMDP 更新(每次 option 结算时):
+        #      Q_opt[s0, o] += lr · [r_opt + γ^k · V(s1) − Q_opt[s0, o]]
+        #  r_opt = option 执行期间累计的**主任务**奖励, k = 执行步数。
+        #  部分执行(到期/停滞/被中断)按截断处理, 仍是合法 bootstrap。
+        #
+        #  ★ 判别器为什么**从数学里自己掉出来**(不是手设计的阈值):
+        #    inert(上限压到1步, 但那1步是好的): Q_opt ≈ γ·V(s') 且 V(s') ≈ V(s)/γ
+        #                                        => A ≈ 0     -> 不淘汰 ✓
+        #    harm (反转 π_o, 朝反方向走):        Q_opt ≈ γ·V(s_back), V(s_back) ≪ V(s)
+        #                                        => A ≪ 0     -> 淘汰   ✓
+        self.q_opt = None              # (n_states, n_opts) —— 惰性建表
+        self._rr_oidx = {}             # option 名 -> 列号(跨 regime 稳定的身份)
+        self.rr_calib_min_advq = float(rr_calib_min_advq)
+        # ★ GVF 势函数: **中性初始化**(全 0)的状态价值表。
+        #   为什么不能借用 `self.q.Q` 的 max: 那张表是乐观初始化,
+        #   未试过的动作会把 max 顶在初值上 —— 实测 V(s0) 逐位 1.0000。
+        self.rr_V = np.zeros(self.mdp.n_states, dtype=float)
+        self.rr_lr_v = float(rr_lr_v)
+        # ★ "犯错是可以原谅的" = **退休可逆**。被判坏的 option 以 p 的概率被重新检验;
+        #   若其统计量恢复(它用的是同一批阈值判据), 下次 `rr_broken` 自然不再点名它。
+        self.rr_forgive_p = float(rr_forgive_p)
+        # ══ 三态 epistemic state(好 / 坏 / 未知)══════════════════════════════
+        #  ★ 为什么必须有: 实测发现, `advq == 0` 在两种完全不同的情况下出现 ——
+        #      (a) 证据充分且真的没有显著差异  -> 好
+        #      (b) **奖励流为空, Φ 学不到东西**(harm 故障下整臂全灭时
+        #          `Q_adv ≡ 0.0000` 精确零, 因为账压根没记)  -> **未知**
+        #    把 (b) 读成"不坏", 就是**自欺**。系统的最大缺口不是精度, 是它
+        #    分不清这两种零。所以"未知"必须是一等状态, 不能被 0 顶上。
+        #
+        #  "奖励流为空"的在线判据: 连续多少步没有拿到任何正奖励。
+        #  默认 3×horizon = "连着三个回合一分没拿" -> 势函数不可能在学东西。
+        self.rr_starve_steps = (int(rr_starve_steps) if rr_starve_steps
+                                else 3 * int(getattr(mdp, "horizon", 30)))
+        self.rr_since_rew = 0        # 距上次拿到正奖励的步数
+        self.rr_starve_ever = 0      # 曾经进入"奖励流为空"的次数(诊断)
+        self.rr_unk_p = float(rr_unk_p)   # "未知"状态的探索概率(有限度探索)
+        # ★ 三态开关。默认 **False** = 旧行为逐位不变(向后兼容 + 它本身是
+        #   一条消融轴: "把未知提升为一等状态, 到底改变了什么?")。
+        #   True 时启用三件事: 缓存为空 -> 退回基元层; 未知 -> 有限度探索;
+        #   未知 -> 永不算坏。
+        self.rr_three_state = bool(rr_three_state)
+        # ── 阶段五: 证据库(evidence bank) ──────────────────────────────
+        # ★ 默认关闭 ⇒ 旧行为**逐位不变**(与 rr_three_state 同一条纪律)。
+        # ★ 语义: 证据**只降级(好->坏), 不升级** —— 与 A 类的反熟悉度约束同一条。
+        #   理由: 预测误差低只说明"我预测得准", 不说明"这件事有价值";
+        #   而**新颖度会拉高误差** ⇒ 允许升级就等于允许新颖度伪造"好"。
+        self.rr_evidence = bool(rr_evidence)
+        self.rr_ev_n_min = int(rr_ev_n_min)
+        self.rr_ev_z_bad = float(rr_ev_z_bad)
+        self.rr_ev_stale_hl = int(rr_ev_stale_hl)
+        self.rr_bank = None
+        self.rr_ev_step = 0
+        self.rr_ev_last = None          # 最近一次的 support() 引用清单
+        self.rr_ev_bad_n = 0            # 证据库投了几次 bad(诊断用)
+        if self.rr_evidence:
+            from hibs_lnn.evidence_bank import EvidenceBank
+            self.rr_bank = EvidenceBank(
+                dim=len(self.mdp.vec()), seed=seed,
+                n_min=self.rr_ev_n_min, stale_hl=self.rr_ev_stale_hl,
+                z_bad=self.rr_ev_z_bad)
+        # ── A 类动力学证据(阶段四)─────────────────────────────────
+        #   `rr_cumulant`(上面那个)是 **option 构造期**参数 —— 它是 OaK 的
+        #   `(I_o, g_o, π_o, β_o)` 里的 `g_o`。A 类是**每步的动力学读数**,
+        #   是另一回事, 所以单开一个通道。
+        #
+        #   ★ 方向约定: 三个 cumulant 都**统一成"压力"(越大越差)** ——
+        #     A1 转移不确定性(归一化熵) / A2 转移预测误差(1−p(s2|s,a)) /
+        #     A3 离开已知稳定动力学区域(1−熟悉度)。
+        #     这样它们**只能当风险证据**, 不可能被读成"值"。
+        self.rr_dyn = str(rr_dyn)
+        if self.rr_dyn not in ("none", "N", "A1", "A2", "A3"):
+            # "N" = 新颖度**控制量** —— 与 A1/A2/A3 走同一套管道,
+            #   用来回答"A 类到底是动力学探测器, 还是只是新颖度探测器"。
+            raise ValueError(f"unknown rr_dyn: {rr_dyn}")
+        self.rr_dyn_c = float(rr_dyn_c)
+        self._rr_T = {}          # (s,a) -> {s2: n}   在线转移计数(只用真实转移)
+        self._rr_vis = {}        # s -> n             访问次数
+        self._rr_dense = {}      # option -> [n, Σ, Σ²]  动力学证据台账
+        self._rr_dseg = [0.0, 0.0, 0.0]   # 全段基线 [n, Σ, Σ²] —— "显著更差"的参照
+        self._rr_dn = 0          # A 类喂了多少个转移
+        self._rr_prev_state = {}     # option -> 上次判定(用来数退休/恢复次数)
+
+    # ── 技能库(每个 regime 重建一次 —— 目标随 regime 移动) ──────────
+    def _rr_ensure(self):
+        reg = tuple(self.mdp.regime)
+        if self._rr_regime == reg and self.rr_lib_obj is not None:
+            return
+        # ── regime 变了: 台账怎么处理 = 「持续」这条轴 ──────────────────
+        if self._rr_regime is not None:            # 不是第一次
+            self.rr_regime_idx += 1
+            self.rr_calib_hist.append({
+                "regime": self.rr_regime_idx,
+                "broken": sorted(self.rr_broken()),
+                "usage": self._rr_usage(),
+            })
+            if not self.rr_persist:
+                # 只在本 regime 内校准 —— 每换一次世界, 经验清零
+                self.rr_outcome = {}
+        mdl = KeyDoorTabular(self.mdp, gamma=self.q.gamma)
+        self.rr_mdl = mdl
+        if self.rr_v_main == "exact":
+            V_main = main_value(mdl)
+        elif self.rr_v_main == "learned":
+            # agent 自己的 Q 表 —— 在线版, 不需要 oracle
+            V_main = np.max(self.q.Q, axis=1).copy()
+        else:
+            raise ValueError(f"unknown rr_v_main: {self.rr_v_main}")
+        self._rr_v_main_arr = V_main
+
+        if self.rr_lib == "rr":
+            lib = build_rr_library(mdl, V_main, bonus_weight=self.rr_bonus,
+                                   feats=self.rr_feats,
+                                   cumulant=self.rr_cumulant,
+                                   z_mode=self.rr_z_mode)
+        elif self.rr_lib == "bottleneck":
+            lib = build_bottleneck_library(mdl)
+        elif self.rr_lib == "random":
+            lib = build_random_goal_library(mdl, V_main, seed=self.rng.randint(1 << 30))
+        else:
+            raise ValueError(f"unknown rr_lib: {self.rr_lib}")
+
+        self.rr_lib_obj = lib
+        self._rr_regime = reg
+        self.rr_stats["rebuilds"] += 1
+        # 每个 option 的硬到期上限: **由它自己的名义时长导出**。
+        # 名义时长 = 从起始状态出发、按 π_o 走、直到终止判据命中所需步数
+        # (模型确定性, 直接模拟)。
+        self._rr_cap = {}
+        for st in lib:
+            nom = self._rr_nominal(st)
+            cap = int(self.rr_max_duration) if self.rr_max_duration else max(3, 2 * nom)
+            self._rr_cap[st.name] = cap
+
+    def _rr_nominal(self, st):
+        """模拟 π_o 从**回合起始状态 0** 出发到自己终止要多少步。
+
+        模型确定性, 直接前向模拟。这个数��� `expired` 上限的依据 ——
+        §6 要求上限由 option 自身的名义时长导出, 不是拍脑袋常数。
+        """
+        s = 0
+        for k in range(1, self.mdp.horizon + 1):
+            if st.policy[s] == STOP:
+                return k
+            nxt = self.rr_mdl.T[s][st.policy[s]][0][1]
+            if self.rr_mdl.is_goal[nxt] or float(getattr(st, "feature")[nxt]) > 0:
+                return k
+            if st.beta[nxt]:
+                return k
+            if nxt == s:
+                return k
+            s = nxt
+        return self.mdp.horizon
+
+    # ── 选择 ────────────────────────────────────────────────────────
+    def _rr_select(self, s):
+        """选一个 option。规则由 `rr_select_rule` 决定(所有臂共用)。
+
+        "uniform"    —— 在**可启动**(I_o 成立)的 option 里均匀抽。
+                        每个库都有同等曝光, 所以臂间差异只能来自子任务内容。
+        "gain"       —— `argmax`(子任务价值 − V_main), 且增益必须 **> 0**。
+                        这是"哪个子任务现在最值得追"的贪心读法, 本身是一条
+                        消融轴(更强的先验 = 更多 oracle 信息)。
+        "calibrated" —— **自我校准**: 只用**自己的实测达成率**排序,
+                        不用任何假设的价值。UCB1 形式:
+                            score = reached/n + c·sqrt(ln(N+1)/(n+1))
+                        并且**排除被判"坏了"的 option**(见 `rr_broken`)。
+                        这是"犯错 -> 发现 -> 改正"的闭环本身, 与其它两条
+                        规则的关键区别是: 它**不引入任何外部先验**,
+                        "哪个 option 好"完全由 agent 自己的经验决定。
+        """
+        cand = [st for st in self.rr_lib_obj if initiation_ok(st, s)]
+        # 选择**尝试**总数 —— fallback 占比的分母必须是它, 不能是
+        # `selections`(那只在真的选中时加一, 比值会 > 1, 实测 6.827)。
+        self.rr_stats["sel_attempts"] = self.rr_stats.get("sel_attempts", 0) + 1
+        if not cand:
+            return None
+        rule = self.rr_select_rule
+        if rule == "gain":
+            best, best_g = None, 0.0
+            for st in cand:
+                g = option_gain(st, s, self._rr_v_main_arr)
+                if g > best_g:
+                    best, best_g = st, g
+            return best
+        if rule == "calibrated":
+            # ★ 奖励流为空 -> **退回安全基元策略**。这不是放弃, 是承认"现在
+            #   什么都判不了": Φ 学不到东西, 任何判断都是自欺。等主任务拿到
+            #   奖励、Φ 重新有内容, 再回来判。
+            if self.rr_three_state and self.rr_starved():
+                self.rr_stats["starved_sel"] = self.rr_stats.get("starved_sel", 0) + 1
+                return None
+            broken = self.rr_broken()
+            live = [st for st in cand if getattr(st, "name", None) not in broken]
+            # ★★ **原谅**(`rr_forgive_p`)—— "犯错是可以原谅的"的机制含义:
+            #   被判坏的 option **不是被处决**, 而是以 p 的概率被**重新检验**。
+            #
+            #   没有这条路就有一个**死锁**: 早期 V 还没学到东西(bootstrap 暂态),
+            #   option 的价值天然偏低 -> 判坏 -> 不再使用 -> 统计量永不更新 ->
+            #   永远坏。实测就是这么崩的: advq 恒 -0.004, fallback 0.999。
+            #   **退休必须可逆, 否则一次误判 = 永久损失。**
+            dea = [st for st in cand if getattr(st, "name", None) in broken]
+            if dea and self.rr_forgive_p > 0 and self.rng.rand() < self.rr_forgive_p:
+                self.rr_stats["forgiven"] = self.rr_stats.get("forgiven", 0) + 1
+                return dea[int(self.rng.randint(len(dea)))]
+            if not live:                      # 全坏了 -> 退回基元层(诚实行为)
+                return None
+            # ★ 三态驱动的选择(leo 契约: "未知应触发有限度探索"):
+            #   未知 -> 以 `rr_unk_p` 的概率**优先挑它** —— 不确定的 option
+            #           得先攒到证据, 才可能从"未知"变成"好/坏"。没有这条,
+            #           它永远停在未知(不被选 -> 没证据 -> 不被选)。
+            #   好   -> 正常 UCB 参与选择。
+            #   坏   -> 只在原谅概率下被重新检验。
+            unk = [st for st in live
+                   if self.rr_epistemic(self.rr_outcome.get(
+                       getattr(st, "name", None), {})) == "unknown"]
+            if unk and self.rr_three_state and self.rng.rand() < self.rr_unk_p:
+                self.rr_stats["unk_probe"] = self.rr_stats.get("unk_probe", 0) + 1
+                return unk[int(self.rng.randint(len(unk)))]
+            N = sum(o.get("n_eff", 0.0) for o in self.rr_outcome.values())
+            best, best_sc = None, -np.inf      # adv 分数可为负 -> 不能用 -1.0 做初值
+            for st in live:
+                o = self.rr_outcome.get(getattr(st, "name", None))
+                if o is None:                 # 没试过的 option: 无限乐观, 先试它
+                    return st
+                n = o.get("n_eff", 0.0)
+                sc = self._rr_score_of(o) + self.rr_ucb_c * float(
+                    np.sqrt(np.log(N + 1.0) / (n + 1.0)))
+                if sc > best_sc:
+                    best, best_sc = st, sc
+            return best
+        return cand[int(self.rng.randint(len(cand)))]
+
+    # ── 一个回合(rr 路径; 其他模式逐字委托父类) ──────────────────
+    def run_episode(self):
+        if self.mode != "rr":
+            return super().run_episode()          # 对照臂路径**逐字不变**
+        self._rr_ensure()
+        s = self.mdp.reset()
+        done, n = False, 0
+        active, o_steps, prev_s, stuck, o_start = None, 0, None, 0, None
+        o_rew = 0.0            # option 执行期间的**主任务**累计奖励(SMDP 更新用)
+        while not done and n < self.mdp.horizon:
+            v0 = self.mdp.vec()        # ★ **步前**状态 —— 与父类 run_episode 同约定。
+            a = None
+            if self.rng.rand() < self.opt_prob or active is not None:
+                # 启动
+                if active is None:
+                    active = self._rr_select(s)
+                    o_steps, prev_s, stuck, o_start, o_rew = 0, s, 0, s, 0.0
+                    if active is not None:
+                        self.rr_stats["selections"] += 1
+                # 出动作: **每步按当前状态重算 π_o**(闭环)
+                if active is not None:
+                    if int(active.policy[s]) != STOP:
+                        a = int(active.policy[s])
+                        self.rr_stats["recomputes"] += 1
+                    else:
+                        self._rr_settle(active, o_steps, "beta_stop", o_start, s,
+                                        r_opt=o_rew)
+                        active, o_steps, o_start = None, 0, None
+            if a is None:
+                if active is not None:
+                    self._rr_settle(active, o_steps, "devalued", o_start, s,
+                                    r_opt=o_rew)
+                    active, o_steps, o_start = None, 0, None
+                a = self.q.act(s)
+            s2, r, done = self.mdp.step(a)
+            self.q.update(s, a, r, s2, done)
+            # ★ GVF 势函数: **每个转移都喂**, 不论那一步是 option 出的还是基元出的。
+            #   这就是 option 绕过 Q 也不影响它的原因 —— 它学的是"走到哪值多少",
+            #   不是"哪个动作好"。
+            self._rr_vstep(s, r, s2, done)
+            # ★ A 类动力学证据: **先读数(用更新前的表)再更新** —— 这是
+            #   "先预测、再观测"的正确在线语义。**失败时这行照样执行**:
+            #   到不了终点也有真实转移, 这正是 A 类作为候选的全部理由。
+            if self.rr_dyn != "none":
+                _dv = self._rr_dval(s, a, s2)
+                self._rr_dstep(s, a, s2)
+                self._rr_dacc(active.name if active is not None
+                              else "__primitive__", _dv)
+            n += 1
+            # ★ 奖励流监控: "连续多少步一分没拿"。Φ 从奖励流学, 奖励流为空
+            #   时 Φ 恒为初值 —— 此时任何"不坏"的结论都是自欺。
+            self.rr_since_rew = 0 if float(r) > 0 else (self.rr_since_rew + 1)
+            # ── 阶段五: 喂证据库 ────────────────────────────────────────
+            # ★ `phi=v0, phi_next=self.mdp.vec()` —— **不能两个都传 `self.mdp.vec()`**。
+            #   `self.mdp` 在 `step()` 里已经前进, 两个都传当前 vec 会让 `v_next == v`,
+            #   TD 的 `gamma*v_next` 项与 `v` 抵消 ⇒ 学的是"瞬时误差"不是值。
+            #   (`hibs_lnn/oak_proposer.py:338` 的 `observe_gvf(phi, cums, phi)` 正是
+            #    这个形态; 本模块刻意避开, 见 docs/stage5_evidence_bank_spec.md §0。)
+            # 四个 cumulant = 这一步**四个不同的可观测事实**:
+            #   prediction → "有 option 正在执行"   reward → 即时奖励
+            #   transition → "状态没变(自环)"        regime → "本回合结束"
+            if self.rr_bank is not None:
+                _cums = (1.0 if active is not None else 0.0,
+                         float(r),
+                         1.0 if s2 == s else 0.0,
+                         1.0 if done else 0.0)
+                self.rr_ev_step += 1
+                self.rr_bank.observe(v0, _cums, self.mdp.vec(),
+                                     step=self.rr_ev_step,
+                                     regime=self.rr_regime_idx)
+            self.trans.append((v0, a, self.mdp.vec()))    # (步前, 动作, 步后)
+            # ── 结算判据: 全部在**新状态**上评估(正确语义) ──────────
+            if active is not None:
+                o_steps += 1
+                o_rew += float(r)      # 主任务奖励记到**当前这个 option** 头上
+                self.rr_stats["exec_steps"] += 1
+                reason = None
+                # ★ 主判据 = **option 自己的 β_o**(由 stopping value z 导出)。
+                #   这是机制本体 —— 之前把"特征达成"排在 β 之前, 导致所有
+                #   变体在特征亮起的同一瞬间就停, z 永远轮不到起作用,
+                #   5 个 rr 变体的台账**逐位相同**(Pitfall-26 tell)。
+                #   "恰好停在特征上"现在作为 β_o 的一个**子理由**计数,
+                #   这样既能证明机制在跑, 又能看出它停在哪。
+                if bool(active.beta[s2]):
+                    reason = ("beta_at_feature" if float(active.feature[s2]) > 0
+                              else "beta_elsewhere")
+                elif done:
+                    reason = "horizon_end"
+                elif o_steps >= self._rr_cap.get(active.name, self.mdp.horizon):
+                    reason = "expired"             # ③ 硬到期
+                elif s2 == prev_s:
+                    stuck += 1
+                    self.rr_stats["stall_baseline"].append(stuck)
+                    if stuck >= self.stall_patience:
+                        reason = "stall"           # ④ 撞墙空转
+                else:
+                    stuck = 0
+                if reason:
+                    self._rr_settle(active, o_steps, reason, o_start, s2,
+                                    r_opt=o_rew, done=bool(done))
+                    active, o_steps, o_start = None, 0, None
+                prev_s = s2
+            s = s2
+        if active is not None:                     # 回合结束仍在执行
+            self._rr_settle(active, o_steps, "horizon_end", o_start, s,
+                            r_opt=o_rew, done=True)
+        self.episodes += 1
+        self._rr_sync_states()          # 三态判定 + 退休/恢复计数(每回合一次)
+        return bool(done and self.mdp._reached()), n
+
+    # ── 有效计数(遗忘)──────────────────────────────────────────────
+    def _rr_decay(self):
+        """每次启动后, 旧统计量保留的比例。`hl=inf` -> 1.0(不遗忘)。"""
+        hl = self.rr_forget_hl
+        if hl is None or not np.isfinite(hl) or hl <= 0:
+            return 1.0
+        return float(0.5 ** (1.0 / hl))
+
+    @staticmethod
+    def _rr_rate(o):
+        """当前胜任度 = reached_eff / n_eff。不遗忘时逐位等于终身平均。"""
+        ne = o.get("n_eff", float(o.get("n", 0)))
+        return (o.get("reached_eff", float(o.get("reached", 0))) / ne) if ne > 0 else 0.0
+
+    @staticmethod
+    def _rr_eff(o):
+        """**效率** = 达成次数 / 消耗步数(每步产出多少达成)。
+
+        这是不依赖 oracle 的"主任务成本"信号: 视野有限, 白走的路严格是损失。
+        与 `rate` 的区别: 一个"总能达成但每次都绕远路"的 option,
+        `rate` 高而 `eff` 低 —— 后者才是对主任务真正有意义的量。
+        """
+        return o.get("reached_eff", 0.0) / max(1.0, o.get("steps_eff", 1.0))
+
+    def _rr_score_of(self, o):
+        s = self.rr_score
+        if s == "rate":
+            return self._rr_rate(o)
+        if s == "eff":
+            return self._rr_eff(o)
+        if s == "advq":
+            return self._rr_advq_of(o)
+        return self._rr_adv(o)
+
+    @staticmethod
+    def _rr_adv(o):
+        """主任务推进量 = Σ势函数差分 / Σ步数(每步把主任务推进多少)。"""
+        return o.get("adv_sum", 0.0) / max(1.0, o.get("adv_steps", 1.0))
+
+    def _rr_pot(self, s):
+        """势函数 Φ(s)。**必须是一个独立学习、中性初始化的状态价值预测**(GVF)。
+
+        三个来源, 依次说明为什么只有第三个在线可用:
+
+        `learned` —— `max_a Q[s,a]`, agent 的动作价值表取最大。
+            实测**不可用**: 该表是**乐观初始化**(q_init=+1.0), 只要某个动作
+            还没试过, `max_a` 就还是 1.0。实测 option 的启动状态上
+            `V(s0)` **逐位等于 1.0000**(初值), 而 `γ^k·V(s1) = 0.717` ->
+            advantage ≡ −0.275 —— **量出来的是初值 artifact, 不是 option 好坏**。
+            (32 个状态里只有 14 个有任一 Q 离开初值, 但"最大值"几乎都还在初值上。)
+
+        `exact` —— 模型 VI 的 `V_main`。干净, 但**是 oracle**(用了真转移模型),
+            只能当"信号质量"的对照, 不能当在线方案。
+
+        `gvf`   —— ★ **对"在线可用势函数"的答案**: 一张中性初始化(全 0)的
+            状态价值表, 用 TD(0) 从 agent **自己走的每一步**学, 不管那一步是
+            基元动作还是 option 内部的动作:
+
+                V[s] += lr_v · [r + γ·V[s'] − V[s]]
+
+            为什么这样就成了:
+              · **中性初值** -> 没有"未试过的动作把 max 顶在初值"这个病;
+              · 奖励稀疏(+1 只在终点) -> `V(s)` 自然收敛成 γ^(到目标的步数),
+                这**正是**我们要的"离目标多远"的势函数;
+              · **每个状态都被喂** -> option 绕过 Q 也没关系, 因为喂 V 的是
+                每一步的真实转移, 不是动作选择;
+              · 不用转移模型、不用目标位置的坐标 -> **无 oracle**。
+        """
+        if s is None:
+            return 0.0
+        if self.rr_pot == "exact":
+            return float(self._rr_v_main_arr[s])
+        if self.rr_pot == "gvf":
+            return float(self.rr_V[s])
+        return float(np.max(self.q.Q[s]))
+
+    def _rr_vstep(self, s, r, s2, done):
+        """GVF 势函数的一步 TD —— 每个转移都喂, 无论那一步是谁出的动作。"""
+        tgt = float(r) if done else float(r) + float(self.q.gamma) * self.rr_V[s2]
+        self.rr_V[s] += self.rr_lr_v * (tgt - self.rr_V[s])
+
+    def _rr_has_base(self, s):
+        """**势函数在该状态上是否有证据**(离开中性初值)。
+
+        为什么必须有这个门: 在没有任何经验的区域上比较"option 比基线好不好",
+        比出来的是**初值的形状**, 不是经验。这不是调阈值, 是判断的前提条件 ——
+        "要判断这里用 option 划不划算, 前提是在这里有过经验"。
+        """
+        if s is None:
+            return False
+        if self.rr_pot == "gvf":
+            return bool(abs(float(self.rr_V[s])) > 1e-12)
+        return bool(np.any(self.q.Q[s] != self.q.q_init))
+
+    # ── option 的学习价值(SMDP)──────────────────────────────────────
+    def _rr_oindex(self, name):
+        """option 名 -> `q_opt` 的列号。名跨 regime 稳定, 所以身份稳定。"""
+        if name not in self._rr_oidx:
+            self._rr_oidx[name] = len(self._rr_oidx)
+        n_col = len(self._rr_oidx)
+        if self.q_opt is None:
+            # 与基元 Q **同一初值** —— 这样早期 advantage ≡ 0 = "还没有信息",
+            # 而不是"所有 option 都很差"。
+            self.q_opt = np.full((self.mdp.n_states, max(n_col, 1)),
+                                 float(self.q.q_init))
+        elif self.q_opt.shape[1] < n_col:
+            pad = np.full((self.mdp.n_states, n_col - self.q_opt.shape[1]),
+                          float(self.q.q_init))
+            self.q_opt = np.hstack([self.q_opt, pad])
+        return self._rr_oidx[name]
+
+    def _rr_vbase(self, s):
+        """V_base(s) = max_a Q[s, a] —— **只用基元动作**的价值。
+
+        这是 advantage 的比较基线: "不用这个 option, 我靠基元动作能拿到多少"。
+        它必须是**基元专属**的, 不能把 option 的价值混进来, 否则
+        `Q_opt − V` 恒 <= 0(自己不可能超过包含自己的最大值)。
+        """
+        return float(np.max(self.q.Q[s]))
+
+    def _rr_vall(self, s):
+        """V_all(s) = max(基元, option) —— agent **实际行为**(含 option)的价值。
+
+        ★ SMDP 的 bootstrap 必须用它, 不能用 `_rr_vbase`: option 之间是可以
+          串联的(先拿钥匙再开门), 如果 option 从"基元专属"价值 bootstrap,
+          option 链上的价值就传不下去 —— 每次传播只能走一层。
+        """
+        v = float(np.max(self.q.Q[s]))
+        if self.q_opt is not None and self.q_opt.shape[1]:
+            v = max(v, float(np.max(self.q_opt[s])))
+        return v
+
+    @staticmethod
+    def _rr_advq_of(o):
+        """advantage = Q_opt − Φ(s0) 的(遗忘加权)均值。正 = 比基线好。"""
+        return o.get("advq_sum", 0.0) / max(1.0, o.get("advq_n", 1.0))
+
+    @staticmethod
+    def _rr_advq_se(o):
+        """上面那个均值的**标准误**(遗忘加权)。没有它就不能说"显著更差"。"""
+        n = max(1.0, o.get("advq_n", 0.0))
+        m = o.get("advq_sum", 0.0) / n
+        v = max(0.0, o.get("advq_sq", 0.0) / n - m * m)
+        return float(np.sqrt(v / n))
+
+    # ── 三态 epistemic state ────────────────────────────────────────
+    # ── A 类动力学 cumulant(阶段四)────────────────────────────────
+    def _rr_dval(self, s, a, s2):
+        """A 类 cumulant 的**行前读数**(用更新前的表 —— 先预测再观测)。
+
+        三条共同契约(leo 的四条要求里最硬的两条):
+          · 每一步都能在线获得 —— 只看刚发生的真实转移;
+          · **不用目标坐标、不用真实模型、不用未来标签** —— 只有
+            `(s, a, s2)` 三元组的计数, agent 自己走出来的;
+          · 统一方向 = "压力", 越大越差, ⇒ 天然不可能被读成"值"。
+        """
+        if self.rr_dyn == "none":
+            return 0.0
+        d = self._rr_T.get((int(s), int(a)))
+        n = sum(d.values()) if d else 0
+        if self.rr_dyn == "N":
+            # ★ **控制量: 新颖度**。`1/(1+n(s,a))`, 用**更新前**的计数。
+            #   它必须与 A1/A2/A3 **走同一套管道**(同一个 _rr_dval/_rr_dacc/
+            #   基线与判据), 否则"A 与 N 有没有分开"比的是实现差异而不是语义。
+            #   方向同样统一成"压力": 越新 -> 越大。
+            return float(1.0 / (1.0 + n))
+        if self.rr_dyn == "A1":
+            # ★ A1 = **转移预测误差**(按 leo 的 A′ 规格)。
+            #   语义: 用**更新前**的模型预测这一步会落在哪, 再看实际落在哪。
+            #   ⇒ "意外度" = 1 − p̂_prev(实际后继 | s,a)。
+            #   ★ 这是**可预测性**, 不是任务价值 —— 一个稳定把你带向
+            #     错误方向的动作照样很容易预测(leo 点名的那条)。
+            #   ★ 与 A2 的分工: A1 对**分布翻转**敏感(A2 不敏感),
+            #     A2 对**支撑集扩张**敏感(A1 也敏感) —— 两者在翻转环境上
+            #     **必然分歧**, 这正是检验"它们是不是同一个量"的机会。
+            #
+            #   注意: 本分支与 A2 早先**写反了**(旧 A1 = 熵, 旧 A2 = 1−p̂)。
+            #   在 A′ 里按 leo 规格对齐: A1 = 预测误差, A2 = 不确定性。
+            if n < 2:
+                return 1.0          # 无先验 ⇒ 没有"预测"可供做错, 报未知
+            return float(1.0 - d.get(int(s2), 0) / n)
+        if self.rr_dyn == "A2":
+            # ★ A2 = **转移不确定性** = 观测到的后继分布归一化熵。
+            #   ★ 关键区别: 熵对 **{0.9,0.1} 与 {0.1,0.9} 给出同一个数**,
+            #     所以分布翻转时 A2 **不跳** —— 这是 A1 ≠ A2 的结构性证据。
+            #   ★ 但 A2 对"支撑集扩张"(0.9/0.1 -> 0.5/0.5) 敏感。
+            if n < 2:
+                return 1.0          # 见过的样本不足 ⇒ 报最大不确定
+            p = np.array(list(d.values()), float)
+            p /= p.sum()
+            return float(-(p * np.log(p + 1e-12)).sum()
+                         / np.log(max(2, getattr(self.mdp, "n_states", 32))))
+        # A3 离开已知稳定动力学区域: 落点的**出发边平均熵**(归一化)。
+        #   ★ 方向必须与 A1/A2 一致 = "压力"(越大越差)。第一版写成了
+        #     `1 - 熵`, 返回的是**熟悉度** —— 与通道约定相反, 于是读数恒
+        #     1.000(确定性 MDP 里熵恒 0)、永不触发。这是"通道方向写反"
+        #     的典型样子: 指标看起来在动, 但基线与判据读的是相反的量。
+        ns = int(s2)
+        if self._rr_vis.get(ns, 0) == 0:
+            return 1.0                                  # 全新状态 -> 最大压力
+        ents = []
+        # 用**观测到的**出边动作, 不硬编码 (0,1) —— 第一版漏掉了 GRAB/OPEN,
+        # 而 KeyDoor 的动作是 LEFT/RIGHT/GRAB/OPEN 四个。
+        acts = {a2 for (ns2, a2) in self._rr_T if ns2 == ns}
+        for a2 in (sorted(acts) if acts else (0, 1)):
+            dd = self._rr_T.get((ns, int(a2)))
+            nn = sum(dd.values()) if dd else 0
+            if nn >= 2:
+                pp = np.array(list(dd.values()), float)
+                pp /= pp.sum()
+                ents.append(float(-(pp * np.log(pp + 1e-12)).sum()))
+        if not ents:
+            return 1.0                                  # 出边一条都没摸过
+        return float(min(1.0, np.mean(ents)
+                         / np.log(max(2, getattr(self.mdp, "n_states", 32)))))
+
+    def _rr_dstep(self, s, a, s2):
+        """把这一步的真实转移记进在线转移表 —— **失败时这行照样执行**。"""
+        k = (int(s), int(a))
+        d = self._rr_T.get(k)
+        if d is None:
+            d = self._rr_T[k] = {}
+        d[int(s2)] = d.get(int(s2), 0) + 1
+        self._rr_vis[int(s2)] = self._rr_vis.get(int(s2), 0) + 1
+        self._rr_dn += 1
+
+    def _rr_dacc(self, name, d):
+        """把读数记到 **具体 option** 的台账 + 全段基线。"""
+        L = self._rr_dense.get(name)
+        if L is None:
+            L = self._rr_dense[name] = [0.0, 0.0, 0.0]
+        L[0] += 1.0
+        L[1] += d
+        L[2] += d * d
+        B = self._rr_dseg
+        B[0] += 1.0
+        B[1] += d
+        B[2] += d * d
+
+    def _rr_dyn_bad(self, name):
+        """A 类风险判据: 该 option 的动力学压力是否**显著高于本段基线**。
+
+        尺度**���全由数据自己的方差给出**(两样本 SE), 不引入手工 ε ——
+        与 leo 在 inert 上要求的"'接近零'必须使用健康段自身的方差定义"同一条。
+        """
+        if self.rr_dyn == "none":
+            return False
+        L = self._rr_dense.get(name)
+        if L is None or L[0] < self.rr_min_launches:
+            return False
+        Bn, Bs, Bs2 = self._rr_dseg
+        if Bn < 20 or Bn <= L[0]:
+            return False
+        m = L[1] / L[0]
+        v = max(0.0, L[2] / L[0] - m * m)
+        bm = Bs / Bn
+        bv = max(0.0, Bs2 / Bn - bm * bm)
+        se = math.sqrt(v / L[0] + bv / Bn)
+        return (m - bm) > self.rr_dyn_c * se
+
+    def rr_dyn_stats(self):
+        """A 类通道的报告: 证据量 / 均值 / 是否触发风险。"""
+        Bn, Bs, Bs2 = self._rr_dseg
+        bm = Bs / Bn if Bn else 0.0
+        per = {}
+        for k in sorted(self._rr_dense):
+            L = self._rr_dense[k]
+            m = L[1] / L[0] if L[0] else 0.0
+            per[k] = {"n": int(L[0]), "mean": round(m, 4),
+                      "risk": bool(self._rr_dyn_bad(k))}
+        return {"kind": self.rr_dyn, "transitions": int(self._rr_dn),
+                "base_mean": round(bm, 4), "base_n": int(Bn), "per_option": per}
+
+    def rr_starved(self):
+        """奖励流是否为空 —— 势函数不可能在学东西。
+
+        ★ 这是本轮最重要的那个门。实测: harm 故障下整臂全灭时
+        `Q_adv ≡ 0.0000` **精确为零** —— 不是"没有显著差异", 是"根本没记账"
+        (到不了终点 -> 无奖励 -> Φ 恒为 0 -> 证据门 `_rr_has_base` 挡掉一切)。
+        不加这个门, 系统会把"我不知道"读成"没问题" —— **自欺**。
+        """
+        return self.rr_since_rew >= self.rr_starve_steps
+
+    def rr_epistemic(self, o):
+        """**三态判定**: `"good"` / `"bad"` / `"unknown"`。
+
+        与旧 `rr_broken` 的关键区别: **"未知"不是"好"**。
+        旧代码 `advq = 0 -> 不 < 0 -> 不淘汰 -> 当作健康`, 而在奖励流为空时
+        `advq` 恰好是精确的 0 —— 于是"没有证据"被系统性地读成"没问题"。
+
+        判据(与 leo 定的契约一致):
+          未知  —— 奖励流为空 / 势函数未离开初值 / 证据量不足(< min_launches)
+          坏    —— 证据充分, 且**上置信界 < 0**(显著更差)
+          好    —— 证据充分, 且没有显著负向信号
+        """
+        if self.rr_starved():
+            return "unknown"                      # Φ 学不到 -> 无有效预测证据
+        n = o.get("advq_n", 0.0)
+        if n < self.rr_min_launches:
+            return "unknown"                      # 证据不足
+        m = self._rr_advq_of(o)
+        if m + self.rr_ucb_c * self._rr_advq_se(o) < 0.0:
+            return "bad"
+        # ★★ **反熟悉度保证**: A 类动力学证据**只能降级(好 -> 坏)**,
+        #    **永远不能升级(未知 -> 好)**。也就是说"可预测"买不到"好" ——
+        #    否则一个稳定把你带向错误方向的 option 会因为好预测而被判好。
+        #    这条不是调出来的, 是设计约束: A 类是**风险通道**, 不是值信号。
+        #    (它到底能不能当值信号, 由"稳定但错误"否证实验来判。)
+        nm = o.get("name")
+        if nm is not None and self._rr_dyn_bad(nm):
+            return "bad"
+        # ── 阶段五: 证据库(★ **只降级, 不升级**)──────────────────────
+        #   与 A 类同一条不对称约束: 证据可以投 `bad`, 但**永远不能**把状态升成
+        #   `good`。理由: 预测误差低只说明"我预测得准", 不说明"这件事有价值";
+        #   而**新颖度会拉高误差** ⇒ 允许升级就等于允许新颖度伪造"好"。
+        #   ⇒ 证据缺席不改变判定, 证据示警才降级。
+        if self.rr_bank is not None:
+            self.rr_ev_last = self.rr_bank.support(step=self.rr_ev_step,
+                                                   regime=self.rr_regime_idx)
+            if self.rr_ev_last.get("verdict") == "bad":
+                self.rr_ev_bad_n += 1
+                return "bad"
+        return "good"
+
+    def rr_ev_support(self):
+        """★ 最近一次证据判定背后的**引用清单** —— 哪条支持 bad / 哪条缺席。
+
+        这是"证据可追溯"的直接接口: 调用方拿到的不是分数, 是**来源**。
+        """
+        if self.rr_bank is None:
+            return {"enabled": False}
+        s = self.rr_bank.support(step=self.rr_ev_step, regime=self.rr_regime_idx)
+        s["enabled"] = True
+        s["n_bad_ever"] = int(self.rr_ev_bad_n)
+        return s
+
+    def rr_complementarity(self, label="reward"):
+        """★ 这组 GVF 到底有没有产生**互补证据**。
+
+        `label`: 用哪个 cumulant 的二值化当"变化/未变化"标签。
+        默认 `"reward"` ⇒ 问的是「这组证据在**奖励到达**这件事上互不互补」。
+
+        ⚠ 口径限制(必须写明): 标签本身就是四个 cumulant 之一,
+        所以对 `reward` 那条 GVF 天然有利。读 `complementarity` 时要同时看
+        `auc_i`(**单条**的 AUC)与 `corr_err`(冗余度), 不能只看差值。
+
+        **允许结论是"冗余"** —— 那就照实报冗余。
+        """
+        if self.rr_bank is None:
+            return {"enabled": False}
+        from hibs_lnn.evidence_bank import complementarity
+        h = self.rr_bank.z_history()
+        if label not in h["cumulant"]:
+            return {"enabled": True, "error": f"unknown label {label}",
+                    "labels": list(h["cumulant"])}
+        lab = (h["cumulant"][label] > 0).astype(int)
+        if lab.min() == lab.max():
+            return {"enabled": True, "error": "标签全为同一值, 无法算 AUC",
+                    "label": label, "n": int(lab.size)}
+        r = complementarity(h["z"], lab, z_bad=self.rr_ev_z_bad)
+        r.update({"enabled": True, "label": label, "n": int(lab.size),
+                  "pos_rate": float(lab.mean())})
+        return r
+
+    def rr_epistemic_all(self, names=None):
+        return {k: self.rr_epistemic(o) for k, o in self.rr_outcome.items()
+                if names is None or k in names}
+
+    def _rr_sync_states(self):
+        """把三态判定同步进台账, 并**计数退休/恢复**。
+
+        为什么必须分开记: leo 的契约里 `当前状态` 用于**决策**,
+        `历史状态` 用于**审计** —— 一个 option 被判坏过几次、又恢复过几次,
+        是"持续学习是否真的在发生"的直接证据, 不能被当前状态覆盖掉。
+        """
+        for k, o in self.rr_outcome.items():
+            st = self.rr_epistemic(o)
+            old = self._rr_prev_state.get(k)
+            if old is not None and st != old:
+                if st == "bad":
+                    o["retired_n"] = o.get("retired_n", 0) + 1
+                elif old == "bad":
+                    o["recovered_n"] = o.get("recovered_n", 0) + 1
+            self._rr_prev_state[k] = st
+            o["state"] = st
+        if self.rr_starved():
+            self.rr_starve_ever += 1
+
+    def _rr_settle(self, st, steps, reason, s0=None, s1=None,
+                   r_opt=0.0, done=False):
+        self.rr_stats["terms"][reason] = self.rr_stats["terms"].get(reason, 0) + 1
+        self.rr_stats["durations"].append(int(steps))
+        # ★ 归属到**这个 option**(此前 `st` 收下即弃 —— 库级台账不存在)
+        o = self.rr_outcome.setdefault(getattr(st, "name", id(st)),
+                                       {"n": 0, "reached": 0, "steps": 0,
+                                        "name": getattr(st, "name", None),
+                                        "n_eff": 0.0, "reached_eff": 0.0,
+                                        "steps_eff": 0.0,
+                                        "adv_sum": 0.0, "adv_steps": 0.0,
+                                        "advq_sum": 0.0, "advq_n": 0.0,
+                                        "advq_sq": 0.0})
+        dec = self._rr_decay()
+        hit = 1.0 if reason == "beta_at_feature" else 0.0
+        # 终身计数(永不衰减, 供报告与判据门限用)
+        o["n"] += 1
+        o["steps"] += int(steps)
+        o["reached"] += int(hit)
+        # 有效计数(按 rr_forget_hl 指数遗忘; dec=1.0 时逐位等于终身计数)
+        o["n_eff"] = dec * o["n_eff"] + 1.0
+        o["reached_eff"] = dec * o["reached_eff"] + hit
+        o["steps_eff"] = dec * o["steps_eff"] + int(steps)
+        # 势函数差分(旧方案; 保留作对照)
+        prog = self._rr_pot(s1) - self._rr_pot(s0)
+        o["adv_sum"] = dec * o["adv_sum"] + prog
+        o["adv_steps"] = dec * o["adv_steps"] + max(1, int(steps))
+        # ★ SMDP 更新 + advantage 记账(新方案; 在线、无 oracle)
+        if s0 is not None and s1 is not None:
+            name = getattr(st, "name", None)
+            if name is not None:
+                j = self._rr_oindex(name)
+                qo = self.q_opt
+                assert qo is not None          # _rr_oindex 已建表
+                g, k = float(self.q.gamma), max(1, int(steps))
+                # ★ bootstrap 用**势函数** Φ: 它才是"agent 现在认为走到某状态值多少"
+                #   的在线估计。`gvf` 时它是中性初始化独立学的状态价值,
+                #   没有"未试过的动作把 max 顶在初值"这个病。
+                boot = 0.0 if done else (g ** k) * self._rr_pot(s1)
+                tgt = float(r_opt) + boot
+                qo[s0, j] += self.q.lr * (tgt - qo[s0, j])
+                # ★ 只在**势函数对该状态有证据**时记账 —— 否则比的是初值的形状
+                if self._rr_has_base(s0):
+                    advq = float(qo[s0, j]) - self._rr_pot(s0)
+                    o["advq_sum"] = dec * o["advq_sum"] + advq
+                    o["advq_sq"] = dec * o.get("advq_sq", 0.0) + advq * advq
+                    o["advq_n"] = dec * o["advq_n"] + 1.0
+                else:
+                    o["no_base"] = o.get("no_base", 0) + 1
+
+    # ── 自我校准: 检测 + 淘汰 ───────────────────────────────────────
+    def rr_broken(self, names=None):
+        """哪些 option 的**终止机制坏了**(而不是"暂时运气差")。
+
+        判据(事前定义, 只看 option 自己的达成率, 不看主任务表现):
+            启动 >= `rr_min_launches` 次 且 达成率 < `rr_calib_min_rate`
+
+        ## 为什么不是 `reached == 0`
+
+        最初的写法是"从没达成过"(绝对零)。这是错的 —— **连 L2 的真案都
+        抓不到**: L2 是 57 启动 / 1 次 goal_reached, 达成率 0.018, 不是 0。
+        绝对零判据会放过它。
+
+        ## 0.5 这个线的依据(来自实测的两个簇, 不是拍脑袋)
+
+            坏的:  L2 真案 0.018 (56/57 expired)  |  本轮制造器 0.250
+            好的:  rr[key] 1.000 (确定性 MDP + 模型导出的 π_o 应当几乎必成)
+                   rr-zeroV 0.595 (健康但偏早停的臂)
+
+        两个簇之间有一大段空档, 0.5 落在空档里。**确定性 MDP 上模型导出的
+        option 本该接近 1.0**, 明显低于 1.0 就意味着终止机制或 π_o 有问题。
+        """
+        out = set()
+        for k, o in self.rr_outcome.items():
+            if names is not None and k not in names:
+                continue
+            if o.get("n_eff", float(o.get("n", 0))) < self.rr_min_launches:
+                continue
+            bad_int = self._rr_rate(o) < self.rr_calib_min_rate
+            bad_adv = self._rr_adv(o) < self.rr_calib_min_adv
+            # advq 额外要求**基线证据够** + **显著更差**:
+            #   ★ 判据必须是 "上置信界 < 0"(显著更差), 不是 "均值 < 0"。
+            #   实测量到 Q_adv = −0.0002 —— 那是**零的噪声范围之内**,
+            #   严格 `< 0` 会把每一个 option 都判坏(fallback 0.994)。
+            #   证据不足时不许处决 —— 这正是"犯错是可以原谅的"的统计版本,
+            #   而且它不需要任何手工 epsilon: 尺度由数据自己的方差给出。
+            advq_mean = self._rr_advq_of(o)
+            bad_q = (o.get("advq_n", 0.0) >= self.rr_min_launches
+                     and advq_mean + self.rr_ucb_c * self._rr_advq_se(o) < 0.0)
+            # ★ 三态: "未知"**永远不算坏** —— 证据不足 / 奖励流为空都不处决。
+            #   这是"退休必须保守"的原则: 宁可留着不确定的, 不可错杀。
+            if self.rr_three_state and self.rr_epistemic(o) == "unknown":
+                bad_q = False
+            rule = self.rr_retire_rule
+            if rule == "none":              # 诊断臂: 只报数, 不淘汰
+                hit = False
+            elif rule == "internal":
+                hit = bad_int
+            elif rule == "adv":
+                hit = bad_adv
+            elif rule == "advq":            # ★ 在线可用: 只需 agent 自己的 Q
+                hit = bad_q
+            elif rule == "both":
+                hit = bad_int and bad_q
+            elif rule == "all":
+                hit = bad_int and bad_adv and bad_q
+            else:
+                hit = bad_int or bad_q
+            if hit:
+                out.add(k)
+        return out
+
+    def rr_calib_stats(self):
+        """校准台账: 每个 option 的启动数 / **当前胜任度** / 效率 + 谁被判坏了。
+
+        注意 `rate` 报的是**有效达成率**(按 `rr_forget_hl` 遗忘后的当前胜任度),
+        `rate_life` 才是终身平均 —— 持久化的意义就在这两者的差别上。
+        """
+        per = {}
+        for k, o in sorted(self.rr_outcome.items()):
+            ne = o.get("n_eff", float(o.get("n", 0)))
+            m = self._rr_advq_of(o)
+            se = self._rr_advq_se(o)
+            per[k] = {
+                # ── 当前判定(用于决策)──────────────────────────────
+                "state": self.rr_epistemic(o),
+                # ── 证据量 ──────────────────────────────────────────
+                "n": o["n"],
+                "n_eff": round(ne, 2),
+                "advq_n": round(o.get("advq_n", 0.0), 2),
+                "no_base": o.get("no_base", 0),   # 有启动但没进比较的次数
+                # ── 近期状态(遗忘加权)─────────────────────────────
+                "rate": round(self._rr_rate(o), 4),
+                "advq": round(m, 4),
+                "advq_se": round(se, 4),
+                "advq_lo": round(m - self.rr_ucb_c * se, 4),   # 下置信界
+                "advq_hi": round(m + self.rr_ucb_c * se, 4),   # 上置信界
+                "eff": round(self._rr_eff(o), 4),
+                "adv": round(self._rr_adv(o), 4),
+                # ── 历史状态(用于审计; 与当前状态分开)────────────
+                "reached": o["reached"],
+                "rate_life": round(o["reached"] / o["n"], 4) if o["n"] else 0.0,
+                "retired_n": o.get("retired_n", 0),      # 被判坏过几次
+                "recovered_n": o.get("recovered_n", 0),  # 从坏恢复过几次
+                "mean_steps": round(o["steps"] / o["n"], 2) if o["n"] else 0.0,
+            }
+        broke = self.rr_broken()
+        states = [v["state"] for v in per.values()]
+        return {
+            "per_option": per, "broken": sorted(broke), "n_broken": len(broke),
+            # ★ 三态汇总 + 自欺门的状态 —— 报告层必须能一眼看出
+            #   "这次是真的没问题" 还是 "这次根本没数据"。
+            "states": {"good": states.count("good"),
+                       "bad": states.count("bad"),
+                       "unknown": states.count("unknown")},
+            "starved": bool(self.rr_starved()),
+            # ★ 阶段五: 证据库 —— 报的是**引用清单**不是分数
+            "evidence": (self.rr_ev_support() if self.rr_evidence else {"enabled": False}),
+            "since_rew": int(self.rr_since_rew),
+            "starve_steps": int(self.rr_starve_steps),
+            "starve_ever": int(self.rr_starve_ever),
+            "sel_starved": self.rr_stats.get("starved_sel", 0),
+            "sel_unk_probe": self.rr_stats.get("unk_probe", 0),
+            "sel_forgiven": self.rr_stats.get("forgiven", 0),
+        }
+
+    def _rr_usage(self):
+        """各 option 的**使用占比**(校准的直接观测量)。"""
+        tot = sum(o["n"] for o in self.rr_outcome.values())
+        if not tot:
+            return {}
+        return {k: round(o["n"] / tot, 4) for k, o in sorted(self.rr_outcome.items())}
+
+    # ── 台账 ────────────────────────────────────────────────────────
+    def rr_bookkeeping(self):
+        d = list(self.rr_stats["durations"])
+        base = self.rr_stats["stall_baseline"]
+        return {
+            "recomputes": self.rr_stats["recomputes"],
+            "selections": self.rr_stats["selections"],
+            "exec_steps": self.rr_stats["exec_steps"],
+            "terms": dict(self.rr_stats["terms"]),
+            "rebuilds": self.rr_stats["rebuilds"],
+            "n_options": 0 if self.rr_lib_obj is None else len(self.rr_lib_obj),
+            "mean_duration": float(np.mean(d)) if d else 0.0,
+            "max_duration": int(np.max(d)) if d else 0,
+            "horizon": int(self.mdp.horizon),
+            # ★ lock-in 检: 平均执行时长接近整回合 = 不是抽象而是锁死。
+            #   阈值取自 option 自身名义时长, 所以也一并报出来。
+            "lockin_ratio": (float(np.mean(d)) / max(1, self.mdp.horizon)) if d else 0.0,
+            "max_cap": (int(max(self._rr_cap.values())) if self._rr_cap else 0),
+            "stall_trigger_frac": (float(np.sum([1 for b in base if b >= self.stall_patience])) / max(1, len(base))) if base else 0.0,
+            "beta_nonempty": 0 if self.rr_lib_obj is None else
+                             int(sum(int(np.sum(o.beta)) for o in self.rr_lib_obj)),
+        }

hibs_lnn/rr_options.py

@@ -0,0 +1,278 @@
+# -*- coding: utf-8 -*-
+"""Reward-respecting subtask options on `KeyDoorMDP`(OaK 的第一步)。
+
+论文:Sutton et al. 2022, *Reward-Respecting Subtasks for Model-Based
+Reinforcement Learning*(arXiv:2202.03466)。
+
+## 层序(不可颠倒, 见 `docs/oak_diagnosis_from_papers.md`)
+
+    SubTask ──> Option ──> Option model ──> Planning
+    (c, z)      (π_o,β_o)    SMDP model      planner
+
+本项目此前一直从**转移图**出发(bottleneck / 介数中心性 / 最短路),那正是论文
+点名的**最差类别**:"option models from ... shortest path options based on
+bottleneck states ... are much less likely to be useful in planning"。
+这个模块把驱动层换回 **SubTask**。
+
+## 子任务的定义(论文式(4))
+
+    c(s,a) = R(s,a)                          ← **与主任务完全相同的奖励**
+    z_i(s) = V_main(s) + (w̄_i − w_i)·x_i(s)   ← 只在 x_i(s)=1 处允许停
+             └────────── stopping bonus ──────────┘
+
+`w_i` 是**特征 i 在主任务价值函数里的权重**(一热特征下 = 该特征为 1 诸状态上
+`V_main` 的均值),不是常数 1。硬写 `w_i = 1` 会让 bonus 恒 0 → `z ≡ V_main`
+→ `β_o` 处处为空 → option 永不停止 → 与 shortest-path 给出逐位相同的曲线。
+""" 
+
+import numpy as np
+
+from hibs_lnn.skill_mdp import N_ACT
+from hibs_lnn.subtask_options import (
+    STOP,
+    Subtask,
+    reward_respecting_subtask,
+    shortest_path_subtask,
+)
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 1. KeyDoor 的表格视图 —— 给 Subtask.solve 提供 (T, R, is_goal)
+# ══════════════════════════════════════════════════════════════════════
+
+class KeyDoorTabular:
+    """`KeyDoorMDP` 的**表格**表示。
+
+    KeyDoor 的动力学完全确定性, 所以 `T[s][a] = [(1.0, s')]`;唯一随 regime
+    改变的是 `is_goal`(目标判定含 `goal_pos < door_pos` 的免钥匙情形)与 `R`
+    (进目标得 +1)。**因此本对象必须按 regime 重建**, 不能跨 regime 复用。
+
+    接口刻意与 `subtask_options.py` 里 gridworld 的环境对象**逐字一致**
+    (`n_states` / `T` / `R` / `is_goal` / `gamma`), 这样 `Subtask.solve`
+    与 `reward_respecting_subtask` 可以原样复用, 不必为 KeyDoor 另写一份。
+    """
+
+    def __init__(self, mdp, gamma=0.95):
+        self.gamma = float(gamma)
+        self.regime = tuple(mdp.regime)
+        self.n_pos = int(mdp.n_pos)
+        self.n_states = int(mdp.n_states)
+        key_pos, door_pos, goal_pos = self.regime
+
+        # 目标状态: 与 KeyDoorMDP._reached() 同一判据
+        def is_term(s):
+            pos, _hk, do = s // 4, (s // 2) % 2, s % 2
+            return pos == goal_pos and (do or goal_pos < door_pos)
+
+        self.is_goal = np.array([is_term(s) for s in range(self.n_states)],
+                                dtype=bool)
+
+        self.T = [[None] * N_ACT for _ in range(self.n_states)]
+        self.R = np.zeros((self.n_states, N_ACT), dtype=float)
+        for s in range(self.n_states):
+            pos, hk, do = s // 4, (s // 2) % 2, s % 2
+            for a in range(N_ACT):
+                np_, nhk, ndo = pos, hk, do
+                if a == 0:                      # LEFT
+                    np_ = max(0, pos - 1)
+                elif a == 1:                    # RIGHT
+                    np_ = min(self.n_pos - 1, pos + 1)
+                elif a == 2:                    # GRAB
+                    if pos == key_pos and not hk:
+                        nhk = 1
+                elif a == 3:                    # OPEN
+                    if pos == door_pos and hk and not do:
+                        ndo = 1
+                ns = np_ * 4 + nhk * 2 + ndo
+                self.T[s][a] = [(1.0, ns)]
+                self.R[s][a] = 1.0 if self.is_goal[ns] else 0.0
+        self.regime_key = self.regime
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 2. 特征向量与主任务价值
+# ══════════════════════════════════════════════════════════════════════
+
+def feature_vectors(mdl: KeyDoorTabular):
+    """KeyDoor 的**子成就特征**: 「拿到钥匙」与「打开门」。
+
+    这两个是任务链上真正的中间成果(key → door → goal), 对应论文里
+    "the features are the sub-achievements of the task" 的取法。
+    """
+    n = mdl.n_states
+    x_key = np.array([(s // 2) % 2 for s in range(n)], dtype=float)
+    x_door = np.array([s % 2 for s in range(n)], dtype=float)
+    return {"key": x_key, "door": x_door}
+
+
+def main_value(mdl: KeyDoorTabular, max_sweeps=5000, tol=1e-12):
+    """主任务的最优价值 `V_main`(精确价值迭代)。
+
+    ★ 与 `Subtask.solve` 用**同一套约定**: 目标状态价值为 0, 其余
+      `V(s) = max_a [ R(s,a) + γ V(s') ]`。两处约定一致是硬要求 ——
+      否则 `z_i(s) = V_main(s) + bonus` 里的 `V_main` 与子任务自身
+      的价值不在同一把尺子上, `β_o` 会在错误的地方触发。
+    """
+    n = mdl.n_states
+    V = np.zeros(n)
+    for _ in range(max_sweeps):
+        delta = 0.0
+        Vn = V.copy()
+        for s in range(n):
+            if mdl.is_goal[s]:
+                Vn[s] = 0.0
+                continue
+            best = -np.inf
+            for a in range(N_ACT):
+                if mdl.T[s][a] is None:
+                    continue
+                val = mdl.R[s][a] + mdl.gamma * V[mdl.T[s][a][0][1]]
+                if val > best:
+                    best = val
+            Vn[s] = best
+            delta = max(delta, abs(Vn[s] - V[s]))
+        V = Vn
+        if delta < tol:
+            break
+    return V
+
+
+def optimal_policy(mdl: KeyDoorTabular):
+    """主任务最优策略(诊断用: 给 T_adapt 阈值与 sanity check)。"""
+    V = main_value(mdl)
+    n = mdl.n_states
+    pol = np.full(n, STOP, dtype=int)
+    for s in range(n):
+        if mdl.is_goal[s]:
+            continue
+        best_a, best_v = STOP, -np.inf
+        for a in range(N_ACT):
+            val = mdl.R[s][a] + mdl.gamma * V[mdl.T[s][a][0][1]]
+            if val > best_v:
+                best_a, best_v = a, val
+        pol[s] = best_a
+    return V, pol
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 3. 子任务库的构造
+# ══════════════════════════════════════════════════════════════════════
+
+def build_rr_library(mdl: KeyDoorTabular, V_main, bonus_weight=1.0,
+                     feats=("key", "door"), cumulant="reward",
+                     z_mode="rr"):
+    """构造 reward-respecting 子任务库并**解出** option。
+
+    参数就是消融的旋钮 —— 每个旋钮对应矩阵里的一个臂:
+
+      `z_mode`    "rr"      → `z = V_main + (w̄ − w_i)x_i`   (机制本体)
+                  "zeroV"   → `z = 0     + (w̄ − 0 )x_i`   (削掉价值函数)
+                  "nobonus" → `w̄ = w_i` → bonus ≡ 0        (削掉停止奖励)
+      `cumulant`  "reward"  → `c = R`(reward-respecting)
+                  "zero"    → `c = 0`(纯"到达特征", 丢掉沿途目标)
+    """
+    feats_all = feature_vectors(mdl)
+    lib = []
+    for name in feats:
+        x = feats_all[name]
+        if z_mode == "rr":
+            st = reward_respecting_subtask(mdl, x, V_main,
+                                           bonus_weight=bonus_weight)
+        elif z_mode == "zeroV":
+            # 削掉价值函数: V_main ≡ 0。此时 z 只剩 bonus 项,
+            # "停"与"继续"不再由主任务价值定价 —— 这正是用户猜测的
+            # "可能是价值函数的原因" 的**直接检验臂**。
+            z0 = np.zeros_like(np.asarray(V_main, dtype=float))
+            st = reward_respecting_subtask(mdl, x, z0,
+                                           bonus_weight=bonus_weight)
+        elif z_mode == "nobonus":
+            # w̄ = w_i → bonus ≡ 0 → z ≡ V_main → 论文警告的退化情形。
+            # 这一臂**预期**表现为 option 永不提前停(β_o 空), 是 harness
+            # 的"已知负向"校准点(Pitfall 35 / §9.3 第三条)。
+            on = np.asarray(x, dtype=float) > 0
+            wi = float(np.mean(np.asarray(V_main, dtype=float)[on])) if on.any() else 0.0
+            st = reward_respecting_subtask(mdl, x, V_main, bonus_weight=wi)
+        else:
+            raise ValueError(f"unknown z_mode: {z_mode}")
+
+        if cumulant == "zero":
+            st.c_fn = (lambda s, a: 0.0)      # 丢掉沿途主任务奖励
+        elif cumulant != "reward":
+            raise ValueError(f"unknown cumulant: {cumulant}")
+
+        st.name = f"rr[{name}]"
+        st.feature = x
+        st.solve(mdl)
+        lib.append(st)
+    return lib
+
+
+def build_bottleneck_library(mdl: KeyDoorTabular, subgoal_state=None):
+    """**已知弱基线(负对照)**: 从瓶颈/子目标状态出发的 shortest-path subtask。
+
+    `c = −1`, `z = 0` 只在子目标处 —— 它优化的是"**到达**",完全无视任务目标。
+    它在这里的**正确行为就是不比什么都不做好**, 所以它同时是 harness 的
+    负向校准点(§9:一个已知负向的臂必须复现为负)。
+    """
+    if subgoal_state is None:
+        # 瓶颈 = 门所在的格(拿钥匙后必须经过) —— 或用割点思想选
+        door_pos = mdl.regime[1]
+        subgoal_state = min(mdl.n_states - 1, door_pos * 4 + 2)   # (door, has_key, closed)
+    st = shortest_path_subtask(mdl, subgoal_state)
+    st.name = f"bottleneck[{subgoal_state}]"
+    st.feature = np.zeros(mdl.n_states)
+    st.solve(mdl)
+    return [st]
+
+
+def build_random_goal_library(mdl: KeyDoorTabular, V_main, seed=0,
+                              n_goals=2, bonus_weight=1.0):
+    """**随机目标(负对照)**: 目标状态随机取, 其余同 reward-respecting。
+
+    论文 Fig.1 的第三条曲线。用来检验"收益是不是来自目标**选得好**,
+    而不是来自'有一个可停止的子任务'这件事本身"。
+    """
+    rng = np.random.RandomState(seed)
+    lib = []
+    cand = [s for s in range(mdl.n_states) if not mdl.is_goal[s]]
+    for i in range(n_goals):
+        g = int(cand[rng.randint(len(cand))])
+        x = np.zeros(mdl.n_states)
+        x[g] = 1.0
+        st = reward_respecting_subtask(mdl, x, V_main,
+                                       bonus_weight=bonus_weight)
+        st.name = f"random[{g}]"
+        st.feature = x
+        st.solve(mdl)
+        lib.append(st)
+    return lib
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 4. 启动集 I_o 与选择
+# ══════════════════════════════════════════════════════════════════════
+
+def initiation_ok(st: Subtask, s: int) -> bool:
+    """`I_o(s)`: 只有当**特征尚未达成**且**在 s 停止不是最优**时才允许启动。
+
+    "特征已达成"= `x_i(s) > 0`(如 has_key=1)。已经拿到钥匙还去执行
+    "拿钥匙"的 option 是空转;论文的 initiation set 正是排除这类状态。
+    """
+    x = getattr(st, "feature", None)
+    if x is None:
+        return True
+    return float(x[s]) <= 0.0
+
+
+def option_gain(st: Subtask, s: int, V_main) -> float:
+    """选择用的**增益**: 该 option 承诺的价值超出主任务价值多少。
+
+    只在可启动处有意义;不可启动返回 `-inf`。选择 = `argmax` 这个量,
+    这就是"哪个子任务现在最值得追"。
+    """
+    if st.value is None or not initiation_ok(st, s):
+        return -np.inf
+    v = float(st.value[s])
+    if not np.isfinite(v):
+        return -np.inf
+    return v - float(np.asarray(V_main)[s])

hibs_lnn/skill_agent.py

@@ -0,0 +1,338 @@
+"""skill_agent.py — 在 KeyDoorMDP 上做 B 矩阵的智能体。
+
+## 要回答的问题 (用户 2026-09-14 框架里的 H5 + 复用)
+
+    "Option 是否保存了可以重新利用的经验?"
+
+即 A→B→C→A→B→C 反复漂移时, 是否出现
+
+        T_A^(2) < T_A^(1),   T_A^(3) < T_A^(2)
+
+## 公平对照的两个设计要点
+
+1. **两个 agent 都保留 Q 表** (跨 regime 不重置)
+   否则"复用"测的是"有没有记忆", 而不是"option 有没有带来额外的可复用结构"。
+   我们要隔离的是 **option 库** 的额外贡献。
+
+2. **相同计算预算**: option agent 的额外开销是"拟合世界模型 + 发现 option",
+   所以给它和 primitive 相同数量的**环境交互**。
+   测的是 **样本效率 R(N)**, 不是"跑得更久所以更好"。
+
+## 关键: regime 变化后 option 库会不会失效?
+
+一个 regime = (key_pos, door_pos, goal_pos)。换 regime 后:
+  - **技能本身仍然成立** ("走到 key 位置并抓取" 这个**行为模式**没变)
+  - 但**地点变了** -> 旧 option 的 goal_center 是**过期的**
+
+所以本实现区分两种 option 使用方式:
+  - `reuse_stale`  : 直接用旧 option (预期: 会被过期目标拖累)
+  - `rediscover`   : 换 regime 后**重新发现**, 但库不清空 (预期: 应该更快)
+这正好对应"技能可复用"的两种理解, 也是判据所在。
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from hibs_lnn.skill_mdp import N_ACT, KeyDoorMDP  # noqa: E402
+from hibs_lnn.uncertainty_gate import TabularTransition  # noqa: E402
+
+
+class QLearner:
+    """表格 Q-learning (跨 regime 保留 Q 表 —— 这是"记忆"基线)。"""
+
+    def __init__(self, n_states, n_act=N_ACT, lr=0.2, gamma=0.95,
+                 eps=0.15, seed=0, q_init=1.0):
+        # ★ **乐观初始化** —— 稀疏奖励下这是必需的, 不是调参技巧。
+        #   若 Q 全为 0, `argmax` 恒返回动作 0, agent 会**一直做同一个动作**
+        #   (实测: 在 KeyDoor 上一直 left, 卡在 pos 0), 只有 ε-随机步才动,
+        #   于是几乎永远到不了目标 -> 600 回合成功率仍为 0.00。
+        #   初值取正 (q_init=+1) 使每个 (s,a) 都先被尝一次, 由更新把它拉回真值。
+        self.Q = np.full((n_states, n_act), float(q_init))
+        self.n_states, self.n_act = n_states, n_act
+        self.lr, self.gamma, self.eps = lr, gamma, eps
+        self.q_init = float(q_init)
+        self.rng = np.random.RandomState(seed)
+
+    def act(self, s):
+        if self.rng.rand() < self.eps:
+            return int(self.rng.randint(0, self.n_act))
+        return int(np.argmax(self.Q[s]))
+
+    def update(self, s, a, r, s2, done):
+        tgt = r if done else r + self.gamma * float(np.max(self.Q[s2]))
+        self.Q[s, a] += self.lr * (tgt - self.Q[s, a])
+
+
+class SkillAgent:
+    """Q-learning + 一个**跨 regime 保留**的技能库。"""
+
+    def __init__(self, mdp: KeyDoorMDP, mode="primitive", seed=0,
+                 discover_every=25, min_trans=120, opt_prob=0.5,
+                 use_subgoals=1, n_regions=16, max_len=5, term_eps=None):
+        self.mdp = mdp
+        self.mode = mode                    # primitive / reuse_stale / rediscover / macro
+        self.q = QLearner(mdp.n_states, seed=seed)
+        self.rng = np.random.RandomState(seed + 1)
+        self.discover_every = int(discover_every)
+        self.min_trans = int(min_trans)
+        self.opt_prob = float(opt_prob)
+        self.use_subgoals = int(use_subgoals)
+        self.n_regions = int(n_regions)
+        self.max_len = int(max_len)
+        # ★ β_o 的"目标达成"阈值必须与**状态空间尺度**匹配。
+        #   KeyDoor 的 vec() = one-hot(pos) ⊕ has_key ⊕ door_open (n_pos+2 维)。
+        #   **两个不同位置之间的 L2 距离是 √2 ≈ 1.414**, 而到达"某个目标区域"
+        #   的合理判据是"落进该区域", 该区域半径就是 OptionManager 的
+        #   `init_radius`(按区域最近邻距离中位数 * 0.75 自适应推断)。
+        #   固定 eps=0.05 (给"归一化距离"用的量级) 在这里**几乎永不满足**
+        #   -> β_o 只在预算耗尽时触发 -> success 恒 0 -> 技能库从不学习。
+        #   这是本项目第 5 次同型错误("阈值与状态空间尺度不匹配"),
+        #   故此处**默认 None = 运行时取 om.init_radius**, 不再手写常数。
+        self.term_eps = None if term_eps is None else float(term_eps)
+
+        self.trans = []                     # 全历史 (跨 regime 累积)
+        self.om = None                      # 当前技能库
+        self.episodes = 0
+        self.n_discover = 0
+
+    # ── 技能库维护 ──────────────────────────────────────────────────
+    def maybe_discover(self, force=False):
+        """周期性 (或强制) 用**已有全部转移**重建技能库。
+
+        ★ 库**不清空**: 新 options 与旧 options 合并去重。
+          这才是"技能可复用"的实现 —— 换 regime 只是新增地点变体,
+          而不是从头学。
+        """
+        if not force:
+            if self.episodes % self.discover_every != 0:
+                return
+        if len(self.trans) < self.min_trans:
+            return
+        X = np.array([np.append(v, a) for v, a, _ in self.trans])
+        Y = np.array([vn for _, _, vn in self.trans])
+        dim = X.shape[1] - 1
+        T = TabularTransition().fit(X, Y, N_ACT)
+        from hibs_lnn.option_manager import OptionManager
+        from hibs_lnn.uncertainty_gate import UncertaintyGate
+        g = UncertaintyGate(tau_C=1.0)
+        g.calibrate([T.predict(X[i, :dim], int(X[i, -1]))[1]
+                     for i in range(0, len(X), max(1, len(X) // 100))])
+        om = OptionManager(T, g, max_len=self.max_len, seed=0)
+        n_uniq = len(np.unique(np.round(X[:, :dim], 6), axis=0))
+        nreg = min(self.n_regions, max(4, n_uniq))
+        if self.use_subgoals:
+            om.discover_subgoals(X[:, :dim], X[:, -1].astype(int), n_regions=nreg)
+        else:
+            om.discover(X[:, :dim], X[:, -1].astype(int), n_regions=nreg)
+        if self.om is not None:
+            # 合并: 旧技能在前 (先验偏好), 新技能去重后追加
+            seen = {tuple(int(x) for x in o.actions) for o in self.om.options}
+            for o in om.options:
+                k = tuple(int(x) for x in o.actions)
+                if k not in seen:
+                    self.om.options.append(o)
+                    seen.add(k)
+        else:
+            self.om = om
+        self.n_discover += 1
+
+    def _select_option(self, v):
+        """选一个可启动的 option(与 _option_action 同源, 抽出复用)。"""
+        if self.om is None or not self.om.options:
+            return None
+        goal_vec = None
+        try:
+            key_pos, door_pos, goal_pos = self.mdp.regime
+            gv = np.zeros_like(v)
+            gv[goal_pos] = 1.0
+            gv[self.mdp.n_pos] = 1.0      # has_key = 1
+            gv[self.mdp.n_pos + 1] = 1.0  # door_open = 1
+            goal_vec = gv
+        except Exception:
+            pass
+        return self.om.select(v, goal=goal_vec, exclude_unc=True)
+
+    def _option_action(self, s):
+        """按 option 出动作 —— **必须尊重启动集 I_o**。
+
+        ★ 原来的写法是「从技能库里**均匀随机**挑一个 option, 取它的第一个动作」。
+          这既不看 `I_o`(启动集), 也不管目标是否相关, 等于往动作里注入
+          一半的噪声。实测后果 (KeyDoor B 矩阵):
+            技能库涨到 54~60 个后, rediscover 在全部 6 段上都差于 primitive,
+            其中两段**永不收敛** (T_adapt = 上限 300)。
+
+          正确做法 (用户给的 `Option=(I_o,g_o,π_o,β_o)`):
+            用 `OptionManager.select(s, goal=...)` —— 它**会**检查 `initiable(s)`,
+            也就是"当前状态是否落在该 option 的启动集里"。这才是 `I_o` 的语义。
+
+        ★★ 本函数是**逐步顾问**语义 (每步问一次, 执行一个 primitive 动作)。
+            它不是时间抽象 —— option 的多步结构完全没用上, 成败也无从统计
+            (`Option.visits/success` 因此永远是 0, `select()` 里
+            `rate = success/visits` 恒取默认 0.5, 技能库**从不学习哪些 option 管用**)。
+            真正的宏执行见 `_macro_step`。
+        """
+        o = self._select_option(self.mdp.vec())
+        if o is None:
+            return None          # 没有可启动的技能 -> 交回 Q (这才是正确的退让)
+        acts = [int(x) for x in o.actions]
+        if not acts:
+            return None
+        # 闭环: 用世界模型算"朝该 option 目标前进最多"的动作; 失败则退回动作序列
+        a = None
+        if self.om.T is not None:
+            a = self._goal_action(self.mdp.vec(), o.goal_center)
+        if a is None:
+            a = acts[0]
+        return int(a)
+
+    def _macro_step(self, v, active, steps):
+        """把一个 option 当**宏动作**执行。
+
+        返回 `(动作, 新的 active, 新的 steps)`。`active is None` 表示本步先选一个
+        option 再出动作; 每步都重算 `π_o` (闭环), 当 `β_o` 命中
+        (目标达成 / 步数上限) 时结算成败并交回 base policy。
+
+        ## 为什么要这个
+
+        原 `rediscover` 把 option 当**单步动作顾问**: 每步按概率问一次 "现在该做
+        什么动作", option 的 `(I_o, g_o, π_o, β_o)` 里只有 `π_o` 的一步被用到。
+        后果有两个, 都是实测到的:
+
+          1. **成败无从统计** -> `visits/success` 恒 0 -> `select()` 的
+             `rate = success/visits` 恒为默认 0.5 -> 54~60 个 option 在启动集���
+             **同分**, 选择等于抛硬币 -> 全部 6 段都差于 primitive。
+          2. **不是时间抽象** -> 逐步咨询等于给 base policy 注入噪声,
+             没有任何"一段行为被当作一个决策单位"的效果。
+        """
+        # 目标达成阈值: 未显式给定时, 用 OptionManager 自适应推断的
+        # `init_radius`(区域尺度) —— 同一把尺子量启动集与目标区。
+        eps = self.term_eps
+        if eps is None:
+            eps = float(getattr(self.om, "init_radius", 0.75))
+        if active is None:
+            active = self._select_option(v)
+            steps = 0
+            if active is None:
+                return None, None, 0
+        a = self._goal_action(v, active.goal_center) if self.om.T is not None else None
+        if a is None:
+            a = int(active.actions[0]) if active.actions else None
+        steps += 1
+        # β_o: 目标达成 或 预算耗尽 -> 结算
+        # ★ 主判据 = **区域归属** (in_goal_region): "已进入目标区域"。
+        #   旧判据 `goal_distance(v) < eps` 在离散状态空间里退化 ——
+        #   实测 2737 次执行中 0 次因它触发 (eps=0.754 只接受精确到达,
+        #   而可达的最小距离中位数是 1.000)。距离判据保留为兜底。
+        try:
+            reached = bool(active.in_goal_region(v))
+            if not reached:
+                reached = active.goal_distance(v) < eps
+        except Exception:
+            reached = False
+        if reached or steps >= max(1, int(self.max_len)):
+            active.visits += 1
+            if reached:
+                active.success += 1
+            active = None
+            steps = 0
+        return a, active, steps
+
+    def _goal_action(self, v, g):
+        """π_o(s) = argmax_a [ ‖g−s‖ − ‖g−T(s,a)‖ ], 每步重算。"""
+        g = np.asarray(g, dtype=float)
+        d_now = float(np.linalg.norm(v - g))
+        best_a, best_gain = None, -np.inf
+        for a in range(N_ACT):
+            sn, unc = self.om.T.predict(v, a)
+            if not np.isfinite(unc):
+                continue
+            gain = d_now - float(np.linalg.norm(np.asarray(sn, dtype=float) - g))
+            if gain > best_gain:
+                best_a, best_gain = a, gain
+        return best_a
+
+    # ── 一个 episode ────────────────────────────────────────────────
+    def run_episode(self):
+        s = self.mdp.reset()
+        done = False
+        n = 0
+        # ── macro 模式的跨步状态: 当前正在执行的宏动作 ──────────────
+        active, o_steps = None, 0
+        while not done and n < self.mdp.horizon:
+            v = self.mdp.vec()
+            a = None
+            if self.mode == "macro":
+                # 宏执行: 选一个 option -> 跑到 β_o 触发 -> 结算成败
+                if self.rng.rand() < self.opt_prob or active is not None:
+                    a, active, o_steps = self._macro_step(v, active, o_steps)
+            elif self.mode != "primitive" and self.rng.rand() < self.opt_prob:
+                # rediscover / reuse_stale: 逐步顾问语义 (保持不变, 作为对照)
+                a = self._option_action(s)
+            if a is None:
+                active, o_steps = None, 0     # 交回 base policy 时宏动作结束
+                a = self.q.act(s)
+            s2, r, done = self.mdp.step(a)
+            self.q.update(s, a, r, s2, done)
+            self.trans.append((v, a, self.mdp.vec()))
+            s = s2
+            n += 1
+        self.episodes += 1
+        if self.mode != "primitive":
+            self.maybe_discover()
+        return bool(done and self.mdp._reached()), n
+
+    def option_bookkeeping(self):
+        """技能库的成败台账(诊断用: 证明 visits/success 真的被回填了)。"""
+        if self.om is None:
+            return {"n_options": 0, "n_used": 0, "total_visits": 0, "total_success": 0}
+        vs = [o.visits for o in self.om.options]
+        ss = [o.success for o in self.om.options]
+        return {"n_options": len(self.om.options),
+                "n_used": int(sum(1 for v_ in vs if v_ > 0)),
+                "total_visits": int(sum(vs)), "total_success": int(sum(ss))}
+
+
+# ── B 矩阵: regime 链 ───────────────────────────────────────────────
+
+DEFAULT_REGIMES = [
+    dict(key_pos=2, door_pos=5, goal_pos=7),      # A
+    dict(key_pos=5, door_pos=2, goal_pos=6),      # B (key/door 换位)
+    dict(key_pos=1, door_pos=6, goal_pos=7),      # C
+]
+
+
+def run_regime_chain(mode="primitive", chain=None, n_pos=8, episodes_per=400,
+                     seed=0, thresh=0.8, window=20, **kw):
+    """跑 A→B→C→A→B→C 链, 返回每次 regime 的 T_adapt(达到 thresh 所需回合)。
+
+    T_adapt = 该 regime 段内, 滑动成功率首次 ��� thresh 时的回合数;
+              从未达到则记为 episodes_per (上限)。
+    """
+    chain = chain or (DEFAULT_REGIMES * 2)
+    mdp = KeyDoorMDP(n_pos=n_pos, horizon=30, **chain[0])
+    agent = SkillAgent(mdp, mode=mode, seed=seed, **kw)
+    out = []
+    for ci, reg in enumerate(chain):
+        mdp.set_regime(reg["key_pos"], reg["door_pos"], reg["goal_pos"])
+        if mode != "primitive":
+            agent.maybe_discover(force=True)
+        succ, t_adapt = [], None
+        for ep in range(episodes_per):
+            ok, _ = agent.run_episode()
+            succ.append(1.0 if ok else 0.0)
+            if t_adapt is None and len(succ) >= window:
+                if float(np.mean(succ[-window:])) >= thresh:
+                    t_adapt = ep + 1
+        out.append({"regime": ci, "key": reg["key_pos"], "door": reg["door_pos"],
+                    "goal": reg["goal_pos"],
+                    "t_adapt": int(t_adapt if t_adapt is not None else episodes_per),
+                    "final_succ": float(np.mean(succ[-window:])) if succ else 0.0,
+                    "n_options": len(agent.om.options) if agent.om else 0})
+    return out, agent

hibs_lnn/skill_mdp.py

@@ -0,0 +1,187 @@
+"""skill_mdp.py — 一个有**已知 option 结构**的 MDP, 用来判定:
+
+    (a) OptionManager 到底能不能发现并利用 option?
+    (b) E9/E10 的负结果 是**实现坏了**, 还是 **lm4 benchmark 的性质**?
+
+## 为什么需要它
+
+lm4 的测量已经证明那个 benchmark **无时序结构**(不对称性 A ≡ 0, 动作可交换)。
+在那种环境下 option 无论怎么实现都不会有用 —— 所以 lm4 上的负结果
+**无法判定实现好坏**。
+
+要判定实现, 必须换到一个**option 客观上应该有用**的环境。
+这就是经典的「钥匙—门」链式任务: 最优解要求一段**有严格顺序**的多步行为。
+若 OptionManager 在这里也发现不了/用不上 option, 那才是实现的问题。
+
+## 任务结构
+
+    state = (pos, has_key)            pos ∈ {0..N-1},  has_key ∈ {0,1}
+    actions:
+        0  left     位置 -1
+        1  right    位置 +1
+        2  grab     仅在 key_pos 且 !has_key 时拿到钥匙
+        3  open     仅在 door_pos 且 has_key 时开门 (此后 goal 可达)
+
+    reward:
+        到达 goal 且门已开  -> +1, 回合结束
+        步数超过上限        -> 0,  回合结束
+
+    ★ **顺序依赖是内生的**:
+        - "go_right 到 key" 只在**还没拿钥匙**时有用
+        - "grab" 只在 key 位置有用
+        - "open" 只在**已拿钥匙**时有用
+      -> A(a,b) ≠ 0, 且不对称 (go_key → grab ≠ grab → go_key)
+      -> 这正是 lm4 里**完全缺失**的结构
+
+## regime (用于 A→B→A 复用测试)
+
+    一个 regime = (key_pos, door_pos, goal_pos)。
+    换 regime = 同样的技能 (拿钥匙/开门) 仍然有效, 但**地点变了**
+    -> 这正是"可复用行为结构"的定义, 也是 option 该体现价值的地方。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+LEFT, RIGHT, GRAB, OPEN = 0, 1, 2, 3
+N_ACT = 4
+
+
+class KeyDoorMDP:
+    """钥匙—门 链式 MDP。`state = (pos, has_key)` 编码成整数 pos*2 + has_key。"""
+
+    def __init__(self, n_pos=8, key_pos=2, door_pos=5, goal_pos=7, horizon=30):
+        self.n_pos = int(n_pos)
+        self.regime = (int(key_pos), int(door_pos), int(goal_pos))
+        self.horizon = int(horizon)
+        # ★ state 必须包含 door_open! 它影响转移(开门后目标才可达)。
+        #   早先编码 pos*2+has_key **漏掉了 door_open** -> 同一 (pos,has_key)
+        #   在门开/门关时无法区分 -> 任务退化成 POMDP -> Q-learning 学不会
+        #   (实测: 400 回合成功率仍为 0.0)。
+        #   现在: pos*4 + has_key*2 + door_open  -> n_pos*4 个状态
+        self.n_states = self.n_pos * 4
+        self.t = 0
+        self.pos, self.has_key, self.door_open = 0, 0, 0
+
+    # ── 状态编码 ────────────────────────────────────────────────────
+    def state(self):
+        return self.pos * 4 + self.has_key * 2 + self.door_open
+
+    def decode(self, s):
+        s = int(s)
+        return s // 4, (s // 2) % 2, s % 2     # pos, has_key, door_open
+
+    def vec(self):
+        """给知识层用的连续表示: one-hot(pos) ⊕ has_key ⊕ door_open。"""
+        v = np.zeros(self.n_pos + 2)
+        v[self.pos] = 1.0
+        v[self.n_pos] = float(self.has_key)
+        v[self.n_pos + 1] = float(self.door_open)
+        return v
+
+    def set_regime(self, key_pos, door_pos, goal_pos):
+        self.regime = (int(key_pos), int(door_pos), int(goal_pos))
+
+    def reset(self):
+        self.t = 0
+        self.pos, self.has_key, self.door_open = 0, 0, 0
+        return self.state()
+
+    # ── 动力学 ──────────────────────────────────────────────────────
+    def step(self, a):
+        key_pos, door_pos, goal_pos = self.regime
+        self.t += 1
+        if a == LEFT:
+            self.pos = max(0, self.pos - 1)
+        elif a == RIGHT:
+            self.pos = min(self.n_pos - 1, self.pos + 1)
+        elif a == GRAB:
+            if self.pos == key_pos and not self.has_key:
+                self.has_key = 1
+        elif a == OPEN:
+            if self.pos == door_pos and self.has_key and not self.door_open:
+                self.door_open = 1
+        # 到达目标
+        done = False
+        r = 0.0
+        if self.pos == goal_pos and (self.door_open or goal_pos < door_pos):
+            r, done = 1.0, True
+        elif self.t >= self.horizon:
+            done = True
+        return self.state(), r, done
+
+    def _reached(self):
+        key_pos, door_pos, goal_pos = self.regime
+        return self.pos == goal_pos and (self.door_open or goal_pos < door_pos)
+
+    def greedy_action(self):
+        """这个任务的最优一步策略 (只为给 baseline/交互测量用)。"""
+        key_pos, door_pos, goal_pos = self.regime
+        if self.pos != key_pos and not self.has_key and key_pos >= 0:
+            return RIGHT if key_pos > self.pos else LEFT
+        if self.pos == key_pos and not self.has_key:
+            return GRAB
+        if not self.door_open and goal_pos >= door_pos:
+            if self.pos != door_pos:
+                return RIGHT if door_pos > self.pos else LEFT
+            if self.has_key:
+                return OPEN
+        return RIGHT if goal_pos > self.pos else LEFT
+
+    def optimal_steps(self):
+        """最优解需要多少步 (用于设 T_adapt 阈值)。"""
+        key_pos, door_pos, goal_pos = self.regime
+        n = abs(key_pos - 0) + 1          # 走到 key + grab
+        if goal_pos >= door_pos:
+            n += abs(door_pos - key_pos) + 1   # 走到 door + open
+            n += abs(goal_pos - door_pos)
+        else:
+            n += abs(goal_pos - key_pos)
+        return n
+
+
+def interaction_asymmetry(mdp, a, b, n_ep=200, seed=0):
+    """A(a,b) = I(a,b) − I(b,a), 用**走到目标的步数**度量。
+
+        S_seq = 从初始态做完整序列再贪心走到目标的**总步数**
+        I(a,b) = S_b − S_ab      (先做 a 再做 b, 比只做 b 少用多少步)
+
+    ★ 为什么不能用「成功率」: 贪心策略从**任何**状态都能解出任务,
+      于是成功率恒为 1.000, 前缀完全不影响 —— 测量饱和, 什么也测不出。
+      (这是本项目第二次踩同一个坑; 上一次是 lm4 的 `b_only = 1.0000`。)
+      步数才对前缀敏感。
+    """
+    def steps(seq):
+        tot = 0
+        for _ in range(n_ep):
+            mdp.reset()
+            n = 0
+            done = False
+            for x in seq:
+                _, _, done = mdp.step(x)
+                n += 1
+                if done:
+                    break
+            while not done and n < mdp.horizon * 3:
+                _, _, done = mdp.step(mdp.greedy_action())
+                n += 1
+            tot += n
+        return tot / n_ep
+
+    S_ab = steps([a, b]); S_ba = steps([b, a])
+    S_a = steps([a]); S_b = steps([b])
+    # 基线: 什么都不强迫
+    S_none = steps([])
+    I_ab, I_ba = S_b - S_ab, S_a - S_ba
+    return dict(a=a, b=b, S_none=S_none, S_a=S_a, S_b=S_b, S_ab=S_ab, S_ba=S_ba,
+                I_ab=I_ab, I_ba=I_ba, asym=I_ab - I_ba)
+
+
+def has_temporal_structure(mdp, n_ep=200, seed=0, tol=0.5):
+    """对全部有序动作对测 A(a,b), 返回是否**存在**顺序依赖。"""
+    import itertools
+    rows = [interaction_asymmetry(mdp, a, b, n_ep=n_ep, seed=seed)
+            for a, b in itertools.permutations(range(N_ACT), 2)]
+    A = np.array([r["asym"] for r in rows])
+    frac = float((np.abs(A) > tol).mean())
+    return rows, A, frac

hibs_lnn/ssm_v30_3.py

@@ -0,0 +1,166 @@
+"""
+V30.3: 内部纠缠 SSM 层 (减法版)
+===================================
+核心改动: 在 SSM 递推的每一步, 用当前隐藏状态的跨维度投影
+调制下一步的 A 矩阵相位。5 行代码, 无外部引擎。
+
+减法:
+  V30.1: +EntanglementEngine (后处理)
+  V30.2: +EntangleDecohereEngine (纠缠+退相干+熵正则)
+  V30.3: 只改 SSM 内部, 不加任何外部模块
+"""
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class SSM_Layer_V30_3(nn.Module):
+    """
+    V30.3 SSM 层: V29 基线 + 内部纠缠。
+
+    在串行扫描的每一步(h_mean 计算后):
+      if ent_mode != 'none':
+        # 调 h 的相位: 纯相位调制, 不改变振幅
+        phase_shift = ent_mod_net(h_norm)  # 跨 N 维度投影
+        h = h * exp(i · phase_shift)        # 纯相位旋转
+
+    纠缠特性:
+      - 发生在 SSM 递推内部 (每个 token 步)
+      - 跨 N 维度耦合 (ent_k=3 时 top-3)
+      - 纯相位 (不破坏已学习的振幅结构)
+      - 因果: 只影响未来状态, 不影响过去
+    """
+
+    def __init__(self, d_model, d_state=8, fiber=None, layer_idx=0,
+                 ent_mode='none', ent_k=3, ent_strength=0.05):
+        super().__init__()
+        self.d_model = d_model
+        self.d_state = d_state
+        self.ent_mode = ent_mode
+        self.ent_k = ent_k
+        self.ent_strength = ent_strength
+
+        # 沿用 V29 架构
+        self.norm = nn.LayerNorm(d_model)
+        self.in_proj = nn.Linear(d_model, 2 * d_model)
+        self.conv = nn.Conv1d(d_model, d_model, kernel_size=4, groups=d_model, padding=3)
+        self.out_proj = nn.Linear(d_model, d_model)
+
+        # SSM 参数
+        self.ssm_logsigma = nn.Parameter(torch.randn(d_model, d_state) * 0.1)
+        self.ssm_theta = nn.Parameter(torch.randn(d_model, d_state) * 0.5)
+        self.dt_proj = nn.Linear(d_model, d_model)
+        self.B_proj = nn.Linear(d_model, d_state)
+        self.C_proj = nn.Linear(d_model, d_state)
+        self.ssm_D = nn.Parameter(torch.ones(d_model))
+
+        # V33 路由进递推 (INTACT 意图条件化): cond 调制 dt/B (读写门意图感知)
+        # 零初始化 → 加载 Stage1 缓存后 cond 任意值 ≡ 无条件 (无需重训 Stage1)
+        self.cond_dt = nn.Linear(d_model, d_model)
+        self.cond_b = nn.Linear(d_model, d_state)
+        with torch.no_grad():
+            self.cond_dt.weight.zero_(); self.cond_dt.bias.zero_()
+            self.cond_b.weight.zero_(); self.cond_b.bias.zero_()
+
+        # KL 相关 (从 V29 继承)
+        self.logvar_net = nn.Sequential(
+            nn.Linear(d_model, d_model), nn.SiLU(),
+            nn.Linear(d_model, d_state),
+        )
+        self.base_prior_logvar = nn.Parameter(torch.zeros(d_state))
+        self.fiber_prior_strength = nn.Parameter(torch.tensor(0.1))
+        self.register_buffer('kl_scale', torch.tensor(0.0))
+
+        # ── V30.3 内部纠缠: 极小调制网络 ──
+        # 输入: |h| 投影到 N 维 (跨维度耦合)
+        # 输出: 相位调制量 (纯相位, 不改变振幅)
+        if ent_mode != 'none':
+            self.ent_mod = nn.Linear(d_state, d_state, bias=False)
+            self.ent_amp = nn.Linear(d_state, 1, bias=False)  # 振幅门控
+
+        self._entropy_trace = []
+
+    def compute_entropy(self, h):
+        B, D, N = h.shape
+        amp = h.abs()
+        rho = amp.view(B, D, N, 1) * amp.view(B, D, 1, N)
+        rho = rho / (rho.sum(dim=(-1, -2), keepdim=True) + 1e-10)
+        try:
+            e = torch.linalg.eigvalsh(rho).clamp(min=1e-10)
+            return -(e * e.log()).sum(dim=-1).mean().item()
+        except:
+            return 0.0
+
+    def forward(self, x, cond=None):
+        r = x
+        x = self.norm(x)
+        a, b = self.in_proj(x).chunk(2, dim=-1)
+        a = F.silu(self.conv(a.transpose(-1, -2))[:, :, :x.shape[1]].transpose(-1, -2))
+
+        B_, L_, D_ = a.shape
+        S_ = self.ssm_logsigma.shape[-1]
+        sigma = -self.ssm_logsigma.exp()
+        theta0 = self.ssm_theta
+        A_eff = sigma.unsqueeze(0).unsqueeze(0) + 1j * theta0.unsqueeze(0).unsqueeze(0)
+
+        if cond is not None:
+            # V33 路由: 意图 cond 调制 dt 与 B (读写门意图感知), 广播到每步
+            c_dt = self.cond_dt(cond)              # (..., d)
+            c_b = self.cond_b(cond)                # (..., d_state)
+            if c_dt.dim() == 1:
+                c_dt = c_dt.unsqueeze(0)
+                c_b = c_b.unsqueeze(0)
+            dt = F.softplus(self.dt_proj(a) + c_dt.unsqueeze(1)) + 1e-4
+            Bk = self.B_proj(a) + c_b.unsqueeze(1)
+        else:
+            dt = F.softplus(self.dt_proj(a)) + 1e-4
+            Bk = self.B_proj(a)
+        Ck = self.C_proj(a)
+        Ab = torch.exp(dt.unsqueeze(-1) * A_eff)
+        bk = (Ab - 1.0) / (A_eff + 1e-8) * Bk.unsqueeze(2) * a.unsqueeze(-1)
+
+        h = torch.zeros(B_, D_, S_, dtype=torch.complex64, device=Ab.device)
+        ys = torch.zeros(B_, L_, D_, device=a.device)
+
+        for k in range(L_):
+            h_mean = Ab[:, k] * h + bk[:, k]
+
+            # ── V30.3: 内部纠缠 ──────────────
+            if self.ent_mode != 'none' and k > 0:
+                # 从 |h| 导出纯相位调制 (跨 N 维度耦合)
+                h_norm = h_mean / (h_mean.abs() + 1e-8)  # 归一化复数
+                h_amp = h_mean.abs()                     # 振幅
+                phase_input = h_norm.real * h_amp        # (B, D, N) 振幅加权相位信号
+
+                # 跨 N 维度的线性耦合
+                delta_raw = self.ent_mod(phase_input)  # (B, D, N)
+
+                if self.ent_k > 0 and self.ent_k < S_:
+                    # top-k 稀疏化: 只纠缠振幅最大的维度
+                    _, top_idx = h_amp.topk(self.ent_k, dim=-1)
+                    mask = torch.zeros_like(delta_raw)
+                    mask.scatter_(-1, top_idx, 1.0)
+                    delta_raw = delta_raw * mask
+
+                # 振幅门控: 强信号有更强的纠缠, 但不改变本身振幅
+                amp_gate = torch.sigmoid(self.ent_amp(h_amp))  # (B, D, 1)
+                phase_shift = torch.tanh(delta_raw) * self.ent_strength * amp_gate
+
+                # 纯相位旋转: 不改变振幅
+                h = h_mean * torch.exp(1j * phase_shift)
+            else:
+                h = h_mean
+
+            y = (Ck[:, k].unsqueeze(1) * h).sum(dim=-1).real + self.ssm_D * a[:, k]
+            ys[:, k] = y
+
+            if self.ent_mode != 'none':
+                self._entropy_trace.append(self.compute_entropy(h))
+
+        out = self.out_proj(ys * F.silu(b)) + r
+
+        # 兼容 V30_CodeLoop: 保存最后一个激活
+        self._last_a = a[:, -1, :]
+
+        return out, 0.0  # (y, kl=0 兼容 V30_CodeLoop)

hibs_lnn/stochastic_keydoor.py

@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+"""A′ 的三个环境:把 `novelty` 与 `dynamics change` 分开。
+
+## 为什么需要新环境
+
+原 `KeyDoorMDP.step()` 是**完全确定性**的(无任何随机源)。实测:所有访问过
+`n>=2` 的 `(s,a)`,后继分布的最大熵**逐位为 0.000000**。于是
+
+    转移不确定性 H(T|S,A) ≡ 0
+    转移预测误差 1−p̂(s'|s,a) 的唯一非零来源是 `n<2` 分支
+    稳定区域 ≈ 同样的计数
+
+三个语义不同的量坍缩成**同一个"我见过这个 (s,a) 几次"**。
+⇒ 那个环境对 A 类**不可辨识**,不是 A 类不行。
+
+## 三个环境(A′-2)
+
+    E0  KeyDoorMDP              确定性        —— 负对照, 保留不删
+    E1  StochasticKeyDoor       平稳随机      —— 不确定性可分离, 无 shift
+    E2  NonStationaryKeyDoor    非平稳(slip↑) —— ★ **可用**: 满足构型 II
+        FlipKeyDoor             非平稳(翻转)  —— ❌ 失败构造, 保留为反例
+
+★ **命名与直觉相反, 以实测为准**(探针③, 逐步紧邻等长窗口):
+
+    E2 翻转:    N 3.62  A1 3.39  A2 2.75   <- N 跳得比 A1 还凶, 失败
+    E2 slip↑:   N 0.88  A1 3.10  A2 1.25   <- N 平, A1 跳, A1/A2 分歧 ✓
+
+我原以为"翻转(支撑集不变)"最干净、"slip↑"是反例。**测量给出相反答案**:
+决定 novelty 的不是转移的支撑集, 而是最终的**去向分布**; 翻转恰好把 agent
+送到它几乎没去过的伙伴目标。而均匀随机 slip↑ 是在**已熟悉的地盘内**
+增加不可预测性 ⇒ 访问分布不动, `p̂` 变成错的。
+
+## 设计要点:机制只写一份
+
+每个环境只实现 **`_perturb(a) -> 实际执行的动作`**, `step()` 与诊断用的
+`true_transition()` **共用**它。
+
+第一版把机制在 `step()` 和 `true_transition()` 里各写了一遍, 后果是:
+`true_transition` 里那条 `if rand < _slip_now(): a = randint(N)` 是**均匀随机**
+版本, 对 `FlipKeyDoor` 完全不对(它只翻给伙伴动作)。于是"真值"量的是另一套
+动力学, 而探针偏偏靠真值判断环境可不可辨识 —— **诊断工具自己错了,
+却会给出一个看起来正常的结论**。两份实现只要漂移一次就足够。
+"""
+import numpy as np
+
+from hibs_lnn.skill_mdp import KeyDoorMDP
+
+__all__ = ["StochasticKeyDoor", "FlipKeyDoor", "NonStationaryKeyDoor",
+           "N_ACTIONS", "true_transition"]
+
+N_ACTIONS = 4                       # LEFT, RIGHT, GRAB, OPEN
+_NEVER = 1 << 62
+
+
+class StochasticKeyDoor(KeyDoorMDP):
+    """E1 平稳随机:`P(s'|s,a)` 全程不变。
+
+    以 `(1-slip)` 执行意图动作, 否则执行**均匀随机**动作。
+    作用 = 制造"不确定性高但**没有** regime shift"。
+    """
+
+    def __init__(self, slip=0.10, seed=0, **kw):
+        super().__init__(**kw)
+        self.slip = float(slip)
+        self.rng = np.random.RandomState(int(seed))
+        self.t_total = 0            # 全局步数(跨 episode) —— 子类用它定位 shift
+        self.shifted = False
+
+    # ── 机制(唯一实现; step 与 true_transition 共用)──────────────
+    def _p_now(self):
+        return self.slip
+
+    def _perturb(self, a):
+        """返回**实际执行**的动作。支撑集由子类的实现决定。"""
+        if self.rng.rand() < self._p_now():
+            return int(self.rng.randint(N_ACTIONS))
+        return int(a)
+
+    def step(self, a):
+        if not self.shifted and self.t_total >= getattr(self, "shift_at", _NEVER):
+            self.shifted = True
+        self.t_total += 1
+        return KeyDoorMDP.step(self, self._perturb(a))
+
+
+class FlipKeyDoor(StochasticKeyDoor):
+    """❌ 失败构造(保留为反例):"翻转分布、不扩张支撑集"**仍然混淆 novelty**。
+
+    ## 我当初的推理(错的)
+
+    想让 `P(s'|s,a)` 的**支撑集恒定**、只翻转权重:
+
+        P(s'|s,a) = (1-p)·1[s'=T(s,a)] + p·1[s'=T(s,c(a))]
+        shift 前 p = 0.10           shift 后 p = 0.90
+
+    `c(a)` 是固定的伙伴动作(LEFT<->RIGHT, GRAB<->OPEN)。推理是:
+    支撑集 `{T(s,a), T(s,c(a))}` 两个 p 下都一样 ⇒ 到达的状态集合不变
+    ⇒ novelty 不变; 而模型学到的 `p̂` 现在是错的 ⇒ A1 跳; 熵
+    `H({p,1−p})` 两 regime 同值 ⇒ A2 不跳。看起来是完美的 构型 II。
+
+    ## 实测(逐步、紧邻等长窗口, 探针③)
+
+        E2 翻转:  N 0.0597 -> 0.2160 (3.62)   A1 0.1908 -> 0.6476 (3.39)
+                  A2 0.1125 -> 0.3093 (2.75)
+        E2c slip↑: N 0.0997 -> 0.0881 (0.88)   A1 0.1738 -> 0.5382 (3.10)
+                  A2 0.1326 -> 0.1656 (1.25)
+
+    **翻转版失败**: N 跳 3.62 倍, 比 A1 还凶。
+
+    ## 为什么推理错了(值得记)
+
+    > **决定 novelty 的不是转移的支撑集, 而是最终的去向分布。**
+
+    支撑集不变只保证"这些状态**可能**被到达"; 但翻转把 agent 在 90% 的
+    步子上送到**伙伴目标** —— 那是它极少去的地方 ⇒ 它真的闯进了新领���。
+    支撑集是"可能性", novelty 量的是"实际去过几次", 两者不是一回事。
+
+    ## 教训
+
+    "不扩张支撑集"看起来是把 novelty 摘掉的自然做法, 但 agent 的行为是
+    **状态依赖**的 —— 改了动力学就改了轨迹, 改了轨迹就改了访问分布。
+    要抑制 novelty, 得直接让**访问分布**不变, 而不是让转移的支撑集不变。
+    `NonStationaryKeyDoor`(均匀随机 slip↑)无意中做到了这一点:
+    它在**已熟悉的地盘内**增加不可预测性。
+    """
+
+    COMPANION = (1, 0, 3, 2)            # LEFT<->RIGHT, GRAB<->OPEN
+
+    def __init__(self, p_pre=0.10, p_post=0.90, shift_at=3000, seed=0, **kw):
+        super().__init__(slip=p_pre, seed=seed, **kw)
+        self.p_pre = float(p_pre)
+        self.p_post = float(p_post)
+        self.shift_at = int(shift_at)
+
+    def _p_now(self):
+        return self.p_pre if self.t_total < self.shift_at else self.p_post
+
+    def _perturb(self, a):
+        if self.rng.rand() < self._p_now():
+            return int(self.COMPANION[int(a)])      # 只翻给伙伴动作
+        return int(a)
+
+
+class NonStationaryKeyDoor(FlipKeyDoor):
+    """★ E2(**可用版**):均匀随机 slip 在 `shift_at` 处抬升。
+
+        E1: slip 恒定 0.10            E2: 0.10 -> 0.60 @shift_at
+
+    它最初是被当成"反例"写下来的(我原以为它会混淆 novelty, 因为
+    "slip 变大 ⇒ agent 走得不一样"). 实测**正好相反**, 它是唯一同时满足
+    构型 II 的构造:
+
+        N   0.0997 -> 0.0881  (0.88)   ← 平坦: 没有更"新"
+        A1  0.1738 -> 0.5382  (3.10)   ← 跳: 学到的 p̂ 现在错了
+        A2  0.1326 -> 0.1656  (1.25)   ← 基本平 ⇒ **A1 与 A2 分歧**
+
+    为什么它反而干净: 均匀随机 slip 在 **已熟悉的地盘内** 增加不可预测性
+    (agent 早就把大部分 (s,a) 走过很多遍了), 所以访问分布几乎不动;
+    而 `p̂` 的**形状**变了 ⇒ 预测误差上去了。
+
+    于是这条环境上 "变" 与 "新" 可辨识, 并且 A1/A2 读数**明显分离** ——
+    这是 A 类候选第一次在同一环境上表现出不同的量。
+    """
+
+    def __init__(self, slip0=0.10, slip1=0.60, shift_at=3000, seed=0, **kw):
+        super().__init__(p_pre=slip0, p_post=slip1, shift_at=shift_at,
+                         seed=seed, **kw)
+
+    def _perturb(self, a):
+        if self.rng.rand() < self._p_now():
+            return int(self.rng.randint(N_ACTIONS))     # 均匀随机 = 不选边
+        return int(a)
+
+
+def true_transition(env, s, a, trials=400):
+    """把 `(s,a)` 的真实后继分布**数出来**(穷举环境, 非模型)。
+
+    只用于验证"这个 benchmark 真的可辨识"(判据 ⑨′a/⑨′b)。
+    agent 侧一律只用在线计数表, **不碰这个函数**。
+
+    ★ 设置状态必须走 `decode()`:`s = pos*4 + has_key*2 + door_open`,
+      `has_key`/`door_open` 也影响转移。手写 `env.s = s` 是错的
+      (那个属性不存在, 而且漏掉两个标志位)。
+    ★ 扰动走 `env._perturb()` —— 与 `step()` **同一份实现**。E0 没有该方法,
+      退化成恒等(确定性), 正好是我们要的负对照。
+    """
+    pert = getattr(env, "_perturb", None)
+    cnt = {}
+    for _ in range(int(trials)):
+        env.pos, env.has_key, env.door_open = env.decode(s)
+        env.t = 0
+        aa = int(a) if pert is None else int(pert(a))
+        s2, _, _ = KeyDoorMDP.step(env, aa)
+        cnt[int(s2)] = cnt.get(int(s2), 0) + 1
+    return cnt

hibs_lnn/subtask_options.py

@@ -0,0 +1,310 @@
+r"""subtask_options.py — **按论文顺序**实现 STOMP(arXiv 2202.03466)。
+
+    SubTask ──> Option ──> Model ──> Planning
+
+本文件是对本项目现有 `OptionManager` 的**修正版**。差别(逐条对齐论文):
+
+| | 现有 `option_manager.py` | 本文件 |
+|:--|:--|:--|
+| 起点 | **转移图**(model-first) | **subtask**:先定 GVF 的 `(c, z)` |
+| 目标 | 状态向量 `g_o` + 欧氏距离 | **stopping value `z_i(s)`**(带 stopping bonus) |
+| `π_o` | 对模型贪心 argmax | 在 subtask MDP 上解出来的策略 |
+| `β_o` | 逻辑回归拟合 | **stop 动作最优即停**(与论文 Fig.2 的"红色停止格"一致) |
+| model | 无 | **option model**(终止分布 + 累计奖励)显式学出来 |
+| 用途 | 替换 base policy 的动作 | **进 planner**,指标 = planning look-ahead 操作数 |
+
+## 论文的两种 subtask(必须都实现, 才有正反例)
+
+```
+shortest-path (bottleneck)   c = −1                          z = 0 at subgoal
+reward-respecting            c = R (与主任务相同)             z_i(s) = v(s) − w_i x_i(s) + w̄_i x_i(s)
+                                                                       \____ stopping bonus ____/
+```
+论文 Fig.1 的结论:`shortest-path` 的 planning **比 primitive 还慢**;
+`reward-respecting` **明显更快**。**这两个已知结论就是本项目的 ground truth。**
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from hibs_lnn.gridworld import N_ACT, UP, RIGHT, DOWN, LEFT
+
+STOP = N_ACT          # 停止动作的编号
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 1. Subtask 规格:GVF 的 cumulant c 与 stopping value z
+# ══════════════════════════════════════════════════════════════════════
+
+class Subtask:
+    """一个 GVF 子任务 = (c, z)。
+
+    c(s, a)       : cumulant(论文里最短路径 subtask 是 −1, reward-respecting 是主任务奖励)
+    z(s)          : stopping value(在 s 停止时拿到的终止价值)
+    """
+
+    def __init__(self, name, c_fn, z_fn):
+        self.name = name
+        self.c_fn = c_fn          # (s, a) -> float, 该转移的期望 cumulant
+        self.z_fn = z_fn          # (s) -> float
+        self.gamma = 0.99         # 由 solve(env) 覆盖
+        self.policy = None        # π_o:(s) -> a 或 STOP
+        self.value = None         # 该 subtask 的价值函数
+        self.model = None         # option model
+        self.beta = None          # β_o(s): 是否停止
+
+    # ── 解 subtask -> 得到 option(论文 §3) ────────────────────────────
+    def solve(self, env, max_sweeps=2000, tol=1e-10, resume_from=None):
+        """在 subtask MDP 上做价值迭代(action 集 = 4 个 primitive + STOP)。
+
+            目标: 最大化  E[ Σ γ^t c_t + γ^K z(S_K) ]
+            Q(s, a) = c(s,a) + γ (1−β) V(s') + γ β z(s')     # β 由"停止是否最优"隐式决定
+        """
+        n = env.n_states
+        V = np.zeros(n) if resume_from is None else resume_from.copy()
+        for sweep in range(max_sweeps):
+            delta = 0.0
+            Vn = V.copy()
+            for s in range(n):
+                if env.is_goal[s]:
+                    Vn[s] = 0.0        # goal 是终止状态(episode 结束)
+                    delta = max(delta, abs(Vn[s] - V[s]))
+                    continue
+                # 停下:s 的价值就是 z(s)
+                best = self.z_fn(s)
+                for a in range(N_ACT):
+                    c = self.c_fn(s, a)
+                    if c is None:
+                        continue
+                    val = 0.0
+                    for p, ns in env.T[s][a]:
+                        # 在 ns 决定:继续(value)还是停(z)
+                        val += p * (c + env.gamma * max(V[ns], self.z_fn(ns)))
+                    if val > best:
+                        best = val
+                Vn[s] = best
+                delta = max(delta, abs(Vn[s] - V[s]))
+            V = Vn
+            if delta < tol:
+                break
+        self.value = V
+        # 导出 π_o 与 β_o
+        pol = np.full(n, STOP, dtype=int)
+        for s in range(n):
+            if env.is_goal[s]:
+                pol[s] = STOP
+                continue
+            best_a, best_v = STOP, self.z_fn(s)
+            for a in range(N_ACT):
+                c = self.c_fn(s, a)
+                if c is None:
+                    continue
+                val = 0.0
+                for p, ns in env.T[s][a]:
+                    val += p * (c + env.gamma * max(V[ns], self.z_fn(ns)))
+                if val > best_v + 1e-12:
+                    best_a, best_v = a, val
+            pol[s] = best_a
+        self.policy = pol
+        # β_o(s) = True 表示"停在 s 是最优的"
+        #   判据: z(s) >= "继续走"的价值 —— 与论文 Fig.2 的红色停止格一致
+        cont = np.full(n, -np.inf)
+        for s in range(n):
+            if env.is_goal[s]:
+                continue
+            best = -np.inf
+            for a in range(N_ACT):
+                c = self.c_fn(s, a)
+                if c is None:
+                    continue
+                val = 0.0
+                for p_, ns in env.T[s][a]:
+                    val += p_ * (c + env.gamma * max(V[ns], self.z_fn(ns)))
+                best = max(best, val)
+            cont[s] = best
+        self.beta = np.array([bool(self.z_fn(s) >= cont[s] - 1e-12) for s in range(n)],
+                             dtype=bool)
+        self.gamma = env.gamma
+        return self
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 2. 两种 subtask 的具体定义(论文 Fig.1 的对照)
+# ══════════════════════════════════════════════════════════════════════
+
+def shortest_path_subtask(env, subgoal_state, neg_on_neg=True):
+    """论文:shortest-path / bottleneck option。`c = −1`,`z = 0` 只在子目标处。"""
+
+    def c(s, a):
+        return -1.0
+
+    def z(s):
+        return 0.0 if s == subgoal_state else -np.inf
+
+    st = Subtask("shortest_path", c, z)
+    return st
+
+
+def reward_respecting_subtask(env, feature_vec, V_main, bonus_weight=1.0,
+                              stop_at_goal=True):
+    r"""论文式(4):reward-respecting subtask of feature attainment。
+
+        c(s,a) = R(s,a)                       -- **与主任务相同的奖励**
+        z_i(s) = [w^T x(s) - w_i*x_i(s)] + w_bar_i*x_i(s)
+               = V_main(s) + (w_bar_i - w_i)*x_i(s)
+                              \__ stopping bonus __/
+
+    *** 一个必须做对的细节(本项目在 ground-truth 基准上抓到的 bug) ***
+    式(4) 里 `w_i` 是 **特征 i 在主任务价值函数里的权重**, 不是 1。
+
+    第一版把 `w_i` 硬写成 1.0 且 `w_bar_i = 1` -> stopping bonus 恒为 0
+    -> `z_i(s) == V_main(s)` -> 子任务近似主任务 -> `beta_o` 处处为空
+    -> option 永不停止 -> option model 退化 -> reward-respecting 与
+       shortest-path 给出**完全相同**的 planning 曲线(实测 2145 / 2145)。
+
+    这正是论文原话警告的情形:
+      "The stopping values should not equal the estimated values because then the
+       subtask would approximate the main task and solving it would probably add
+       nothing new."
+
+    对一热特征 x_i(s) in {0,1}, 主任务线性近似下特征 i 的权重就是
+    **该特征为 1 的诸状态上的价值贡献** -> w_i = mean(V_main[feature > 0])。
+
+    bonus_weight 就是论文的 w_bar_i:
+        w_bar ~ w_i    bonus 小, option 几乎不提前停
+        w_bar = 1      论文主用值
+        w_bar -> 很大   退化成 shortest-path(论文 §6 实测, w_bar=100 走最短路)
+    """
+    on = np.asarray(feature_vec, dtype=float) > 0
+    w_i = float(np.mean(np.asarray(V_main, dtype=float)[on])) if on.any() else 0.0
+
+    def c(s, a):
+        return float(env.R[s][a])
+
+    def z(s):
+        if not on[s] and not (stop_at_goal and env.is_goal[s]):
+            # 特征为 0 处**不允许停**(否则"停"与"继续"同价 -> beta 退化)
+            return -np.inf
+        return float(V_main[s]) + (bonus_weight - w_i) * float(feature_vec[s])
+
+    st = Subtask("reward_respecting", c, z)
+    st.w_i = w_i
+    st.bonus_weight = bonus_weight
+    return st
+
+# ══════════════════════════════════════════════════════════════════════
+# 3. Option model(论文 §4:第三步,在 option 之后)
+# ══════════════════════════════════════════════════════════════════════
+
+def build_option_model(env, opt, max_steps=200):
+    r"""由 option 的 (pi_o, beta_o) 推出**SMDP 形式的 option model**。
+
+    返回 `M[s] = [(p, s_term, r_disc, k), ...]`,其中
+
+        p       : 从 s 出发最终终止于 s_term 的概率
+        r_disc  : 沿途中**已贴现**的累计奖励  sum_t gamma^t r_t
+        k       : 平均步数
+
+    ★★ 第二个必须做对的细节(ground-truth 基准抓到的)
+    -------------------------------------------------
+    第一版只返回未贴现的累计奖励, 且 planner 里写成 ``r + gamma*V(s_term)``
+    —— 即只贴现**一步**, 而不是 option 实际占用的 k 步。
+    -> option 被系统性高估 -> 价值迭代发散
+    (实测: look-ahead ��满 300000 仍未收敛, 而 primitive 只需 1716)。
+
+    SMDP 的正确形式是:   Q(s, o) = E[ r_disc + gamma^k * V(s_term) ]
+    """
+    n = env.n_states
+    M = []
+    for s0 in range(n):
+        cur = {int(s0): (1.0, 0.0, 0.0)}     # state -> (prob, 期望贴现回报, 期望步数)
+        term = {}
+
+        def merge(d, key, p, dr, k):
+            o = d.get(key)
+            if o is None:
+                d[key] = [p, p * dr, p * k]
+            else:
+                o[0] += p
+                o[1] += p * dr
+                o[2] += p * k
+
+        for _step in range(max_steps):
+            if not cur:
+                break
+            nxt = {}
+            for s, (p, dr, k) in cur.items():
+                if opt.beta[s] or opt.policy[s] == STOP:
+                    merge(term, s, p, dr, k)
+                    continue
+                a = int(opt.policy[s])
+                r_imm = float(opt.c_fn(s, a))
+                for pt, ns in env.T[s][a]:
+                    pp = p * pt
+                    merge(nxt, int(ns), pp, dr + (env.gamma ** k) * r_imm, k + 1.0)
+            cur = {s: (v[0], v[1] / v[0] if v[0] > 0 else 0.0,
+                       v[2] / v[0] if v[0] > 0 else 0.0) for s, v in nxt.items()}
+
+        outs = []
+        for s, (psum, drw, kw) in sorted(term.items()):
+            if psum <= 1e-12:
+                continue
+            outs.append((float(psum), int(s), float(drw / psum), float(kw / psum)))
+        if not outs:
+            outs = [(1.0, int(s0), 0.0, 1.0)]
+        M.append(outs)
+    return M
+
+
+
+# ══════════════════════════════════════════════════════════════════════
+# 4. Planning(论文 §5):指标 = look-ahead 操作数
+# ══════════════════════════════════════════════════════════════════════
+
+def planning_curve(env, option_models, v_star, s0, tol=1e-3, max_ops=400000,
+                   sweeps_between=1):
+    """带 option 的价值迭代;记录"每消耗 N 次 look-ahead 时 V(s0) 的误差"。
+
+    option_models : {name: M}, M 来自 build_option_model。空 dict = 只用 primitive。
+    返回 (ops_list, err_list) —— 与论文 Fig.1 的横/纵轴一致。
+    """
+    n = env.n_states
+    V = np.zeros(n)
+    ops_list, err_list = [], []
+    total = 0
+    # 每次都从 s0 开始扫(顺序会显著影响效率, 这里固定在自然顺序, 对三种方法一致)
+    order = list(range(n))
+    while total < max_ops:
+        for s in order:
+            if env.is_goal[s]:
+                V[s] = 0.0
+                continue
+            best = -np.inf
+            # primitive
+            for a in range(N_ACT):
+                val = 0.0
+                for p, ns in env.T[s][a]:
+                    val += p * (env.R[s][a] + env.gamma * V[ns])
+                    total += 1
+                if val > best:
+                    best = val
+            # options —— SMDP:  r_disc + gamma^k * V(s_term)
+            for name, M in option_models.items():
+                for ent in M[s]:
+                    p, s_term, r_disc, k = ent[0], ent[1], ent[2], (ent[3] if len(ent) > 3 else 1.0)
+                    val = p * (r_disc + (env.gamma ** k) * V[s_term])
+                    total += 1
+                    if val > best:
+                        best = val
+            V[s] = best
+        err = abs(V[s0] - v_star)
+        ops_list.append(total)
+        err_list.append(err)
+        if err < tol:
+            break
+    return ops_list, err_list
+
+
+def ops_to_tolerance(env, option_models, v_star, s0, tol=0.01, max_ops=400000):
+    ops, errs = planning_curve(env, option_models, v_star, s0, tol=tol, max_ops=max_ops)
+    return ops[-1], errs[-1], ops, errs

hibs_lnn/swifttd_head.py

@@ -0,0 +1,435 @@
+"""
+V31.1: SwiftTD 式 per-feature step-size 优化 (Javed et al., RLC 2024)
+=====================================================================
+解决 V31.0 发现的问题: IDBD 融合的 β 通过 BPTT 外循环学 (Meta-SGD 风格),
+meta 梯度 ~1e-6 学不动 (arXiv 2401.17401 Figure 4)。
+
+SwiftTD 三件套 (全部在线, 无 BPTT) — 精确对应论文 Algorithm 1:
+  1. per-feature step-size 优化: β[i] = e^{θ[i]}, IDBD 在线更新:
+         θ[i] += κ·δ[i]·h[i]·φ[i]                    (meta 更新, 在 decay/重置之前)
+         h[i] ← (1-β[i]·φ[i]²)⁺·h[i] + β[i]·δ[i]·φ[i]  (step-size 迹)
+  2. overshoot bound: correction ratio τ = Σᵢ β[i]·φ[i]²,
+         τ > η 时更新缩放 s = η/τ (η = 0.1, max correction ratio)
+  3. step-size decay: τ > η 时 θ[i] += φ[i]²·ln(ϵ) (ϵ = 0.99 decay rate,
+       论文 Algorithm 1: 对 θ 的绝对衰减, 无 β 因子; β ← β·ϵ^{φ²})
+       且重置该组的迹 (论文 L524-526)
+
+论文关键超参: η = 0.1, ϵ = 0.99, η_min = e^-15, β 裁剪到 [ln(η_min), ln(η)] → β_max = η。
+
+本实现的关键适配 (记录在 wiki):
+  τ 按输出行 (per-row) 计算。论文的 correction ratio 定义在单个标量预测
+  上 (v = w·φ, 更新后 v' = v + s·β·δ·Σφ²); 我们的 head 有 n2 = 1616 个
+  标量输出 (8 响应 × 202 vocab), 每个输出是独立的预测、独立的误差。
+  w2 的行 u 有它自己的 τ_u = Σₖ β[u,k]·xₖ² 和缩放 s_u — 这是论文
+  "单预测 bound" 对多输出层的直接推广。若用全局 τ (早期版本), 1616 行
+  复制结构使 τ 被维度主导 → bound 永远触发 → 更新塌缩到 ~0 (实测失败)。
+  同样地, w1 按 d 行, b1/b2 是向量 (单一 τ)。
+
+  没有特征归一化: raw 特征保持 IDBD 元梯度 O(1) 尺度 (归一化会把
+  per-feature 元更新稀释到 1/N, 40 步内 β 纹丝不动, 实测失败)。
+
+行为: β ≤ η 且 τ ≈ β̄·Σφ² ≫ η (raw 特征) → bound 常态触发 → 每行每步
+修正恰好 η·errs (10%), decay 把 β 压到 τ≈η 的预算, IDBD 在预算内把
+步长分配给有用特征 (const 特征 → β_min, 相关特征 → 维持)。这正是论文
+Section 6 描述的收敛行为。
+
+应用对象: PLN (2 层 MLP head)。每组用"入边激活"作为 IDBD 特征 φ:
+  w1 (d,d)  : φ = hidden[j]      (SSM 输出), δ = 回传误差 g[i]
+  b1 (d,)   : φ = 1, δ = g[i]
+  w2 (n2,d) : φ = x[i]           (tanh 激活), δ = errs[u]
+  b2 (n2,)  : φ = 1, δ = errs[u]
+其中 errs = p - onehot 是 CE 对 logits 的残差 (梯度)。
+"""
+
+import math
+import torch
+import torch.nn.functional as F
+
+
+class SwiftTDHead:
+    """
+    2 层 MLP head 的 SwiftTD 步长状态机 (V31.1)。
+
+    参数布局 (与 V31 head_forward 一致):
+      W = [w1 (d,d), b1 (d,), w2 (n2,d), b2 (n2,)],  n2 = vocab*n_resp
+      x = tanh(hidden @ w1^T + b1);  logits = x @ w2^T + b2 → (n_resp, vocab)
+
+    状态:
+      theta: 每参数 log 步长 θ (对应 β = e^θ, 裁剪到 [β_min, β_max=η])
+      h    : 每参数 step-size 迹 (IDBD 的 h 向量)
+
+    超参 (论文默认):
+      beta_init : 初始 β (论文 1e-7 长流; 短视野用 0.01)
+      kappa     : IDBD meta step-size θ
+      eta       : max correction ratio η = 0.1 (bound 阈值 = β 上限)
+      eps       : decay rate ϵ = 0.99 (bound 触发时的衰减速率, 独立超参)
+    """
+
+    def __init__(self, d_model, world_vocab, n_resp,
+                 beta_init=0.01, kappa=0.05, eta=0.1, eps=0.99,
+                 beta_min=1e-7, input_dim=None, tau_norm=None):
+        """
+        input_dim (V32 意图注入用): w1 的输入维度。
+        默认 input_dim=d_model → 与 V31 布局完全一致 (向后兼容)。
+        d_model 始终是隐藏层宽度 (x 的维度, w2 的输入)。
+        tau_norm (V35.2 诊断 A): 按有效维度归一 τ。
+          None/False: 原版 τ = Σ β·φ² (绝对和)
+          'mean'    : τ = Σ β·φ² / dim (per-dim 平均 — 修复 V32+ 3d 意图
+                      注入后 384 维求和恒超 η → bound 常态触发 → h 迹归零
+                      → IDBD 分化死亡, β_std 1.6e-05 的诊断根因)
+        """
+        self.d_model = d_model
+        self.input_dim = input_dim if input_dim is not None else d_model
+        self.world_vocab = world_vocab
+        self.n_resp = n_resp
+        self.n2 = world_vocab * n_resp
+        self.tau_norm = tau_norm
+        # 布局: [w1 (d, input_dim), b1 (d,), w2 (n2,d), b2 (n2,)]
+        self.shapes = [(d_model, self.input_dim), (d_model,),
+                       (self.n2, d_model), (self.n2,)]
+        self.beta_init = beta_init
+        self.kappa = kappa
+        self.eta = eta              # max correction ratio (bound 阈值)
+        self.eps = eps              # decay rate (独立超参!)
+        self.beta_max = eta         # 论文: β 裁剪上限 = ln(η)
+        self.beta_min = beta_min
+        self.reset_state()
+
+    # ── 状态��理 ─────────────────────────────────────────────
+    def reset_state(self):
+        self.theta = [torch.full(s, math.log(self.beta_init)) for s in self.shapes]
+        self.h = [torch.zeros(s) for s in self.shapes]
+        self.n_bound_triggers = 0
+        self.n_decays = 0
+        self.n_steps = 0
+
+    def to(self, device):
+        """搬移 SwiftTD 状态 (θ/h 迹) 到 device (head 是普通类, 非 nn.Module)."""
+        self.theta = [t.to(device) for t in self.theta]
+        self.h = [t.to(device) for t in self.h]
+        return self
+
+    def cpu(self):
+        return self.to('cpu')
+
+    def beta(self):
+        return [t.exp().clamp(self.beta_min, self.beta_max) for t in self.theta]
+
+    def step_size_stats(self):
+        b = torch.cat([x.reshape(-1) for x in self.beta()])
+        return {
+            'n_params': int(b.numel()),
+            'beta_mean': float(b.mean()),
+            'beta_std': float(b.std()),
+            'beta_min': float(b.min()),
+            'beta_max': float(b.max()),
+            'frac_clipped_min': float(
+                (b <= self.beta_min * (1 + 1e-3)).float().mean()),
+            'frac_clipped_max': float(
+                (b >= self.beta_max * (1 - 1e-3)).float().mean()),
+            'n_bound_triggers': self.n_bound_triggers,
+            'n_decays': self.n_decays,
+            'n_steps': self.n_steps,
+        }
+
+    def state(self):
+        """保存当前状态 (θ/h 迹), 用于 sleep 前后快照。"""
+        return ([t.clone() for t in self.theta], [t.clone() for t in self.h])
+
+    def load_state(self, st):
+        theta, h = st
+        for t, v in zip(self.theta, theta):
+            t.copy_(v)
+        for t, v in zip(self.h, h):
+            t.copy_(v)
+
+    # ── 核心: 单样本在线一步 ─────────────────────────────────
+    def step(self, W, hidden, x, errs):
+        """
+        对一个样本做一步 SwiftTD 更新 (原地修改 W, 无计算图)。
+        W     : [w1,b1,w2,b2] 当前参数
+        hidden: SSM 输出 (d,)
+        x     : tanh 激活 (d,)
+        errs  : (n2,) = p - onehot (CE 对 logits 的残差)
+        """
+        newW = self._rates(W, hidden, x, errs, graph=False)
+        for old, new in zip(W, newW):
+            old.copy_(new)
+        return W
+
+    def step_graph(self, W, hidden, x, errs):
+        """
+        可微内循环一步 (V31.2 BPTT 外循环用):
+        与 step() 相同的 SwiftTD 速率 (s, β 全 detached),
+        但权重更新保持计算图 → 外循环梯度穿过内循环链
+        (RLN 特征 φ → 误差 δ → w 更新 → query loss)。
+        """
+        return self._rates(W, hidden, x, errs, graph=True)
+
+    def _rates(self, W, hidden, x, errs, graph):
+        """
+        SwiftTD 速率计算 + 权重更新 (graph=False 原地, graph=True 新张量)。
+        s 与 β 为 detached 速率 (bound/decay/clip 不可微, 论文 BPTT 不可用
+        → 直通: 速率当作给定常数, 只对 w 链与特征链反传)。
+        """
+        w1, b1, w2, b2 = W
+        d, din, n2 = self.d_model, self.input_dim, self.n2
+
+        # 各组特征 φ 与误差 δ (IDBD 逐元素形式)
+        dev = hidden.device
+        f_w1 = hidden.unsqueeze(0).expand(d, self.input_dim).contiguous()
+        f_b1 = torch.ones(d, device=dev)
+        f_w2 = x.unsqueeze(0).expand(n2, d).contiguous()        # (n2,d)
+        f_b2 = torch.ones(n2, device=dev)
+
+        d_w1 = (w2.t() @ errs) * (1.0 - x * x)                  # (d,) 回传误差
+        d_w1 = d_w1.unsqueeze(1).expand(d, self.input_dim).contiguous()
+        d_b1 = d_w1[:, 0]
+        d_w2 = errs.unsqueeze(1).expand(n2, d).contiguous()     # (n2,d)
+        d_b2 = errs
+
+        beta = self.beta()
+        ln_eps = math.log(self.eps)  # ϵ<1 → 负; 论文 Algorithm 1: β += φ²·ln(ϵ)
+
+        def _group(w, f, dg, gi, row_tau):
+            """返回 (更新后的 w, 速率 s·β 用于图形更新)。"""
+            b = beta[gi]
+            # 1) meta-θ 更新 (先于 decay/reset — 论文顺序)
+            self.theta[gi].add_(self.kappa * dg.detach() * self.h[gi] * f.detach())
+            # 2) 速率: τ 与缩放 s (detached)
+            if row_tau:
+                tau = (b * f.detach() * f.detach()).sum(dim=1)
+                if self.tau_norm == 'mean':
+                    tau = tau / f.shape[1]     # per-dim 平均 (诊断 A)
+            else:
+                tau = (b * f.detach() * f.detach()).sum()
+                if self.tau_norm == 'mean' and f.dim() == 1:
+                    tau = tau / f.shape[0]     # b1/b2 向量: 按元素数归一
+            s = torch.ones_like(tau)
+            trig = tau > self.eta
+            if bool(trig.any()):
+                s = torch.where(trig, self.eta / tau, s)
+                # 3) decay + 迹重置 (仅触发行)
+                self.theta[gi][trig].add_(
+                    ln_eps * (f.detach() * f.detach())[trig])
+                self.h[gi][trig].zero_()
+                self.n_bound_triggers += int(trig.sum())
+                self.n_decays += int(trig.sum())
+            # 4) h 更新 + clip θ → β ∈ [β_min, η] (论文 Section 6)
+            self.h[gi].mul_(torch.clamp(
+                1.0 - b * f.detach() * f.detach(), min=0.0))
+            self.h[gi].add_(b * dg.detach() * f.detach())
+            self.theta[gi].clamp_(math.log(self.beta_min),
+                                  math.log(self.beta_max))
+            # 速率 (detached): s·β, 广播到 f 形状
+            if f.dim() == 2:
+                s = s.unsqueeze(1)
+            rate = (s * b).detach()
+            if graph:
+                return w - rate * dg * f, rate
+            return w - rate * dg * f, rate
+
+        w1n, _ = _group(w1, f_w1, d_w1, 0, row_tau=True)
+        b1n, _ = _group(b1, f_b1, d_b1, 1, row_tau=False)
+        w2n, _ = _group(w2, f_w2, d_w2, 2, row_tau=True)
+        b2n, _ = _group(b2, f_b2, d_b2, 3, row_tau=False)
+
+        self.n_steps += 1
+        return [w1n, b1n, w2n, b2n]
+
+    # ── 便捷封装: 单样本适应 ─────────────────────────────────
+    def adapt_sample(self, W, hidden, tgt, V):
+        """hidden: (1,d) SSM 输出; tgt: (n_resp,) 目标 token。"""
+        d = self.d_model
+        x = torch.tanh(hidden @ W[0].t() + W[1])
+        logits = x @ W[2].t() + W[3]                            # (1, n2)
+        logits = logits.view(1, self.n_resp, self.world_vocab)
+        p = F.softmax(logits, dim=-1)
+        onehot = F.one_hot(tgt, self.world_vocab).float()
+        errs = (p - onehot).reshape(-1)                         # (n2,)
+        self.step(W, hidden[0], x[0], errs.detach())
+        return logits
+
+
+# ============================================================
+# 自测 1: 论文 weight-flipping 问题 (arXiv 2401.17401 §3)
+# 20 维特征, 前 15 维权重恒为 0 (该学低步长), 后 5 维每 20 步翻转 ±1
+# (该学高步长)。IDBD 应学到 per-feature 步长分化, 且性能好于标量 SGD。
+# 单行 = 单预测, 与模块 row_tau=True 逻辑一致。
+# ============================================================
+def _idbd_linear_step(w, theta, h, phi, delta, kappa, eta, eps,
+                      beta_min, beta_max):
+    """单行线性预测的 SwiftTD 一步 (与模块逻辑一致, 供自测复用)。"""
+    b = theta.exp().clamp(beta_min, beta_max)
+    # 1) meta-θ 更新 (先于 decay/reset — 论文顺序)
+    theta.add_(kappa * delta * h * phi)
+    # 2) 权重更新 (bound 缩放)
+    tau = (b * phi * phi).sum()
+    s = 1.0
+    decayed = False
+    if tau > eta:
+        s = eta / tau
+        # 3) decay (绝对衰减, 无 β 因子) + 迹重置
+        theta.add_(math.log(eps) * phi * phi)
+        h.zero_()
+        decayed = True
+    w.add_(s * b * delta * phi)
+    # 4) h 更新
+    h.mul_(torch.clamp(1.0 - b * phi * phi, min=0.0))
+    h.add_(b * delta * phi)
+    theta.clamp_(math.log(beta_min), math.log(beta_max))
+    return w, theta, h, decayed
+
+
+def _self_test_weight_flipping(seed=42, n_steps=50000, kappa=0.05,
+                               beta_init=0.1, verbose=True):
+    torch.manual_seed(seed)
+    d = 20
+    w_true = torch.zeros(d)
+    w_true[15:] = 1.0
+
+    def run_idbd():
+        # 快速追踪域 (论文 Figure 5 探索范围): η=0.5, β_max=1.0
+        # 翻转每 20 步一次 → 每步需 ~100% 修正 → β 上限需 > η。
+        # MLP head 的收敛域 (β_max=η=0.1) 由自测 3 覆盖。
+        beta_min, beta_max, eta, eps = 1e-5, 1.0, 0.5, 0.99
+        theta = torch.full((d,), math.log(beta_init))
+        h = torch.zeros(d)
+        w = torch.zeros(d)
+        errs = []
+        for t in range(n_steps):
+            if t % 20 == 0:
+                idx = 15 + (t // 20) % 5
+                w_true[idx] *= -1
+            phi = torch.randn(d)
+            y = (w_true * phi).sum()
+            delta = y - (w * phi).sum()
+            w, theta, h, _ = _idbd_linear_step(
+                w, theta, h, phi, delta, kappa, eta, eps, beta_min, beta_max)
+            errs.append(delta.item() ** 2)
+        return sum(errs) / len(errs), theta.exp()
+
+    def run_scalar(alpha):
+        w = torch.zeros(d)
+        errs = []
+        for t in range(n_steps):
+            if t % 20 == 0:
+                idx = 15 + (t // 20) % 5
+                w_true[idx] *= -1
+            phi = torch.randn(d)
+            y = (w_true * phi).sum()
+            delta = y - (w * phi).sum()
+            w.add_(alpha * delta * phi)
+            errs.append(delta.item() ** 2)
+        return sum(errs) / len(errs)
+
+    mse_idbd, beta_end = run_idbd()
+    b_hi = beta_end[15:].mean().item()
+    b_lo = beta_end[:15].mean().item()
+    # 标量基线: 在非发散区间内扫 α, 取最优
+    mse_scalar = min(run_scalar(a) for a in (0.001, 0.005, 0.01, 0.02, 0.05))
+
+    if verbose:
+        print(f"  [weight-flipping] MSE: idbd={mse_idbd:.5f} "
+              f"scalar_best={mse_scalar:.5f}")
+        print(f"    β 均值: const dims={b_lo:.5f} (应低), "
+              f"flip dims={b_hi:.5f} (应高), 比值={b_hi / max(b_lo, 1e-9):.1f}x")
+
+    ok = (mse_idbd <= mse_scalar * 1.05 and b_hi > b_lo * 3)
+    print(f"  {'OK' if ok else 'FAIL'} IDBD 学到 per-feature 步长 "
+          f"(误差更低 + 高/低步长分化)")
+    return ok
+
+
+# ============================================================
+# 自测 2: 三件套在 β_init 过大时不发散 (bound + decay + 迹重置)
+# ============================================================
+def _self_test_bound_stability(seed=42, n_steps=20000, beta_init=0.5,
+                               verbose=True):
+    torch.manual_seed(seed)
+    d = 20
+    w_true = torch.zeros(d)
+    w_true[15:] = 1.0
+    kappa, eta, eps, beta_min, beta_max = 0.05, 0.5, 0.99, 1e-5, 1.0
+
+    def run(alpha, use_swift=False):
+        theta = torch.full((d,), math.log(beta_init))
+        h = torch.zeros(d)
+        w = torch.zeros(d)
+        errs = []
+        for t in range(n_steps):
+            if t % 20 == 0:
+                idx = 15 + (t // 20) % 5
+                w_true[idx] *= -1
+            phi = torch.randn(d)
+            y = (w_true * phi).sum()
+            delta = y - (w * phi).sum()
+            if use_swift:
+                w, theta, h, _ = _idbd_linear_step(
+                    w, theta, h, phi, delta, kappa, eta, eps,
+                    beta_min, beta_max)
+            else:
+                w.add_(alpha * delta * phi)
+            errs.append(delta.item() ** 2)
+            if math.isnan(delta.item()):
+                return float('inf')
+        return sum(errs) / len(errs)
+
+    mse_swift = run(0.0, use_swift=True)
+    mse_scalar = run(beta_init)
+    ok = math.isfinite(mse_swift) and mse_swift < mse_scalar
+    if verbose:
+        print(f"  [bound 稳定性] β_init={beta_init}: "
+              f"scalar(α={beta_init}) MSE={mse_scalar:.5f} (应发散/爆炸), "
+              f"SwiftTD MSE={mse_swift:.5f}")
+    print(f"  {'OK' if ok else 'FAIL'} bound+decay 防止发散")
+    return ok
+
+
+# ============================================================
+# 自测 3: MLP head 单步形状 + loss 下降 + β 分化
+# ============================================================
+def _self_test_mlp_head():
+    torch.manual_seed(0)
+    d, V, n_resp = 8, 20, 2
+    head = SwiftTDHead(d, V, n_resp, beta_init=0.01)
+    w1 = torch.randn(d, d) * 0.5
+    b1 = torch.zeros(d)
+    w2 = torch.randn(V * n_resp, d) * 0.5
+    b2 = torch.zeros(V * n_resp)
+    W = [w1, b1, w2, b2]
+    hidden = torch.randn(1, d)
+    tgt = torch.tensor([3, 17])
+
+    def loss():
+        x = torch.tanh(hidden @ w1.t() + b1)
+        logits = (x @ w2.t() + b2).view(1, n_resp, V)
+        return F.cross_entropy(logits.view(-1, V), tgt.view(-1))
+
+    l0 = loss().item()
+    for _ in range(30):
+        x = torch.tanh(hidden @ w1.t() + b1)
+        logits = (x @ w2.t() + b2).view(1, n_resp, V)
+        p = F.softmax(logits, dim=-1)
+        onehot = F.one_hot(tgt, V).float()
+        errs = (p - onehot).reshape(-1)
+        head.step(W, hidden[0], x[0], errs.detach())
+    l1 = loss().item()
+    stats = head.step_size_stats()
+    ok = l1 < l0 and stats['beta_mean'] > 0
+    print(f"  {'OK' if ok else 'FAIL'} MLP head 30 步: loss "
+          f"{l0:.4f} → {l1:.4f}, β_mean={stats['beta_mean']:.4f}, "
+          f"bound 触发={stats['n_bound_triggers']}, decay={stats['n_decays']}")
+    return ok
+
+
+def _self_test():
+    ok1 = _self_test_weight_flipping()
+    ok2 = _self_test_bound_stability()
+    ok3 = _self_test_mlp_head()
+    print(f"\n  {int(ok1) + int(ok2) + int(ok3)}/3 passed")
+    return ok1 and ok2 and ok3
+
+
+if __name__ == "__main__":
+    _self_test()

hibs_lnn/transition_model.py

@@ -0,0 +1,118 @@
+"""transition_model.py — OaK 第③条的第一个缺失件。
+
+## 为什么需要它
+
+OaK feature #3:
+    feature -> subproblem -> solution -> **transition model** -> planning
+
+我们已经有 feature / subproblem(6 域 / 60 细区间)/ solution(训练),
+但**没有转移模型也无法规划** —— 这是 leo 那张映射表里真正缺的东西。
+
+## 定义 (与 lm4 的数据结构对齐)
+
+    能力状态 a_t    = acc_matrix[t]        (在 6 个域上的准确率画像, 6 维)
+    动作     u_t    = 第 t 步训练了哪个域   (one-hot, 6 维)
+    转移     T      : (a_t, u_t, ctx) -> Δa,   a_{t+1} = a_t + Δa
+
+学 **Δa** 而不是 a_{t+1}, 因为这样 "copy 基线" 就是 Δa≡0,
+模型有没有学到东西一目了然。
+
+## 输入特征
+
+    x = [ a_t (6) | onehot(u_t) (6) | n_visits (6) | t/n_rounds (1) ]   = 19 维
+
+## 基线 (必须打赢才有意义)
+
+    copy     : Δa ≡ 0                     实测 MAE 0.2986
+    constant : Δa ≡ mean(Δa|u)            实测 MAE 0.2723
+
+用 **ridge** 而不是 MLP: 样本量 ~1.8K, 参数少、可复现、无调参空间
+(符合 leo 的"manual > framework"偏好)。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class TransitionModel:
+    """T(a_t, u_t, ctx) -> Δa 的线性(脊)转移模型。
+
+    参数
+    ----
+    lam : 岭正则强度
+    """
+
+    def __init__(self, lam=1e-2):
+        self.lam = float(lam)
+        self.W = None            # (fdim, n_dom)
+        self.n_dom = None
+        self.fitted = False
+
+    # ───────── 特征 ─────────
+    @staticmethod
+    def feat(a, u, n_visits, t_frac):
+        oh = np.zeros(len(a))
+        if 0 <= u < len(a):
+            oh[u] = 1.0
+        return np.concatenate([a, oh, n_visits, [t_frac]])
+
+    def build_xy(self, records):
+        """records: [(acc_matrix, dom_seq)] -> X, Y, groups"""
+        X, Y, G = [], [], []
+        for gi, (M, seq) in enumerate(records):
+            M = np.asarray(M, dtype=float)
+            n_dom = M.shape[1]
+            nvis = np.zeros(n_dom)
+            for t, u in enumerate(seq):
+                if t + 1 >= M.shape[0]:
+                    break
+                if np.isnan(M[t]).any() or np.isnan(M[t + 1]).any():
+                    nvis[u] += 1
+                    continue
+                X.append(self.feat(M[t], int(u), nvis.copy(), t / max(1, len(seq))))
+                Y.append(M[t + 1] - M[t])
+                G.append(gi)
+                nvis[u] += 1
+        return (np.array(X), np.array(Y), np.array(G)) if X else (
+            np.zeros((0, 19)), np.zeros((0, 6)), np.zeros(0))
+
+    # ───────── 拟合 ─────────
+    def fit(self, records):
+        X, Y, _ = self.build_xy(records)
+        if len(X) == 0:
+            raise ValueError("没有可用样本")
+        self.n_dom = int(Y.shape[1])
+        # 只对 Δa 做岭回归 (含截距)
+        X1 = np.hstack([X, np.ones((len(X), 1))])
+        A = X1.T @ X1 + self.lam * np.eye(X1.shape[1])
+        self.W = np.linalg.solve(A, X1.T @ Y)
+        self.fitted = True
+        return self
+
+    def predict_delta(self, a, u, n_visits, t_frac):
+        x = np.append(self.feat(a, u, n_visits, t_frac), 1.0)
+        return x @ self.W
+
+    # ───────── 规划: 用 T 前向搜索选动作序列 ─────────
+    def plan(self, a0, horizon, beam=8, n_dom=None):
+        """beam search: 在 T 的预测下最大化末端平均准确率。
+
+        这是 OaK 的 "planning" —— 用学到的转移模型做前向搜索,
+        而不是靠外生给定的 schedule。
+        """
+        n_dom = int(n_dom if n_dom is not None else (self.n_dom or 0))
+        a0 = np.asarray(a0, dtype=float)
+        # beam 元素: (score, a, nvis, seq)
+        beams = [(float(np.nanmean(a0)), a0.copy(), np.zeros(n_dom), [])]
+        for t in range(horizon):
+            cand = []
+            for _, a, nvis, seq in beams:
+                for u in range(n_dom):
+                    d = self.predict_delta(a, u, nvis, t / max(1, horizon))
+                    a2 = a + d
+                    nv2 = nvis.copy()
+                    nv2[u] += 1
+                    cand.append((float(np.nanmean(a2)), a2, nv2, seq + [u]))
+            cand.sort(key=lambda r: -r[0])
+            beams = cand[:beam]
+        return beams[0][3]

hibs_lnn/uncertainty_gate.py

@@ -0,0 +1,239 @@
+"""uncertainty_gate.py — 覆盖度 + 不确定性门控, 与带不确定性的 rollout。
+
+## 为什么需要
+
+用户指出: 被动观测数据学出的 transition model **只知道数据覆盖过的 (s,a)**。
+若 policy 提出训练数据里没出现过的动作, `T(s,a_new)` 可能完全是幻觉。
+这正是我们实测到的: 转移模型对 `[2,2,2,2,2]` 预测 **0.9582**, 真实执行 **0.4357**。
+
+于是把「覆盖度门控」升级为两个条件:
+
+    allow(s,a) = [C(s,a) > tau_C]  ∧  [U_T(s,a) < tau_U]
+
+    C(s,a) : 该 (状态, 动作) 有多少数据支持 (访问计数)
+    U_T    : 转移预测的不确定性
+
+## U_T 怎么估 —— 用集成分歧, 不用拍脑袋
+
+单个模型无法报出自己有多不确定。标准做法是训练 **K 个 transition model**
+(对数据做 bootstrap), 用它们的**预测分歧**作为 U_T:
+
+    U_T(s,a) = mean_i || T_i(s,a) − mean_j T_j(s,a) ||
+
+分歧大 = 该区域数据稀疏 / 模型没学到 → 不可信。
+这与 coverage 互补: coverage 看「来过没有」, U_T 看「学稳了没有」。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class TransitionEnsemble:
+    """K 个 bootstrap 转移模型的集成, 用预测分歧估计不确定性。
+
+    T_i: x_{t+1} = x_t + Δ_i,  Δ_i = W_i @ φ(x_t, u)
+    """
+
+    def __init__(self, n_models=5, lam=1e-2, seed=0):
+        self.K = int(n_models)
+        self.lam = float(lam)
+        self.rng = np.random.default_rng(seed)
+        self.Ws = None
+        self.n_dom = None
+        self.dim_x = None
+        self.fdim = None
+
+    # ───────── 特征 ─────────
+    @staticmethod
+    def feat(x, u, n_dom, visits):
+        """特征 = [x, onehot(u)]。
+
+        ★ **不要加入常数列** (曾写成 concat([x, oh, [mean(visits)]]) 而
+        mean(visits)≡1 与截距完全共线): 实测条件数被推到 **1.24e16**(近乎奇异),
+        后果是双向的 ——
+          ① 预测全错: Δ 估计 [35.6, 32.5, 10.3, 5.7], 真值应 ~0.3
+          ② 不确定性失效: U_T 对所有动作都 ≈3.27, 完全不区分噪声
+        去掉后: Δ 恢复 [0.30, 0, 0, 0], U_T 动作0(噪声.02)=0.0018 vs
+        动作2(噪声.55)=0.0399 -> **22× 区分**。
+        """
+        oh = np.zeros(n_dom)
+        if 0 <= u < n_dom:
+            oh[u] = 1.0
+        return np.concatenate([x, oh])
+
+    # ───────── 拟合 (bootstrap) ─────────
+    def fit(self, X, Y, n_dom, visits_dim=None):
+        """X: (N, dim_x+1) = [x_t, u];  Y: (N, dim_x) = **绝对** x_{t+1}。
+
+        ★ 接口约定: fit 与 predict **都用绝对下一状态**, 内部学 Δ 再加回 x。
+        曾因约定不一致出过 bug —— 测试把绝对状态当 Δ 喂进来, 在质心 (x=0)
+        处两者巧合相等, 掩盖了问题; 一旦远离质心 (R0=[4.95,4.55,1.36,1.22])
+        就露出 `Δ=x+fx(u)` 的错误。现在接口自洽, 无法再误用。
+        """
+        self.dim_x = Y.shape[1]
+        self.n_dom = int(n_dom)
+        self.fdim = self.dim_x + self.n_dom          # 无截距列
+        N = len(X)
+        D = Y - X[:, :self.dim_x]                    # 内部转成 Δ
+        self.Ws = []
+        for k in range(self.K):
+            idx = self.rng.integers(0, N, size=N)          # bootstrap 重采样
+            F = np.array([self.feat(X[i, :self.dim_x], int(X[i, -1]),
+                                    self.n_dom, np.ones(self.n_dom))
+                          for i in idx])
+            # ★ 不加截距列。onehot(u) 的各列之和恒等于 1, 与截距**完全共线**
+            #   (Σ onehot = ones)。加了以后条件数 8.9e15, 解只在数据质心附近
+            #   碰巧正确, 远离即炸: 实测在区域中心 (R0=[4.95,4.55,1.36,1.22])
+            #   给出 Δ=[92.7, 96.4, 25.8, 23.7], 真值应为 [0.30, 0, 0, 0]。
+            #   去掉后设计矩阵满秩 (rank = dim_x + n_dom)。
+            A = F.T @ F + self.lam * np.eye(F.shape[1])
+            self.Ws.append(np.linalg.solve(A, F.T @ D[idx]))
+        return self
+
+    # ───────── 预测 + 分歧 ─────────
+    def predict(self, x, u, visits):
+        """返回 (**绝对**下一状态的集成均值, 分歧 U_T)。"""
+        if self.Ws is None:
+            return np.asarray(x, dtype=float).copy(), float("inf")
+        x = np.asarray(x, dtype=float)
+        f = self.feat(x, u, self.n_dom, visits)             # 与 fit 一致, 无截距
+        preds = np.array([f @ W for W in self.Ws])          # (K, dim_x) = Δ
+        mean_d = preds.mean(0)
+        unc = float(np.mean(np.linalg.norm(preds - mean_d, axis=1)))
+        return x + mean_d, unc                              # 绝对下一状态
+
+    def rollout(self, x0, actions, visits, gate=None):
+        """多步 rollout: T^k(x0, a_{t:t+k})。返回 (轨迹, 逐步不确定性)。
+
+        gate 非 None 时逐步做可信度检查; 一旦某步不可信��**中止并标记**,
+        而不是继续外推 (Q8: 无覆盖 → 预测不可靠)。
+        """
+        x = np.asarray(x0, dtype=float).copy()
+        traj, uncs, aborted_at = [x.copy()], [], None
+        for t, u in enumerate(actions):
+            if gate is not None:
+                ok, why = gate.allow(x, u, visits)
+                if not ok:
+                    aborted_at = (t, why)
+                    break
+            x_next, unc = self.predict(x, u, visits)        # 已是绝对状态
+            if not np.isfinite(unc):
+                aborted_at = (t, "unc_inf")
+                break
+            x = x_next
+            traj.append(x.copy())
+            uncs.append(unc)
+        return np.array(traj), np.array(uncs), aborted_at
+
+
+class TabularTransition:
+    """计数式转移模型 —— 离散状态空间上的**可表达**动力学。
+
+    ## 为什么必须加它 (实测动机)
+
+    `TransitionEnsemble` 是**线性 ridge 回归** (`[state, onehot(action)] -> next`),
+    对**离散、条件性、非线性**的动力学表达能力不足。实测在 KeyDoor 这类
+    链式任务上: 从区域中心出发, **四个动作预测到同一个下一状态** ->
+    转移图退化成几乎无边 -> `OptionManager` 发现 0 个 option
+    (即使任务里有明显的"拿钥匙→开门"技能链)。
+
+    ★ 结论: option 发现失败**不是 option 逻辑的问题, 而是它依赖的世界模型
+      表达不了结构化动力学**。这里是那个缺口的补丁。
+
+    `predict(x, a)` 与 `TransitionEnsemble` **接口一致**, 可直接替换:
+      返回 (最可能的下一状态, 不确定性)
+    不确定性 = 1 − max_a' P(s'|s,a) —— 即"这个转移有多确定"。
+    """
+    def __init__(self, lam=1.0):
+        self.counts = {}          # (s_key, a) -> {s'_key: n}
+        self.state_map = {}       # s_key -> 原状态向量
+        self.lam = float(lam)
+        self.dim_x = None
+        self.n_dom = None
+
+    @staticmethod
+    def _key(x):
+        return tuple(np.round(np.asarray(x, dtype=float), 6).tolist())
+
+    def fit(self, X, Y, n_dom, visits_dim=None):
+        X = np.asarray(X, dtype=float); Y = np.asarray(Y, dtype=float)
+        self.dim_x = Y.shape[1]; self.n_dom = int(n_dom)
+        self.counts, self.state_map = {}, {}
+        for i in range(len(X)):
+            x, u, y = X[i, :self.dim_x], int(X[i, -1]), Y[i]
+            sk, yk = self._key(x), self._key(y)
+            self.state_map[sk] = x
+            self.counts.setdefault((sk, u), {})
+            self.counts[(sk, u)][yk] = self.counts[(sk, u)].get(yk, 0) + 1
+        return self
+
+    def predict(self, x, u, visits=None):
+        """返回 (最可能下一状态向量, 不确定性 1−P_max)。未见过的 (s,a) -> 原状态 + unc=inf。"""
+        sk = self._key(x)
+        d = self.counts.get((sk, int(u)))
+        if not d:
+            return np.asarray(x, dtype=float).copy(), float("inf")
+        tot = sum(d.values())
+        yk, c = max(d.items(), key=lambda kv: kv[1])
+        return np.array(yk, dtype=float), float(1.0 - c / tot)
+
+    def rollout(self, x0, actions, visits=None, gate=None):
+        x = np.asarray(x0, dtype=float).copy()
+        traj, uncs, aborted = [x.copy()], [], None
+        for t, u in enumerate(actions):
+            if gate is not None:
+                ok, why = gate.allow(x, u, visits if visits is not None else np.ones(1))
+                if not ok:
+                    aborted = (t, why); break
+            xn, unc = self.predict(x, u, visits)
+            if not np.isfinite(unc):
+                aborted = (t, "unc_inf"); break
+            x = xn; traj.append(x.copy()); uncs.append(unc)
+        return np.array(traj), np.array(uncs), aborted
+
+
+class UncertaintyGate:
+    """allow(s,a) = [C(s,a) > tau_C] ∧ [U_T(s,a) < tau_U]
+
+    参数
+    ----
+    tau_C : 覆盖度阈值 (访问计数的分位/绝对阈值)
+    tau_U : 不确定性阈值 (集成分歧)
+    """
+
+    def __init__(self, tau_C=1.0, tau_U=None, adaptive=True):
+        self.tau_C = float(tau_C)
+        self.tau_U = tau_U
+        self.adaptive = adaptive
+        self.unc_hist = []
+
+    def calibrate(self, uncs):
+        """用一批**在训练数据上**的集成分歧定阈值 (取 90 分位)。
+
+        自适应是必要的: 分歧的量纲随任务变化, 硬编码阈值不可移植。
+        """
+        u = np.asarray(uncs, dtype=float)
+        u = u[np.isfinite(u)]
+        if u.size:
+            self.tau_U = float(np.quantile(u, 0.90))
+        return self.tau_U
+
+    def allow(self, x, u, visits):
+        """返回 (是否允许, 原因)。"""
+        c = float(visits[u]) if u < len(visits) else 0.0
+        if c <= self.tau_C:
+            return False, "low_coverage"
+        return True, "ok"          # 不确定性检查在 rollout 内逐步做
+
+    def allow_with_unc(self, x, u, visits, unc):
+        """含不确定性判定的完整版。"""
+        ok, why = self.allow(x, u, visits)
+        if not ok:
+            return False, why
+        if self.tau_U is not None and np.isfinite(unc) and unc > self.tau_U:
+            return False, "high_uncertainty"
+        return True, "ok"
+
+    def stats(self):
+        return {"tau_C": self.tau_C,
+                "tau_U": None if self.tau_U is None else round(self.tau_U, 6)}

hibs_lnn/value_proposer.py

@@ -0,0 +1,180 @@
+"""value_proposer.py — 价值函数提议器 (从 LMT-twister V35.19 移植, 适配连续物理区间)。
+
+## 来源
+
+LMT-twister 家族已把这条线验证到生产级 (skill: lmt-twister-experiment):
+  V35.19 价值函数提议器 (用户理论): 简约性 + 自洽性 + 覆盖增量
+  V35.20 价值函数表示迁移最优 (0.0869 > 外部课程 0.0742)
+  V35.21 三 seed 确认 (0.0850±0.002), S5 内直接训练 scratch +2.05pp
+  V35.22 价值函数 = 稳定器 (方差缩 3 倍)
+  LM1   生产级: 提议器每步自主生成数据
+
+原式 (V35.19):
+    V(p) = λ_sim·sim(p) + λ_con·con(p) + λ_cov/(1+freq(p))
+    sim(p) = 1 - max_{q∈已学} struct_sim(p,q)       # 简约性: 不可归约度
+    con(p) = 1 - 矛盾度                             # 自洽性
+    cov(p) = 1/(1+freq(p))                          # 覆盖增量
+
+## 本移植
+
+lm1 的"结构 p"是离散排列; lm4/lm5 的"结构"是**连续的物理区间**,
+所以相似度换成描述子空间里的距离, 并新增一项**真实反馈** (V35 里由
+CausalProposer.feedback_value 承担)。
+
+    V(p) = λ_sim·sim(p) + λ_con·con(p) + λ_cov·cov(p) + λ_fb·fb(p)
+
+    sim(p)  = 1 - max_{q∈已学} exp(-‖z_p - z_q‖ / σ)   # 物理上离已学区间多远
+    con(p)  = 自洽性 = 该区间与已发现因果结构的吻合度  (由调用方注入)
+    cov(p)  = 1/(1+freq(p))                            # 训练越少越值得学
+    fb(p)   = 1 - acc(p)                               # 真实反馈: 越不准越值得学
+
+## 关键坑 (V35.19 实测, 必须遵守)
+
+1. **候选池必须远大于提议数**, 否则价值函数被抹平 (v1: 池 18 个被全覆盖 ->
+   提议顺序无关 -> λ 扫描零效果)。本实现默认要求 len(pool) >> k·轮数。
+2. **λ_cov 倒 U 型**, 平衡点 ≈ 1:1:1。默认 (1,1,1,1)。
+3. **覆盖项必须真的有频率差异**, 否则退化成随机 (v2 教训: 高频重复 ≠ 均匀覆盖)。
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+class RegimeProposer:
+    """按价值函数从候选区间池里采样"下一个学哪个物理区间"。
+
+    参数
+    ----
+    desc : (N, D) 每个候选区间的物理描述子 (如 [log_dens, logL, absmaglat]).
+           内部做 z-score, 保证各维等权。
+    groups : (N,) 每个候选区间映射到哪个**评估域** (用于汇总/报告, 不参与打分)。
+    lam : (λ_sim, λ_con, λ_cov, λ_fb)
+    sigma : 描述子空间里"多远算不可归约"的尺度 (z-score 单位, 默认 0.5)
+    tau : softmax 温度, 越小越贪婪
+    k : 每次提议几个
+    seed : 采样随机种子
+    """
+
+    def __init__(self, desc, groups=None, lam=(1.0, 1.0, 1.0, 1.0),
+                 sigma=None, tau=0.5, k=2, seed=0):
+        desc = np.asarray(desc, dtype=np.float64)
+        self.n = len(desc)
+        mu = desc.mean(0)
+        sd = desc.std(0)
+        sd[sd < 1e-9] = 1.0
+        self.z = (desc - mu) / sd
+        # ★ sigma 默认由数据决定, 不能用固定 0.5。
+        #   低维描述子 (1-3 维) 下候选间距离量级很小, 固定 sigma=0.5 会让
+        #   exp(-d/sigma) ≈ 0 对所有候选成立 -> sim(p) ≡ 1.0 -> 简约性项死亡
+        #   (实测 signature: value 与 value-nofb 提议序列逐位相同)。
+        #   取"最近邻距离的中位数"当尺度, 保证核在真实分布上有区分度。
+        if sigma is None:
+            d = np.linalg.norm(self.z[:, None, :] - self.z[None, :, :], axis=-1)
+            np.fill_diagonal(d, np.inf)
+            sigma = float(np.median(d.min(axis=1)))
+            sigma = max(sigma, 1e-3)
+        self.sigma = float(sigma)
+        self.groups = (np.asarray(groups) if groups is not None
+                       else np.zeros(self.n, dtype=int))
+        self.lam = tuple(float(x) for x in lam)
+        self.tau = float(tau)
+        self.k = int(k)
+        self.rng = np.random.default_rng(seed)
+        # 状态
+        self._con = None                                  # 自洽性分数 (可注入)
+        self.freq = np.zeros(self.n, dtype=np.float64)   # 被提议次数
+        self.learned = []                                 # 已学区间索引
+        self.acc = np.full(self.n, np.nan)                # 各区间的实测准确率
+        self.trace = []                                   # 每轮提议记录
+
+    # ---------------- 三项 + 反馈 ----------------
+    def sim(self, i):
+        """简约性: 1 - 与已学区间的最大相似度 (物理上离得越远越值得学)。"""
+        if not self.learned:
+            return 1.0
+        d = np.linalg.norm(self.z[self.learned] - self.z[i], axis=1)
+        return float(1.0 - np.exp(-d.min() / self.sigma))
+
+    def cov(self, i):
+        """覆盖增量: 越少被训练越值得学。"""
+        return 1.0 / (1.0 + self.freq[i])
+
+    def con(self, i):
+        """自洽性 (V35.19 三项之一) —— 由调用方 set_consistency() 注入。
+
+        **没注入时返回恒定 1.0, 该维对排序零贡献** ��— 这是本轮踩过的坑:
+        忘了注入 -> 自洽性项死亡 -> 价值函数退化成覆盖均匀化采样器。
+        诊断: stats() 里的 con_std; 若为 0 说明这一项是死的。
+        """
+        return float(self._con[i]) if self._con is not None else 1.0
+
+    def fb(self, i):
+        """真实反馈: 越不准越值得学 (持续学习那一环)。"""
+        a = self.acc[i]
+        if not np.isfinite(a):
+            return 1.0          # 没测过 = 最有价值
+        return float(1.0 - a)
+
+    def value(self, i):
+        ls, lc, lv, lf = self.lam
+        return (ls * self.sim(i) + lc * self.con(i)
+                + lv * self.cov(i) + lf * self.fb(i))
+
+    # ---------------- 外部注入 ----------------
+    def set_consistency(self, con):
+        """注入自洽性分数 (长度 N)。对 lm4: 每个区间与已发现因果边的吻合度。"""
+        self._con = np.asarray(con, dtype=np.float64)
+
+    def observe(self, idx, acc, learned=True):
+        """记录一轮的结果: 该区间的实测准确率 (+ 标记为已学)。"""
+        self.acc[idx] = float(acc)
+        if learned and idx not in self.learned:
+            self.learned.append(int(idx))
+
+    # ---------------- 提议 ----------------
+    def propose(self, k=None):
+        """按 V 的 softmax 采样 k 个不重复候选 (采样而非 argmax: 保留探索)。"""
+        k = k or self.k
+        v = np.array([self.value(i) for i in range(self.n)])
+        # 数值稳定 + 温度
+        v = v - v.max()
+        p = np.exp(v / max(1e-9, self.tau))
+        p = p / p.sum()
+        kk = min(k, self.n)
+        idx = self.rng.choice(self.n, size=kk, replace=False, p=p)
+        for i in idx:
+            self.freq[i] += 1
+        self.trace.append(list(map(int, idx)))
+        return list(map(int, idx))
+
+    def pick_random(self, k=None):
+        """随机对照臂。"""
+        k = k or self.k
+        idx = self.rng.choice(self.n, size=min(k, self.n), replace=False)
+        for i in idx:
+            self.freq[i] += 1
+        self.trace.append(list(map(int, idx)))
+        return list(map(int, idx))
+
+    # ---------------- 诊断 ----------------
+    def stats(self):
+        v = np.array([self.value(i) for i in range(self.n)])
+        # ★ 各项的**区分度**诊断: 标准差为 0 = 该项是死的 (对排序零贡献)
+        _sim = np.array([self.sim(i) for i in range(self.n)])
+        _con = np.array([self.con(i) for i in range(self.n)])
+        _cov = np.array([self.cov(i) for i in range(self.n)])
+        _fb = np.array([self.fb(i) for i in range(self.n)])
+        return {
+            "n_candidates": int(self.n),
+            "n_learned": len(self.learned),
+            "n_proposed_total": int(self.freq.sum()),
+            "freq_nonzero": int((self.freq > 0).sum()),
+            "value_mean": float(v.mean()),
+            "value_std": float(v.std()),
+            "value_cv": float(v.std() / max(1e-9, abs(v.mean()))),
+            "covered_frac": float((self.freq > 0).mean()),
+            "sigma": float(self.sigma),
+            # 各项区分度: 0 = 该项死了 (本轮踩过的坑)
+            "term_std": {"sim": float(_sim.std()), "con": float(_con.std()),
+                         "cov": float(_cov.std()), "fb": float(_fb.std())},
+        }

manifests/delta_compile_report.md

@@ -0,0 +1,21 @@
+# Delta Compile Report
+
+- generated_at: `2026-09-06T05:17:16+00:00`
+- stale_pages: `0`
+- new_raw_sources: `1`
+- drafts_written: `0`
+
+> This report suggests recompilation work. It does not auto-overwrite wiki content.
+
+## Stale Pages
+
+- none
+
+## New Raw Sources
+
+- `docs/wiki/log.md` -> suggested page `docs/wiki/log.md`
+  - 
+
+## Draft Files
+
+- none

manifests/knowledge_graph.json

@@ -0,0 +1,143 @@
+{
+  "schema_version": 2,
+  "wiki_root": "/Users/apple/Downloads/headless/docs/wiki",
+  "nodes": [
+    {
+      "id": "README.md",
+      "type": "meta",
+      "label": "README.md",
+      "tags": "",
+      "stage": "",
+      "audience": "",
+      "source_file": "docs/wiki/README.md"
+    },
+    {
+      "id": "SCHEMA.md",
+      "type": "meta",
+      "label": "SCHEMA.md",
+      "tags": "",
+      "stage": "",
+      "audience": "",
+      "source_file": "docs/wiki/SCHEMA.md"
+    },
+    {
+      "id": "causal_lm1_experiment.md",
+      "type": "meta",
+      "label": "LM1 因果持续学习对照实验",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/causal_lm1_experiment.md"
+    },
+    {
+      "id": "causal_stack.md",
+      "type": "meta",
+      "label": "causal 因果技术栈落地",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/causal_stack.md"
+    },
+    {
+      "id": "current-status.md",
+      "type": "meta",
+      "label": "current-status",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/current-status.md"
+    },
+    {
+      "id": "github-and-raw-strategy.md",
+      "type": "meta",
+      "label": "github-and-raw-strategy",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/github-and-raw-strategy.md"
+    },
+    {
+      "id": "index.md",
+      "type": "meta",
+      "label": "index.md",
+      "tags": "",
+      "stage": "",
+      "audience": "",
+      "source_file": "docs/wiki/index.md"
+    },
+    {
+      "id": "log.md",
+      "type": "meta",
+      "label": "log.md",
+      "tags": "",
+      "stage": "",
+      "audience": "",
+      "source_file": "docs/wiki/log.md"
+    },
+    {
+      "id": "project-overview.md",
+      "type": "meta",
+      "label": "project-overview",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/project-overview.md"
+    },
+    {
+      "id": "sources-and-data.md",
+      "type": "meta",
+      "label": "sources-and-data",
+      "tags": "",
+      "stage": "draft",
+      "audience": "public",
+      "source_file": "docs/wiki/sources-and-data.md"
+    }
+  ],
+  "edges": [
+    {
+      "from": "index.md",
+      "to": "log.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "causal_stack.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "causal_lm1_experiment.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "current-status.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "github-and-raw-strategy.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "project-overview.md",
+      "type": "references"
+    },
+    {
+      "from": "index.md",
+      "to": "sources-and-data.md",
+      "type": "references"
+    }
+  ],
+  "stats": {
+    "node_count": 10,
+    "edge_count": 7,
+    "node_types": {
+      "meta": 10
+    },
+    "edge_types": {
+      "references": 7
+    }
+  }
+}

manifests/raw_sources.csv

@@ -0,0 +1,2 @@
+source_id,company,vendor,kind,filename,raw_rel_path,status,compiled_into,filename,content_hash,size_bytes,ingested_at,compiled_at,last_validated_at,confidence,supersedes,lifecycle_stage,crystallized_into,owner,audience,stage,tags,notes,schema_version
+1,headless,,experiment-log,log.md,docs/wiki/log.md,new,,log.md,d8a4a23a1a848bb5,6572,2026-09-06,2026-09-06,high,,,元木,reader,draft,continuous-learning,Primary experiment log,2

manifests/raw_sources.meta.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": 2,
+  "columns": [
+    "source_id",
+    "company",
+    "vendor",
+    "kind",
+    "filename",
+    "raw_rel_path",
+    "status",
+    "compiled_into",
+    "filename",
+    "content_hash",
+    "size_bytes",
+    "ingested_at",
+    "compiled_at",
+    "last_validated_at",
+    "confidence",
+    "supersedes",
+    "lifecycle_stage",
+    "crystallized_into",
+    "owner",
+    "audience",
+    "stage",
+    "tags",
+    "notes",
+    "schema_version"
+  ],
+  "allowed_status": [
+    "new",
+    "compiled",
+    "archived"
+  ]
+}

manifests/stale_report.md

@@ -0,0 +1,40 @@
+# Stale Report
+
+- generated_at: `2026-09-06T05:10:45+00:00`
+- raw_root: `not configured`
+- fresh_pages: `0`
+- stale_pages: `0`
+- missing_hash: `6`
+- unresolved_sources: `0`
+- archived_refs: `0`
+- manifest_new: `1`
+- session_exempt: `0`
+
+## Fresh Pages
+
+- none
+
+## Pages Needing Recompile (stale)
+
+- none
+
+## Pages Missing source_hash
+
+- `docs/wiki/causal_lm1_experiment.md`
+- `docs/wiki/causal_stack.md`
+- `docs/wiki/current-status.md`
+- `docs/wiki/github-and-raw-strategy.md`
+- `docs/wiki/project-overview.md`
+- `docs/wiki/sources-and-data.md`
+
+## Pages With Unresolved source
+
+- none
+
+## Pages Pointing At Archived Sources
+
+- none
+
+## Raw Files Still Waiting For First Compile
+
+- `docs/wiki/log.md`

scripts/bootstrap_knowledge_system.py

@@ -0,0 +1,195 @@
+"""Bootstrap a compile-first knowledge system into a target repo.
+
+The actual file contents live as real files under
+`skills/knowledge-system-bootstrap/templates/`. This script copies them
+into the target with sentinel-string substitution. That keeps every
+generated script lintable, testable, and reviewable on its own.
+
+Substitution sentinels (plain string.replace, no Template machinery so
+templates can contain literal `$`):
+  __PROJECT_NAME__    — human-readable project name passed on the CLI
+  __RAW_ROOT_NAME__   — folder name for the local raw root
+  __TODAY__           — today's date in YYYY-MM-DD
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+from datetime import date, datetime
+from pathlib import Path
+
+__version__ = "2.0.0"  # bumped for v2 scripts (wiki_lint, supersede_check, crystallize, hybrid_search, graph_export, intake_filter) merged under SKILL_ROOT/scripts/
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+TEMPLATES = SKILL_ROOT / "templates"
+
+
+# (template-relative path, target-relative path)
+TEMPLATE_TO_TARGET: list[tuple[str, str]] = [
+    ("configs/AGENTS.md", "AGENTS.md"),
+    ("configs/CLAUDE.md", "CLAUDE.md"),
+    ("configs/.cursorrules", ".cursorrules"),
+    ("configs/.windsurfrules", ".windsurfrules"),
+    ("configs/.gitignore", ".gitignore"),
+    ("wiki/README.md", "docs/wiki/README.md"),
+    ("wiki/SCHEMA.md", "docs/wiki/SCHEMA.md"),
+    ("wiki/index.md", "docs/wiki/index.md"),
+    ("wiki/log.md", "docs/wiki/log.md"),
+    ("wiki/project-overview.md", "docs/wiki/project-overview.md"),
+    ("wiki/current-status.md", "docs/wiki/current-status.md"),
+    ("wiki/sources-and-data.md", "docs/wiki/sources-and-data.md"),
+    ("wiki/github-and-raw-strategy.md", "docs/wiki/github-and-raw-strategy.md"),
+    ("wiki/runtime-profile.md", "docs/wiki/runtime-profile.md"),
+    ("manifests/README.md", "manifests/README.md"),
+    ("manifests/raw_sources.csv", "manifests/raw_sources.csv"),
+    ("manifests/raw_sources.meta.json", "manifests/raw_sources.meta.json"),
+    ("scripts/wiki_check.py", "scripts/wiki_check.py"),
+    ("scripts/raw_manifest_check.py", "scripts/raw_manifest_check.py"),
+    ("scripts/ingest_raw.py", "scripts/ingest_raw.py"),
+    ("scripts/untracked_raw_check.py", "scripts/untracked_raw_check.py"),
+    ("scripts/provenance_check.py", "scripts/provenance_check.py"),
+    ("scripts/stale_report.py", "scripts/stale_report.py"),
+    ("scripts/delta_compile.py", "scripts/delta_compile.py"),
+    ("scripts/version_check.py", "scripts/version_check.py"),
+    ("scripts/wiki_size_report.py", "scripts/wiki_size_report.py"),
+    ("scripts/init_raw_root.py", "scripts/init_raw_root.py"),
+    ("scripts/export_memory_repo.py", "scripts/export_memory_repo.py"),
+    ("scripts/upgrade.sh", "scripts/upgrade.sh"),
+    # v2.0.0 — new scripts merged under scripts/, no longer in templates/scripts/
+    ("scripts/wiki_lint.py", "scripts/wiki_lint.py"),
+    ("scripts/supersede_check.py", "scripts/supersede_check.py"),
+    ("scripts/crystallize.py", "scripts/crystallize.py"),
+    ("scripts/hybrid_search.py", "scripts/hybrid_search.py"),
+    ("scripts/graph_export.py", "scripts/graph_export.py"),
+    ("scripts/intake_filter.py", "scripts/intake_filter.py"),
+    ("claude-commands/wiki-check.md", ".claude/commands/wiki-check.md"),
+    ("claude-commands/wiki-upgrade.md", ".claude/commands/wiki-upgrade.md"),
+    ("claude-commands/wiki-status.md", ".claude/commands/wiki-status.md"),
+    ("github/workflows/wiki-lint.yml", ".github/workflows/wiki-lint.yml"),
+]
+
+
+def slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "_", value)
+    return value.strip("_") or "project"
+
+
+def render(body: str, vars: dict[str, str]) -> str:
+    out = body
+    for sentinel, value in vars.items():
+        out = out.replace(sentinel, value)
+    unresolved = re.findall(r"__[A-Z][A-Z0-9_]*__", out)
+    expected = {"__main__", "__init__", "__name__", "__file__"}
+    real = [s for s in unresolved if s not in expected]
+    if real:
+        raise RuntimeError(f"unresolved sentinels: {set(real)}")
+    return out
+
+
+def write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def backup(path: Path) -> Path:
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    dest = path.with_suffix(path.suffix + f".bak.{stamp}")
+    shutil.copy2(path, dest)
+    return dest
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Bootstrap a compile-first knowledge system into another repo.")
+    parser.add_argument("target_dir", help="Target repository root")
+    parser.add_argument("project_name", help="Human-readable project name")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files (a .bak.<timestamp> copy is kept unless --no-backup)")
+    parser.add_argument("--no-backup", action="store_true", help="When overwriting, skip the .bak file (only effective with --force)")
+    parser.add_argument("--dry-run", action="store_true", help="Show what would happen without writing anything")
+    parser.add_argument("--raw-root-name", help="Folder name for the local raw root")
+    args = parser.parse_args()
+
+    target = Path(args.target_dir).expanduser().resolve()
+    project_name = args.project_name.strip()
+    slug = slugify(project_name)
+    raw_root_name = args.raw_root_name or f"{slug}_raw"
+    today = date.today().isoformat()
+
+    vars = {
+        "__PROJECT_NAME__": project_name,
+        "__RAW_ROOT_NAME__": raw_root_name,
+        "__TODAY__": today,
+    }
+
+    created: list[Path] = []
+    overwritten: list[tuple[Path, Path | None]] = []
+    skipped: list[Path] = []
+    unchanged: list[Path] = []
+
+    for tmpl_rel, target_rel in TEMPLATE_TO_TARGET:
+        # v2.0.0: scripts/ under SKILL_ROOT/scripts/ (not templates/scripts/)
+        if tmpl_rel.startswith("scripts/"):
+            src = SKILL_ROOT / tmpl_rel
+        else:
+            src = TEMPLATES / tmpl_rel
+        if not src.exists():
+            print(f"WARNING: template missing: {tmpl_rel}")
+            continue
+        body = src.read_text(encoding="utf-8")
+        try:
+            content = render(body, vars)
+        except RuntimeError as exc:
+            raise SystemExit(f"template {tmpl_rel}: {exc}")
+
+        dest = target / target_rel
+        if not dest.exists():
+            if not args.dry_run:
+                write(dest, content)
+            created.append(dest)
+        elif dest.read_text(encoding="utf-8") == content:
+            unchanged.append(dest)
+        elif args.force:
+            bak_path: Path | None = None
+            if not args.dry_run:
+                if not args.no_backup:
+                    bak_path = backup(dest)
+                write(dest, content)
+            overwritten.append((dest, bak_path))
+        else:
+            skipped.append(dest)
+
+    prefix = "[DRY RUN] " if args.dry_run else ""
+    print(f"{prefix}Bootstrapped knowledge system for: {project_name}")
+    print(f"Target repo: {target}")
+    print(f"Default raw root name: {raw_root_name}")
+
+    if created:
+        print(f"\nCreated ({len(created)}):")
+        for p in created:
+            print(f"  + {p.relative_to(target)}")
+    if overwritten:
+        print(f"\nOverwritten ({len(overwritten)}):")
+        for p, bak in overwritten:
+            suffix = f"  (backup: {bak.name})" if bak else "  (no backup)"
+            print(f"  ! {p.relative_to(target)}{suffix}")
+    if unchanged:
+        print(f"\nUnchanged ({len(unchanged)})")
+    if skipped:
+        print(f"\nSkipped — already exists, content differs ({len(skipped)}):")
+        print("Use --force to overwrite.")
+        for p in skipped:
+            print(f"  ~ {p.relative_to(target)}")
+
+    if not args.dry_run and (created or overwritten):
+        print("\nNext steps:")
+        print(f"1. cd {target}")
+        print("2. python3 scripts/init_raw_root.py")
+        print("3. python3 scripts/wiki_check.py")
+        print("4. python3 scripts/raw_manifest_check.py")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())