@furongjun1999/dsh-memory 0.9.23 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.en.md +450 -404
  2. package/CHANGELOG.md +67 -0
  3. package/README.en.md +244 -240
  4. package/README.md +272 -262
  5. package/codebuddy/CODEBUDDY.md +1 -1
  6. package/docs/discipline/templates/full.md.tmpl +1 -1
  7. package/docs/discipline/templates/rules.mdc.tmpl +1 -1
  8. package/docs/en/mdcg/world-model-endpoint.md +1 -1
  9. package/docs/mdcg/cogmap_ops.md +16 -15
  10. package/lib/client.js +29 -3
  11. package/lib/hooks.d.ts +12 -0
  12. package/lib/hooks.js +43 -1
  13. package/md_cg/bucketindex.py +231 -0
  14. package/md_cg/bucketscope.py +339 -0
  15. package/md_cg/config_registry_bulk.py +19 -10
  16. package/md_cg/config_validate.py +14 -2
  17. package/md_cg/detrerank.py +137 -0
  18. package/md_cg/fsutil.py +135 -0
  19. package/md_cg/govern/__init__.py +23 -0
  20. package/md_cg/iface/__init__.py +46 -0
  21. package/md_cg/iface/_verify.py +609 -0
  22. package/md_cg/iface/contracts.py +337 -0
  23. package/md_cg/judgment_manifest.py +14 -0
  24. package/md_cg/kernel/__init__.py +27 -0
  25. package/md_cg/mcp_server.py +5991 -5761
  26. package/md_cg/mdcg.py +474 -16
  27. package/md_cg/mdcos.py +228 -11
  28. package/md_cg/metacognition.py +66 -13
  29. package/md_cg/mutate_extract_shipped.py +126 -0
  30. package/md_cg/mutate_ledger_e2e.py +100 -0
  31. package/md_cg/op_table.py +8 -0
  32. package/md_cg/probe_c_ledger_integrity.py +258 -0
  33. package/md_cg/probe_d_retirement_discipline.py +263 -0
  34. package/md_cg/review_cli.py +6 -1
  35. package/md_cg/run_tests.py +30 -1
  36. package/md_cg/scopeselect.py +214 -0
  37. package/md_cg/scrub.py +66 -9
  38. package/md_cg/state_extract.py +149 -0
  39. package/md_cg/state_slots.py +58 -10
  40. package/md_cg/structboost.py +179 -0
  41. package/md_cg/test_alternatives_historical.py +162 -0
  42. package/md_cg/test_b2_sensitivity_landing.py +226 -223
  43. package/md_cg/test_b3_merge_keeps_content.py +608 -583
  44. package/md_cg/test_bucket_cards.py +85 -0
  45. package/md_cg/test_bucket_day_order.py +74 -0
  46. package/md_cg/test_bucket_quota.py +79 -0
  47. package/md_cg/test_bucket_recency_guards.py +75 -0
  48. package/md_cg/test_bucket_three_causes.py +83 -0
  49. package/md_cg/test_bucketindex.py +130 -0
  50. package/md_cg/test_bucketscope_early.py +71 -0
  51. package/md_cg/test_cond_term_fold_gate.py +1210 -0
  52. package/md_cg/test_cond_term_neg_scope.py +147 -0
  53. package/md_cg/test_detrerank.py +157 -0
  54. package/md_cg/test_gate_four_kpi.py +136 -0
  55. package/md_cg/test_generation_guard.py +14 -2
  56. package/md_cg/test_issue192_move_layer_indices_guard.py +48 -0
  57. package/md_cg/test_issue39_utf8_stdio.py +572 -572
  58. package/md_cg/test_issue413_preimage_failclosed.py +147 -9
  59. package/md_cg/test_issue768_overwrite_time_window_anchor.py +135 -0
  60. package/md_cg/test_issue789_log_plaintext_probe.py +100 -0
  61. package/md_cg/test_issue790_verb_negation.py +77 -0
  62. package/md_cg/test_issue810_root_guard.py +71 -0
  63. package/md_cg/test_issue812_info_index_stale.py +78 -0
  64. package/md_cg/test_issue827_weaken_dedup.py +361 -0
  65. package/md_cg/test_issue829_calibration_positive_gate.py +473 -0
  66. package/md_cg/test_kernel_iface_contracts.py +18 -0
  67. package/md_cg/test_md_cg_no_hive_dep.py +238 -17
  68. package/md_cg/test_probe_cd_shipped.py +385 -0
  69. package/md_cg/test_recent_tail.py +93 -0
  70. package/md_cg/test_run_tests_entry_gates.py +110 -0
  71. package/md_cg/test_scopeselect.py +70 -0
  72. package/md_cg/test_scopeselect_clock.py +70 -0
  73. package/md_cg/test_session_attribution_consistency.py +835 -813
  74. package/md_cg/test_state_extract_shipped.py +162 -0
  75. package/md_cg/test_state_ledger_chain.py +207 -0
  76. package/md_cg/test_state_ledger_e2e.py +145 -0
  77. package/md_cg/test_structboost.py +102 -0
  78. package/md_cg/test_timeboost.py +83 -0
  79. package/md_cg/test_timeboost_relativedate.py +71 -0
  80. package/md_cg/test_topicagg.py +129 -0
  81. package/md_cg/timeboost.py +223 -0
  82. package/md_cg/topicagg.py +142 -0
  83. package/md_cg/whitebox_kb/wisdom/code_compose.py +33 -5
  84. package/md_cg/whitebox_kb/wisdom/compose_engine.py +5 -1
  85. package/md_cg/whitebox_kb/wisdom/role_compose.py +271 -268
  86. package/package.json +137 -137
  87. package/src/hooks.ts +43 -1
  88. package/ui/minimal/payload/build-ui.mjs +41 -2
  89. package/ui/minimal/payload/lib/client.js +29 -3
  90. package/ui/minimal/payload/web/app.js +3 -1
  91. package/ui/minimal/payload/web/client.js +30 -3
  92. package/web/app.js +3 -1
  93. package/web/client.js +30 -3
  94. package/zcode/AGENTS.md +1 -1
package/md_cg/mdcos.py CHANGED
@@ -846,8 +846,12 @@ class MdCGOS(MdCG):
846
846
  TRASH = "trash"
847
847
 
848
848
  # 生效条件:传入 root 时以 super().__init__(root, autoflush=autoflush) 初始化父类,把 actor 存入 self.actor,并按 root(及类常量 AUDIT_ARCHIVE/HIPPOCAMPUS/TRASH)拼出 audit_log/audit_archive/hippocampus/inbox_log/decisions_log/trash_dir 等路径,同时 makedirs(hippocampus/trash_dir, exist_ok=True);读缓存装配走 readcache.install_default(#370:自动装配的唯一入口,基类已装则为幂等空操作,MDCG_READ_CACHE=0 时不装配)。
849
- def __init__(self, root: str, autoflush: int = 64, actor: str = "system"):
850
- super().__init__(root, autoflush=autoflush)
849
+ def __init__(self, root: str, autoflush: int = 64, actor: str = "system",
850
+ async_flush=None):
851
+ # async_flush 必须**显式转发**:本层用 **kw 之外的位置接参会让父类的
852
+ # 同名握手断链(实测 TypeError: MdCGOS.__init__() got an unexpected
853
+ # keyword argument 'async_flush')。None = 随 env(含本层自有缺省)。
854
+ super().__init__(root, autoflush=autoflush, async_flush=async_flush)
851
855
  self.actor = actor
852
856
  self.audit_log = os.path.join(self.root, "_audit.jsonl")
853
857
  self.audit_archive = os.path.join(self.root, self.AUDIT_ARCHIVE)
@@ -1155,6 +1159,16 @@ class MdCGOS(MdCG):
1155
1159
  continue
1156
1160
  _ov = _ofm.get(_ik)
1157
1161
  if _ov is not None:
1162
+ # #768:`condition_space.time_window` 是「**这次观测**发生在什么时候」,
1163
+ # 不是节点的静态属性——#550 的「未传字段继承旧值」把它一起继承过来后
1164
+ # 观测窗就被冻结在**首写时刻**(覆写旧节点 ⇒ 窗口落在过去),而
1165
+ # mdcg.add 的默认窗口构造因为「cs 已带 time_window」整段跳过、
1166
+ # 再也不刷新。故继承 cs 时剔除该键,让写面按本次写入重新定锚
1167
+ # (显式回填 created_at 仍锚在给出的时刻,见 mdcg.add)。
1168
+ if _ik == "condition_space" and isinstance(_ov, dict):
1169
+ _ov = {k: v for k, v in _ov.items() if k != "time_window"}
1170
+ if not _ov:
1171
+ continue
1158
1172
  kw[_ik] = _ov
1159
1173
  nid = super().add(node_id, content, layer=layer, **kw)
1160
1174
  e = self.index["nodes"].get(nid)
@@ -2168,7 +2182,7 @@ class MdCGOS(MdCG):
2168
2182
  early_stop_threshold=None,
2169
2183
  start_time=None, end_time=None, start_operator=None,
2170
2184
  end_operator=None, time_axis=None, view=None,
2171
- strict_conditions: bool = True):
2185
+ strict_conditions: bool = True, now=None):
2172
2186
  """并行多路召回 + RRF 融合。返回 (results, meta)。
2173
2187
 
2174
2188
  validity:**只排除「已过期」(expired),不排除「未生效」(not_yet)**。
@@ -2492,6 +2506,18 @@ class MdCGOS(MdCG):
2492
2506
  # 温路径早停判据(2026-09-19 热温冷分层):
2493
2507
  # top-1 RRF 分 >= threshold 且 top-k 全部来自 >=2 路共识 → 提前返回
2494
2508
  # 不改 RRF 核心算法,只在融合后判断
2509
+ # 结构重排需要**先超取再截断**:实测(476 题)在 k=10 的池子里重排,gold@3 不动;
2510
+ # 在 2×k 池子里重排再截到 k,gold@3 71.9%→85.5%。池子宽窄决定这条信号有没有用。
2511
+ _struct_on = (int(os.environ.get("MDCG_STRUCT_BOOST", "0")) > 0)
2512
+ # 注意:**不要**复用 `_time_on`——那是上面「时间算子启用」的既有变量,
2513
+ # 覆盖它会让「时间算子查询绕开热缓存」失效(实测:默认查询被污染成 11 条)。
2514
+ _timeboost_on = (int(os.environ.get("MDCG_TIME_BOOST", "0")) > 0)
2515
+ # 时间重排的时钟:**复用**本函数内既有的唯一 time 调用点(#111 契约:打分层时钟恰 1 处),
2516
+ # 新增 time.time() 会直接让契约守卫转红(实测:新增后「时钟调用 2 次」)。
2517
+ # 故这里只派生,不取时钟:`_validity_clock` 未启用时由 _candidates 侧时钟兜底(见下)。
2518
+ # `now` 由调用方显式给(缺省回落既有唯一时钟点);None ⇒ 时间重排不启用(不猜「今天」)。
2519
+ _rerank_now = now if now is not None else _validity_clock
2520
+ _k_fetch = min(k * 2, 200) if ((_struct_on or _timeboost_on) and k) else k
2495
2521
  early_stopped = False
2496
2522
  if early_stop_threshold is not None and len(fused_all) >= k:
2497
2523
  top1_score = fused_all[0][1]
@@ -2509,7 +2535,7 @@ class MdCGOS(MdCG):
2509
2535
  filtered = 0
2510
2536
  if early_stopped:
2511
2537
  # 早停:直接取 top-k,不做 judge_ranking
2512
- fused = fused_all[:k]
2538
+ fused = fused_all[:_k_fetch]
2513
2539
  judge = False # 早停时跳过资格判定
2514
2540
  judge_ranking = False
2515
2541
  elif judge and judge_ranking:
@@ -2521,7 +2547,7 @@ class MdCGOS(MdCG):
2521
2547
  # qualified result (including the deterministic id tie).
2522
2548
  # A fixed oversampling window can run out of safe candidates.
2523
2549
  upper = max(fs, fs * 0.5)
2524
- if (k > 0 and len(kept) == k
2550
+ if (_k_fetch > 0 and len(kept) == _k_fetch
2525
2551
  and (-upper, nid) >= (-kept[-1][1], kept[-1][0])):
2526
2552
  break
2527
2553
  node, s = node_by_id[nid]
@@ -2534,14 +2560,14 @@ class MdCGOS(MdCG):
2534
2560
  continue
2535
2561
  kept.append((nid, fs if st == STATE_ACCEPT else fs * 0.5))
2536
2562
  kept.sort(key=lambda x: (-x[1], x[0]))
2537
- if k > 0:
2538
- kept = kept[:k]
2563
+ if _k_fetch > 0:
2564
+ kept = kept[:_k_fetch]
2539
2565
  kept.sort(key=lambda x: (-x[1], x[0]))
2540
2566
  if _ta_tier:
2541
2567
  kept.sort(key=lambda x: _ta_tier.get(x[0], 2)) # 稳定排序:交集者前置
2542
- fused = kept[:k]
2568
+ fused = kept[:_k_fetch]
2543
2569
  else:
2544
- fused = fused_all[:k]
2570
+ fused = fused_all[:_k_fetch]
2545
2571
 
2546
2572
  results = []
2547
2573
  # P2-2(§5.2):默认召回路径上的**拒绝域双语义**——与 `MdCG._emit` 同款
@@ -2679,6 +2705,83 @@ class MdCGOS(MdCG):
2679
2705
  view=view, extra=_cache_extra, clock_window=_query_window)
2680
2706
  if _rrf_dropped:
2681
2707
  stat["min_score"] = _rrf_min
2708
+ # ===== 结构信号重排(章节路由 + 元素覆盖):bench 读数驱动,缺省关 =====
2709
+ # 读数(六元素判断题 476,gold=evidence 行号):gold@1 49.6→52.5 / @3 71.9→85.7 / @10 92.0→96.2。
2710
+ # 只在**已召回候选集内**重排(不改候选集、不过滤)⇒ 无召回损失风险;
2711
+ # 与 recent_tail 的顺序无关(tail 是 0 分补尾,重排在补尾之前更干净)。
2712
+ _struct_boosted = False
2713
+ try:
2714
+ if (int(os.environ.get("MDCG_STRUCT_BOOST", "0")) > 0
2715
+ and results and q):
2716
+ from . import structboost as _sb # noqa: PLC0415
2717
+ results = _sb.rerank(results, q)
2718
+ _struct_boosted = True
2719
+ except Exception: # noqa: BLE001 —— 重排失败回退原序,绝不拖崩检索
2720
+ _struct_boosted = False
2721
+ # ===== 时间桶重排(主库「章节=写入日期」):缺省关,超取路径与 struct 共用 =====
2722
+ # 读数(主库 k=20 池):同日期在 top-5 的占比 10% → 37.5%;池内含该日期时有候选的日期到 100%。
2723
+ # 边界(实测):候选里**没有**那天的节点时重排无效——那需要「按日期二次召回」,
2724
+ # 当前实现(timeboost.scoped_recall)在主库实测 2–17 秒且只有 0–4/6 命中,**未接线**。
2725
+ _time_boosted = False
2726
+ try:
2727
+ if _timeboost_on and results and q and _rerank_now:
2728
+ from . import timeboost as _tb # noqa: PLC0415
2729
+ results = _tb.rerank(results, q, _rerank_now, k=k)
2730
+ _time_boosted = True
2731
+ except Exception: # noqa: BLE001
2732
+ _time_boosted = False
2733
+ if (_struct_boosted or _time_boosted) and k:
2734
+ results = results[:k] # 超取 → 重排 → 截回 k(对外语义不变)
2735
+ # issue #814 后续 / Ornn8 测评建议②(读取策略立项单 A 之外的最小项):
2736
+ # **cutoff 邻近保障**——检索完成后,把「最近 N 条用户轮次」中与 query
2737
+ # 有词法交集、且尚未出现在结果里的事件,按 0 分追加到结果**尾部**。
2738
+ # 动机(测评 turn16/75/25 漏检):相关但「不相似」的最近事实会被多路排序挤掉;
2739
+ # 它们是用户刚刚说过的话,即使 RRF 排不进 k,也必须可见。
2740
+ # 设计约束:**不进热路径缓存**(每轮 recent 不同,缓存键无法表达);
2741
+ # **不参与打分**(score=0.0,打乱正排等于换算法);meta 记 recent_tail 计数。
2742
+ _recent_tail_n = 0
2743
+ try:
2744
+ _rt_n = int(os.environ.get("MDCG_RECENT_TAIL", "6"))
2745
+ if _rt_n > 0 and results:
2746
+ _have_ids = {r[0].get("id") for r in results}
2747
+ _q_terms = [t.lower() for t in re.split(r"[\s,,、;;]+", q or "")
2748
+ if len(t) >= 2]
2749
+ _tail = []
2750
+ _have_texts = [str(r[0].get("content") or "") for r in results]
2751
+ for _ev in self.recent_events(limit=max(20, _rt_n * 4),
2752
+ roles=["user"]):
2753
+ if len(_tail) >= _rt_n:
2754
+ break
2755
+ _txt = str(_ev.get("text") or "")
2756
+ if not _txt or _ev.get("id") in _have_ids:
2757
+ continue
2758
+ # 判重边界(B10 修订裁定):补尾**只按事件 id 查重**,不做内容级判重。
2759
+ # 理由:「(轮20)灯箱已经报价」与正排命中的「灯箱已报价」是同一事实的
2760
+ # 不同措辞,词面判重(子串/分词覆盖)都会**漏判或误判**——语义判重
2761
+ # 属于跨层职责(将来可由 memory 层的 dup 信号提供),不进检索面。
2762
+ # 代价接受:同一事实可能正排一次 + 补尾一次(≤2 次出现,有 recent_event
2763
+ # 标记可识别)。宁可重复可见,不可静默丢失——与 #802/#811 的「不过滤
2764
+ # 就显式」是同一条哲学。
2765
+ _low = _txt.lower()
2766
+ if _q_terms and not any(t in _low for t in _q_terms):
2767
+ continue
2768
+ _tail.append({
2769
+ "id": _ev.get("id"),
2770
+ "frontmatter": {"tags": _ev.get("tags") or [],
2771
+ "recent_event": True},
2772
+ "content": _txt,
2773
+ "path": "_recent.jsonl#" + str(_ev.get("id")),
2774
+ "recent_event": True,
2775
+ })
2776
+ for _node in _tail:
2777
+ # issue #111 契约:打分层内 "state" 键字面量恰 1 处(取值=judge 结果)——
2778
+ # recent_tail 不自造 state(由 judge 面给),只给 reason。
2779
+ results.append((_node, 0.0,
2780
+ {"reason": "recent_tail"},
2781
+ []))
2782
+ _recent_tail_n += 1
2783
+ except Exception: # noqa: BLE001 —— 保障面不拖崩主检索
2784
+ _recent_tail_n = 0
2682
2785
  # issue #672:把生效的时效口径如实透出——调用方看名字容易以为「只给有效的」,
2683
2786
  # 读 meta 一眼可辨(只排过期 / 未启用)。
2684
2787
  _validity_meta = ({"validity_scope": "expired_only"} if validity
@@ -2688,6 +2791,9 @@ class MdCGOS(MdCG):
2688
2791
  if _rrf_min > 0 else {}),
2689
2792
  **(_rrf_note or {}),
2690
2793
  "paths": per_path, "fused": len(results),
2794
+ "recent_tail": _recent_tail_n,
2795
+ "struct_boost": _struct_boosted,
2796
+ "time_boost": _time_boosted,
2691
2797
  "judge_ranking": bool(judge and judge_ranking),
2692
2798
  "judge_filtered": filtered,
2693
2799
  "early_stopped": early_stopped,
@@ -2702,6 +2808,22 @@ class MdCGOS(MdCG):
2702
2808
  # ================= 7. budget-driven pack =================
2703
2809
 
2704
2810
  # 生效条件:query(配合 use_rrf 取 items)逐条按 budget_tokens 与 max_item_tokens 装包:若 used+t > budget_tokens,则 max_item_tokens 为真且 room=budget_tokens-used 不小于 min_excerpt(max_item_tokens 为真时取 max(1, min(50, max_item_tokens // 5)),否则为 0)时按 keep=min(max_item_tokens, room) 摘录,摘录后 est_tokens<=0 则该条以 excerpt_empty 进 skipped 并 continue;否则以 oversize_or_over_budget 进 skipped 并 continue;未超预算则计入 used 并 append,include_recent 为真时再按 left=budget_tokens-used 追加 recent_limit 条近期事件(逐条 est_tokens 不超过 left 才计入),最终返回含 pack/tokens_used/budget/skipped/recent/meta 的 dict;validity 真值时向候选层透传时效过滤(只排已过期)。
2811
+ def _topic_aggregates(self, pack, query, min_members: int = 2,
2812
+ max_groups: int = 5) -> list:
2813
+ """跨轮状态聚合(读取策略 A 项):把同话题的命中条目排成状态时间线。
2814
+
2815
+ 动机(Ornn8 终局报告):答案状态常**散在多轮**里(轮9 报价 + 轮20 未安排制作),
2816
+ search 只按单轮相关性交付,调用方拼不出完整状态。本方法**不改排序**,
2817
+ 只在装包后给一个「同话题 → 时间线」的聚合视图。
2818
+
2819
+ 聚合键:优先用 tags 与 query 的亲和(`_tag_affinity`,与 entity 路同源),
2820
+ 无命中的条目归到 `__untagged__` 组(不输出,避免噪声)。
2821
+ `state` 只读**既有字段**(qual 结果 / verification 状态),不自造——
2822
+ 遵守 issue #111「打分层不自造 state」的同一条纪律。
2823
+ """
2824
+ from .topicagg import aggregate as _agg # noqa: PLC0415 —— 聚合实现单点
2825
+ return _agg(pack, query, min_members=min_members, max_groups=max_groups)
2826
+
2705
2827
  def recall(self, query: str, budget_tokens: int = DEFAULT_BUDGET, k: int = 20,
2706
2828
  layer: str = None, context=None, roles=None,
2707
2829
  include_work: bool = False, judge: bool = True, use_rrf: bool = True,
@@ -2711,7 +2833,7 @@ class MdCGOS(MdCG):
2711
2833
  validity=None, max_item_tokens: int = DEFAULT_MAX_ITEM_TOKENS,
2712
2834
  start_time=None, end_time=None, start_operator=None,
2713
2835
  end_operator=None, time_axis=None, view=None,
2714
- excerpt_strategy: str = "prefix"):
2836
+ excerpt_strategy: str = "prefix", now=None):
2715
2837
  """按 token 预算装包:装到预算花完为止。
2716
2838
 
2717
2839
  装包策略(2026-09-14 调整):
@@ -2853,8 +2975,103 @@ class MdCGOS(MdCG):
2853
2975
  recent.append({"role": ev.get("role"), "t": ev.get("t"),
2854
2976
  "text": ev.get("text"), "tokens": t,
2855
2977
  "tags": ev.get("tags") or []})
2978
+ # ===== 桶作用域召回(日期 + 会话是默认坐标;会话优先,日桶按日期倒排)=====
2979
+ # 使用者口径(2026-11-09):这两类是**默认开启**的通用设置,不是可选优化;
2980
+ # 「条件才是筛选方式」,故桶召回只按查询词面筛选 + 时间降序,**不改正排名次**(score=0)。
2981
+ # 关闭:MDCG_BUCKET_SCOPE=0。预算从同一包预算里扣(诚实口径:附了就是占了)。
2982
+ _bucket_scope_n = 0
2983
+ try:
2984
+ if (os.environ.get("MDCG_BUCKET_SCOPE", "1") != "0"
2985
+ and pack is not None):
2986
+ from . import bucketscope as _bs # noqa: PLC0415
2987
+ # 【#843】validity 必须透传:桶补召回在候选检索**之后**追加,
2988
+ # 不传就会把调用方显式排除的过期记忆重新装回 pack(issue #843 复现)。
2989
+ # 【外测 2026-11-11 卡点 2】时钟必须从**最外层 API** 透传:
2990
+ # 早先这里只认内部 _rerank_clock / time.time(),宿主或外部复测走 recall 时
2991
+ # 逻辑时间被真实时钟覆盖(resolved_dates 返回真实今天)。与 #111 同纪律。
2992
+ _scope_now = (now if now is not None else
2993
+ (_rerank_clock if '_rerank_clock' in dir() else time.time()))
2994
+ _extra = _bs.scope_recall(self, query, session, _scope_now,
2995
+ validity=bool(validity))
2996
+ _have = {e.get("id") for e in pack}
2997
+ for _node, _score, _qual, _prov in _extra:
2998
+ if _node.get("id") in _have:
2999
+ continue
3000
+ _txt = str(_node.get("content") or "")
3001
+ _t = est_tokens(_txt)
3002
+ if used + _t > budget_tokens:
3003
+ continue
3004
+ fm = _node.get("frontmatter") or {}
3005
+ # 【外测 v2.1】metadata 必须带上 resolved_dates:早先只复制 state/reason/bucket,
3006
+ # 调用方在 pack 里取不到解析出的绝对日期,第 3 条建议等于没生效。
3007
+ _bm = {"state": (_qual or {}).get("state"),
3008
+ "reason": "bucket_scope",
3009
+ "bucket": (_qual or {}).get("bucket")}
3010
+ if (_qual or {}).get("resolved_dates"):
3011
+ _bm["resolved_dates"] = _qual["resolved_dates"]
3012
+ if (_qual or {}).get("fallback"):
3013
+ _bm["fallback"] = _qual["fallback"]
3014
+ pack.append({"id": _node.get("id"), "score": 0.0,
3015
+ "state": (_qual or {}).get("state"),
3016
+ "tokens": _t, "content": _txt,
3017
+ "frontmatter": fm, "provenance": _prov or [],
3018
+ "metadata": _bm})
3019
+ used += _t
3020
+ _bucket_scope_n += 1
3021
+ if _bucket_scope_n >= _bs.DEFAULT_CAP:
3022
+ break
3023
+ except Exception: # noqa: BLE001 —— 桶召回失败不拖崩装包
3024
+ _bucket_scope_n = 0
3025
+ # ===== 检索裁定:结论必须由确定性规则裁决(structural: mem_ruling_vector_ref_deterministic)=====
3026
+ # 向量/语义相似度只提供候选参考;**最终名次由词法·时间·空间·交互四类可数信号重排**,
3027
+ # 且必须确定性可回放。纯后处理:不改 pack 内容、不改 fused 分数,只调整交付顺序。
3028
+ # 缺省关(MDCG_DET_RERANK=0);开启后 meta 透出 det_reranked 与时钟来源。
3029
+ det_reranked = False
3030
+ _rerank_clock = (meta.get('clock') if isinstance(meta, dict) else None) or time.time()
3031
+ _clock_source = ('search_meta' if (isinstance(meta, dict) and meta.get('clock'))
3032
+ else 'recall_local')
3033
+ try:
3034
+ if int(os.environ.get('MDCG_DET_RERANK', '0')) > 0 and len(pack) >= 2:
3035
+ from . import detrerank as _dr # noqa: PLC0415
3036
+ _items = [({'id': e.get('id'),
3037
+ 'content': e.get('content'),
3038
+ 'frontmatter': e.get('frontmatter')},
3039
+ float(e.get('score') or 0.0), {}, []) for e in pack]
3040
+ # 模式可配(bench 用):tiebreak(缺省,零风险)/ window(有界上浮)/ replace(v1,已被读数否决)
3041
+ _mode = (os.environ.get('MDCG_DET_MODE') or 'tiebreak').strip().lower()
3042
+ _ranked = _dr.rerank_v2(_items, query, _rerank_clock,
3043
+ mode=_mode, session=session)
3044
+ _order = {it[0][0]['id']: i for i, it in enumerate(_ranked)}
3045
+ pack.sort(key=lambda e: _order.get(e.get('id'), len(pack)))
3046
+ # 四信号读数随包透出(可审计:谁因为什么排在前面)
3047
+ _sig_by_id = {it[0][0]['id']: it[2] for it in _ranked}
3048
+ for e in pack:
3049
+ sig = _sig_by_id.get(e.get('id'))
3050
+ if sig is not None:
3051
+ e['det'] = {'signals': sig, 'score': _dr.score(sig)}
3052
+ det_reranked = True
3053
+ except Exception: # noqa: BLE001 —— 重排失败回退原序,绝不拖崩装包
3054
+ det_reranked = False
3055
+ # ===== 读取策略改造 · A 项:跨轮状态聚合(Ornn8 测评建议①,+2~4 点最大头)=====
3056
+ # 病灶(report 原文):「答案状态散在轮9 和轮20 两条里,检索给了直接相关的一条,
3057
+ # 拼不出完整状态」——这是**记忆组织**问题:search 只按单轮相关性给材料。
3058
+ # 本段不改排序、不改打分,只在**装包之后**追加一个聚合视图:同一话题的命中条目
3059
+ # 按时间排在一起,附「该话题的状态时间线」,让调用方能拼出完整状态。
3060
+ # 关闭:MDCG_TOPIC_AGG=0。
3061
+ aggregates = []
3062
+ try:
3063
+ if int(os.environ.get("MDCG_TOPIC_AGG", "1")) > 0 and len(pack) >= 2:
3064
+ aggregates = self._topic_aggregates(pack, query)
3065
+ except Exception: # noqa: BLE001 —— 聚合面不拖崩装包
3066
+ aggregates = []
3067
+ if isinstance(meta, dict):
3068
+ meta["det_reranked"] = det_reranked
3069
+ if det_reranked:
3070
+ meta["det_clock_source"] = _clock_source
3071
+ meta["det_mode"] = _mode
2856
3072
  return {"pack": pack, "tokens_used": used, "budget": budget_tokens,
2857
- "skipped": skipped, "recent": recent, "meta": meta}
3073
+ "skipped": skipped, "recent": recent, "meta": meta,
3074
+ "aggregates": aggregates}
2858
3075
 
2859
3076
  # ================= 1. Fix pairs 自动挖掘 =================
2860
3077
 
@@ -268,7 +268,7 @@ def trace(cg, window: int = 50) -> dict:
268
268
  # 观测面 2:自信校准(期望正确率 vs 实际验证通过率)
269
269
  # --------------------------------------------------------------------------
270
270
 
271
- # 生效条件:形参 cg 的 index.nodes 中满足 evidence_count>0 且 frontmatter 的正例+负例>0 的节点计数 used,在 used >= int(max_scan)(默认 2000,max_scan 为 0 时立即 break 使 used=0)时截断——used 为 0 返回 ok=False/insufficient_data,否则按 used 与常量 MIN_SAMPLES、期望减实际的 gap 与 GAP_OVERCONFIDENT/GAP_UNDERCONFIDENT 判定 verdict(insufficient_data/overconfident/underconfident/calibrated);
271
+ # 生效条件:形参 cg 的 index.nodes 中满足 evidence_count>0 且 frontmatter 的正例+负例>0 的节点计数 used,在 used >= int(max_scan)(默认 2000,max_scan 为 0 时立即 break 使 used=0)时截断——used 为 0 返回 ok=False/insufficient_data;used 达标但 **Σ正例==0**(全库无 confirmed,issue #829)时 calibrated/overconfident/underconfident 三值一律不判,verdict 落 insufficient_data 且 calibration_defined=False、reason=no_positive_evidence(此时 actual_accuracy 数学上恒 0、gap 恒等于 expected,三值读数不携带信息);正例存在时按 used 与常量 MIN_SAMPLES、期望减实际的 gap 与 GAP_OVERCONFIDENT/GAP_UNDERCONFIDENT 判定 verdict(insufficient_data/overconfident/underconfident/calibrated);两种分支的返回体都带 n_by_layer(逐层 节点/正例/负例 构成);
272
272
  def calibration(cg, max_scan: int = 2000) -> dict:
273
273
  """自信校准:我说的可信吗?
274
274
 
@@ -276,6 +276,18 @@ def calibration(cg, max_scan: int = 2000) -> dict:
276
276
  实际正确率 = Σ正例 / Σ(正例+负例)(来自 evidence_log 的聚合计数)。
277
277
  gap > 0 → 过度自信;gap < 0 → 过度保守。
278
278
  ECE = Σ(证据占比 × |桶内实际 - 桶内自信|)(期望校准误差)。
279
+
280
+ issue #829(2026-11-08):**分母里没有正例时,本函数不判方向**。
281
+ 修前:判据是 `总正例 / (总正例 + 总负例)`,而本仓没有任何生产路径写
282
+ `confirmed`(`verify(verdict="confirmed")` 只有测试与外部裁决会发),
283
+ 故活库 Σ正例 恒为 0 ⇒ `actual_accuracy` 数学上恒为 0.0、`gap` 恒等于
284
+ `expected_accuracy` ⇒ `verdict` **恒为 overconfident**。这不是「读数偏低」,
285
+ 是**该字段不携带信息**;下游 `self_state` / `report` / `scrub.calibrate`
286
+ 把它当真读数消费(scrub 会据此向节点写回 confidence 偏置)。
287
+ 恒红比不报更有害,故:Σ正例==0 时 `verdict="insufficient_data"`、
288
+ `calibration_defined=False`、`reason="no_positive_evidence"`,
289
+ **expected/actual/gap/ece 照旧如实算并透出**(不隐藏、不编造),
290
+ 另给 `n_by_layer` 让「人口构成」在读数面可见。
279
291
  """
280
292
  keys = [f"{lo:g}-{hi:g}" for lo, hi in BINS]
281
293
  buckets = {k: {"n": 0, "conf_sum": 0.0, "pos": 0, "neg": 0} for k in keys}
@@ -291,6 +303,10 @@ def calibration(cg, max_scan: int = 2000) -> dict:
291
303
  # 只把「没进桶」这件事从静默变成可观测。
292
304
  dropped_count = 0
293
305
  dropped_ids = []
306
+ # issue #829:逐层人口构成(节点数 / 正例 / 负例)。修前 `n_by_layer`
307
+ # 在整个包里零命中(#827 早期正文声称「已提」是误记),故「分母为什么
308
+ # 没有正例」在读数面不可见。
309
+ pop_by_layer = {}
294
310
  for nid, e in _nodes(cg).items():
295
311
  if used >= int(max_scan):
296
312
  break
@@ -306,6 +322,11 @@ def calibration(cg, max_scan: int = 2000) -> dict:
306
322
  exp_sum += conf
307
323
  total_pos += pos
308
324
  total_neg += neg
325
+ _lay = str(fm.get("layer") or "unknown")
326
+ _b = pop_by_layer.setdefault(_lay, {"n_nodes": 0, "pos": 0, "neg": 0})
327
+ _b["n_nodes"] += 1
328
+ _b["pos"] += pos
329
+ _b["neg"] += neg
309
330
  placed = False
310
331
  for lo, hi in BINS:
311
332
  if lo <= conf < hi:
@@ -326,6 +347,8 @@ def calibration(cg, max_scan: int = 2000) -> dict:
326
347
  return {"ok": False, "reason": "insufficient_data", "n_nodes": 0,
327
348
  "dropped": 0, "out_of_range": 0, "dropped_ids": [],
328
349
  "dropped_ids_truncated": False,
350
+ "n_by_layer": {},
351
+ "calibration_defined": False,
329
352
  "note": "无带证据的节点:先 verify() 积累验证记录"}
330
353
  expected = exp_sum / used
331
354
  actual = total_pos / max(1, total_pos + total_neg)
@@ -345,7 +368,18 @@ def calibration(cg, max_scan: int = 2000) -> dict:
345
368
  "accuracy": None if acc_b is None else round(acc_b, 4)})
346
369
  if n_ev and total_ev:
347
370
  ece += (n_ev / total_ev) * abs(conf_b - acc_b)
348
- if used < MIN_SAMPLES:
371
+ # issue #829:**正例入口缺失 ⇒ 不判方向**。
372
+ # actual = 0/(0+neg) 恒为 0,gap 恒等于 expected,verdict 必然 overconfident。
373
+ # 这不是「偏过度自信」,是分母里没有正例。故 calibration_defined=False,
374
+ # 方向三值一律不判(verdict=insufficient_data),期望/实际/gap/ece 仍如实透出。
375
+ calibration_defined = used >= MIN_SAMPLES and total_pos > 0
376
+ if total_pos <= 0:
377
+ reason = "no_positive_evidence"
378
+ elif used < MIN_SAMPLES:
379
+ reason = "insufficient_samples"
380
+ else:
381
+ reason = None
382
+ if not calibration_defined:
349
383
  verdict = "insufficient_data"
350
384
  elif gap > GAP_OVERCONFIDENT:
351
385
  verdict = "overconfident"
@@ -362,11 +396,20 @@ def calibration(cg, max_scan: int = 2000) -> dict:
362
396
  "dropped_ids": list(dropped_ids),
363
397
  "dropped_ids_truncated": dropped_count > len(dropped_ids),
364
398
  "n_evidence": total_ev,
399
+ # issue #829:人口构成透出(分母为什么长这样,读数面可见)。
400
+ "n_positive": total_pos,
401
+ "n_negative": total_neg,
402
+ "n_by_layer": pop_by_layer,
403
+ "calibration_defined": calibration_defined,
365
404
  "expected_accuracy": round(expected, 4),
366
405
  "actual_accuracy": round(actual, 4),
367
406
  "gap": round(gap, 4),
368
407
  "ece": round(ece, 4),
369
408
  "verdict": verdict,
409
+ **({"reason": reason} if reason else {}),
410
+ **({"note": "分母无正例(无任何 confirmed 裁决):actual 恒 0、"
411
+ "gap 恒等于 expected,方向不判。先积累 confirmed 证据"}
412
+ if reason == "no_positive_evidence" else {}),
370
413
  "bins": bins,
371
414
  }
372
415
 
@@ -491,7 +534,7 @@ def trust(cg, window: int = 100, max_scan: int = 2000) -> dict:
491
534
  # 自报告:汇总 + 确定性建议
492
535
  # --------------------------------------------------------------------------
493
536
 
494
- # 生效条件:形参 tr.get("ok") 为假时产出 no_trace;否则按 tr["d2"] > D2_EMOTION 产出 diverging、state_rates["BLINDSPOT"] >= BLINDSPOT_DENSE 产出 blindspot_dense;再按 cal 的 verdict 为 overconfident/underconfident 与 bs.get("unresolved_count", 0) > 0 各自追加;全部未触发时返回单条 stable(形参 tt 在函数体内未被使用);
537
+ # 生效条件:形参 tr.get("ok") 为假时产出 no_trace;否则按 tr["d2"] > D2_EMOTION 产出 diverging、state_rates["BLINDSPOT"] >= BLINDSPOT_DENSE 产出 blindspot_dense;再按 cal 的 verdict 为 overconfident/underconfident 各自追加(issue #829:cal.calibration_defined 为假时**不追加方向建议**,改追加一条 no_positive_evidence 提示),并按 bs.get("unresolved_count", 0) > 0 追加 open_questions;全部未触发时返回单条 stable(形参 tt 在函数体内未被使用);
495
538
  def _advise(tr, cal, bs, tt) -> list:
496
539
  """确定性建议(非 LLM):每条都带触发它的证据,可复核。"""
497
540
  out = []
@@ -510,16 +553,26 @@ def _advise(tr, cal, bs, tt) -> list:
510
553
  "why": f"BLINDSPOT 占比 {rates.get('BLINDSPOT')} >= {BLINDSPOT_DENSE}",
511
554
  "action": "为高频盲区邻域建 unresolved 节点,驱动补条件"})
512
555
  verdict = cal.get("verdict")
513
- if verdict == "overconfident":
514
- out.append({"code": "overconfident",
515
- "why": (f"期望正确率 {cal['expected_accuracy']} > 实际 "
516
- f"{cal['actual_accuracy']}(gap {cal['gap']})"),
517
- "action": "对高 confidence 节点抽查复核;verify(weakened) 会触发降级"})
518
- elif verdict == "underconfident":
519
- out.append({"code": "underconfident",
520
- "why": (f"期望正确率 {cal['expected_accuracy']} < 实际 "
521
- f"{cal['actual_accuracy']}(gap {cal['gap']})"),
522
- "action": "自信偏低:可适度提升已验证节点的召回权重"})
556
+ # issue #829:方向不判时不产出方向建议——否则「恒 overconfident」会一路
557
+ # 变成「恒建议抽查复核」,把退化的读数变成退化的行动。
558
+ # 缺省视为可判(cal.get 无该键 = 旧调用方/单元夹具,保持既有行为)。
559
+ if cal.get("calibration_defined", True):
560
+ if verdict == "overconfident":
561
+ out.append({"code": "overconfident",
562
+ "why": (f"期望正确率 {cal['expected_accuracy']} > 实际 "
563
+ f"{cal['actual_accuracy']}(gap {cal['gap']})"),
564
+ "action": "对高 confidence 节点抽查复核;verify(weakened) 会触发降级"})
565
+ elif verdict == "underconfident":
566
+ out.append({"code": "underconfident",
567
+ "why": (f"期望正确率 {cal['expected_accuracy']} < 实际 "
568
+ f"{cal['actual_accuracy']}(gap {cal['gap']})"),
569
+ "action": "自信偏低:可适度提升已验证节点的召回权重"})
570
+ elif cal.get("reason") == "no_positive_evidence":
571
+ out.append({"code": "no_positive_evidence",
572
+ "why": (f"校准分母里正例为 0({cal.get('n_negative')} 条负例 / "
573
+ f"{cal.get('n_positive')} 条正例):actual 恒 0,"
574
+ f"方向不可判,gap={cal.get('gap')} 不构成过度自信证据"),
575
+ "action": "为已成立的结论补 verify(confirmed) 正例入口,再重读校准"})
523
576
  if bs.get("unresolved_count", 0) > 0:
524
577
  out.append({"code": "open_questions",
525
578
  "why": f"unresolved 层有 {bs['unresolved_count']} 个未解问题",
@@ -0,0 +1,126 @@
1
+ # -*- coding: utf-8 -*-
2
+ """定点变异自证:`md_cg/test_state_extract_shipped.py` 的每条判据是否真能红。
3
+
4
+ 口径(沿本仓既有变异纪律):逐个植入「本该被抓住」的缺陷,跑守卫,断言**必须红**;
5
+ 还原后断言**必须绿**且文件 sha256 逐字节还原。变异的对象是**仓内真实文件**
6
+ (先备份到内存,finally 必还原),不改在役库、不落第二份副本。
7
+
8
+ 运行:python -X utf8 -m md_cg.mutate_extract_shipped
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import hashlib
13
+ import os
14
+ import subprocess
15
+ import sys
16
+
17
+ HERE = os.path.dirname(os.path.abspath(__file__))
18
+ REPO = os.path.dirname(HERE)
19
+ CORE = os.path.join(HERE, "state_extract.py")
20
+ SHIM = os.path.join(REPO, "scripts", "state_extract.py")
21
+ PKG = os.path.join(REPO, "package.json")
22
+ GUARD = "md_cg.test_state_extract_shipped"
23
+
24
+
25
+ def sha(p):
26
+ return hashlib.sha256(open(p, "rb").read()).hexdigest()
27
+
28
+
29
+ def run_guard():
30
+ r = subprocess.run([sys.executable, "-X", "utf8", "-m", GUARD],
31
+ cwd=REPO, capture_output=True, text=True,
32
+ encoding="utf-8", errors="replace",
33
+ env={**os.environ, "PYTHONUTF8": "1"})
34
+ return r.returncode, (r.stdout or "") + (r.stderr or "")
35
+
36
+
37
+ def mutate(label, path, old, new, expect_hit_substr):
38
+ """把 path 里 old 换成 new,跑守卫,断言必须红且命中期望断言;还原。"""
39
+ orig = open(path, encoding="utf-8").read()
40
+ backup = orig
41
+ digest = sha(path)
42
+ if old not in orig:
43
+ print(" SKIP %-52s (变异锚点不存在:%r)" % (label, old[:40]))
44
+ return None
45
+ try:
46
+ open(path, "w", encoding="utf-8", newline="\n").write(
47
+ orig.replace(old, new, 1))
48
+ rc, out = run_guard()
49
+ hit = expect_hit_substr in out
50
+ caught = rc != 0 and hit
51
+ print((" OK " if caught else " MISS ") + "%-52s rc=%s 命中=%s"
52
+ % (label, rc, hit))
53
+ return caught
54
+ finally:
55
+ open(path, "w", encoding="utf-8", newline="\n").write(backup)
56
+ assert sha(path) == digest, "!! 还原后 sha256 不一致:" + path
57
+
58
+
59
+ def main():
60
+ print("== 基线(必须先绿)")
61
+ rc0, out0 = run_guard()
62
+ print(" 基线 rc=%s(0=绿)" % rc0)
63
+ if rc0 != 0:
64
+ print(out0)
65
+ return 1
66
+
67
+ print("== 逐条变异(每行都必须 OK=被抓住)")
68
+ results = []
69
+
70
+ # M1:本体删掉生产面 → A2 必红(模拟「本体没搬过来」)
71
+ results.append(mutate(
72
+ "M1 本体删 extract_and_record 定义", CORE,
73
+ "def extract_and_record(cg, session: str, turn_no, role: str, text: str,",
74
+ "def _gone_extract_and_record(cg, session: str, turn_no, role: str, text: str,",
75
+ "A2 本体定义了生产面 extract_and_record"))
76
+
77
+ # M2:垫片重新实现判据 → B2 必红(模拟「两份实现」复发)
78
+ results.append(mutate(
79
+ "M2 垫片重新定义 RULES(两份判据)", SHIM,
80
+ 'from md_cg.state_extract import (',
81
+ 'RULES = []\n\nfrom md_cg.state_extract import (',
82
+ "B2 垫片不得重新定义生产面符号"))
83
+
84
+ # M3:垫片包一层 wrapper → C1 必红(模拟「薄别名变成真实现」)
85
+ results.append(mutate(
86
+ "M3 垫片把 extract_turn 包成 wrapper", SHIM,
87
+ 'from md_cg.state_extract import ( # noqa: E402,F401 —— 薄别名,非实现',
88
+ 'from md_cg.state_extract import extract_turn as _core_extract_turn\n'
89
+ 'def extract_turn(*a, **k):\n return _core_extract_turn(*a, **k)\n\n'
90
+ 'from md_cg.state_extract import ( # noqa: E402,F401 —— 薄别名,非实现',
91
+ "C1 垫片 extract_turn 与本体是同一对象"))
92
+
93
+ # M4:白名单删掉 md_cg → D1 必红(模拟「生产方目录不可发货」)
94
+ results.append(mutate(
95
+ "M4 package.json files 删掉 md_cg", PKG,
96
+ '"lib",\n "src",\n "md_cg",',
97
+ '"lib",\n "src",',
98
+ "D1 生产方目录"))
99
+
100
+ # M5:extract_and_record 不落台账 → E1 必红(模拟「抽取了但不记账」)
101
+ # 注意:变异必须是**语义有效**的。首版把 `_se.append(...)` 那行替换成 `pass`
102
+ # 留下后面几行实参 ⇒ SyntaxError(rc=1 但根本没走到 E1)——那是**假捕获**,
103
+ # 证明不了断言有力度。改为在函数体开头插 `return 0`:语法合法、语义是
104
+ # 「抽了但不记账」,E1 必须以断言文本失败。
105
+ results.append(mutate(
106
+ "M5 extract_and_record 提前 return 0(不记账)", CORE,
107
+ " n = 0\n for ev in extract_turn(text, role, subject):",
108
+ " return 0 # MUTANT: 不记账\n n = 0\n for ev in extract_turn(text, role, subject):",
109
+ "E1 从 md_cg 本体可直接抽取并落台账"))
110
+
111
+ print("== 还原后必须复绿")
112
+ rc1, out1 = run_guard()
113
+ print(" 还原后 rc=%s(0=绿)" % rc1)
114
+
115
+ done = [r for r in results if r is not None]
116
+ caught = sum(1 for r in done if r)
117
+ print()
118
+ print("变异自证:%d/%d 被捕获;还原后复绿=%s"
119
+ % (caught, len(done), rc1 == 0))
120
+ okall = caught == len(done) and len(done) == 5 and rc1 == 0
121
+ print("结论:" + ("全部判据有力度(可红可复绿)" if okall else "存在无力度判据"))
122
+ return 0 if okall else 1
123
+
124
+
125
+ if __name__ == "__main__":
126
+ raise SystemExit(main())