@furongjun1999/dsh-memory 0.5.1 → 0.6.1

package/md_cg/routing.py

@@ -269,27 +269,54 @@ def domain_similarity(a: str, b: str) -> float:
     return len(ga & gb) / len(ga | gb)
 
 
-# 生效条件：counts 各值之和为 0（含空 dict 与全 0 计数）时返回 {'ok': True, 'reason': 'empty', 'buckets': 0}；否则在最大桶占比 >30%、桶数 >1 且单例桶占比 >50%、期望扫描 >30% 中命中的项写入 problems，返回含 ok(=problems 为空)、buckets、nodes、max_bucket_share、singleton_ratio、expected_scan、problems 的 dict。
-def bucket_health(counts: dict) -> dict:
+# 生效条件：counts 各值之和为 0（含空 dict 与全 0 计数）时——total_nodes 为假值（缺省 None 或 <=0）返回 {'ok': True, 'reason': 'empty', 'buckets': 0}（与加 total_nodes 参数之前逐位一致），total_nodes > 0 返回 {'ok': False, 'reason': 'empty_buckets', 'buckets': 0, 'nodes': total_nodes, 'problems': [...]}；否则在「桶数 >1 且最大桶占比 >30%」、「桶数 >1 且单例桶占比 >50%」、「桶数 ==1（单桶，条件路由不可用）」、桶数 >1 时「期望扫描 >30%」中命中的项写入 problems，返回含 ok(=problems 为空)、buckets、nodes、max_bucket_share、singleton_ratio、expected_scan、problems 的 dict。
+def bucket_health(counts: dict, total_nodes: int = None) -> dict:
     """分区健康度自检。分桶键一旦退化（巨桶或碎片化），条件路由就是纸面收益，
     必须在写入侧就能发现，而不是等召回变差才回头查。
 
     counts: {bucket_dir: node_count}
+    total_nodes: 调用方（`MdCG.health`）持有的**库内节点总数**，唯一用途是把
+      「真空库（无节点、无桶）」与「有节点但分桶表为空（分区信息缺失）」分开。
+      **缺省 None ⇒ 不做该比对**：空 counts 的返回与加本参数之前逐位一致，
+      故既有调用方（test_p0 / bench_axis_domain / bench6_arms，只传 counts）
+      行为一字不变——M3③ 的向后兼容面。
+
+    单桶（nb == 1）是「从未分区」而不是「分区退化」：巨桶判据（top/n == 1.0）与
+    期望扫描判据（同样恒 1.0）在 nb==1 时必触发且互为同一事实，此前把这类库报成
+    「巨桶 / 分区失效」是假话（M3①②）。现只给一条如实读数——条件路由本就不可用；
+    ok 仍为 False（单桶库的一次查询确实是全量扫描，判据未放宽）。
     """
     n = sum(counts.values())
+    nb = len(counts)
     if not n:
+        # 库里有节点却零个桶 ⇒ 分桶表与节点面不一致（分区信息缺失），
+        # 不能报 ok=True 冒充健康（M3③）。total_nodes 缺省时不作此判断。
+        if total_nodes and total_nodes > 0:
+            return {
+                "ok": False,
+                "reason": "empty_buckets",
+                "buckets": 0,
+                "nodes": int(total_nodes),
+                "problems": [f"分桶表为空但库内有 {int(total_nodes)} 个节点："
+                             "分区信息缺失，条件路由不可用（非真空库）"],
+            }
         return {"ok": True, "reason": "empty", "buckets": 0}
-    nb = len(counts)
     top = max(counts.values())
     singles = sum(1 for v in counts.values() if v == 1)
     # 期望扫描占比：随机取一节点的情境去路由，命中桶的期望大小占全库比例
     expected_scan = sum(v * v for v in counts.values()) / n / n
     problems = []
-    if top / n > 0.30:
+    if nb > 1 and top / n > 0.30:
         problems.append(f"巨桶：最大桶占 {top / n:.1%}（>30% 视为分区失效）")
     if nb > 1 and singles / nb > 0.50:
         problems.append(f"碎片化：单例桶占 {singles / nb:.1%}（>50% 说明键含实例级字段）")
-    if expected_scan > 0.30:
+    if nb == 1:
+        # 巨桶/期望扫描两条在 nb==1 时只是同一事实的两种写法，合并为一条如实读数。
+        # expected_scan 的**数值**仍在返回 dict 里（下游读的是数：test_p0 :92、
+        # bench_axis_domain :159），只有文案不再把「未分区」说成「巨桶退化」。
+        problems.append(f"单桶：全库仅 1 个分桶（{n} 个节点同桶），"
+                        "条件路由本就不可用（从未分区，非分区退化）")
+    elif expected_scan > 0.30:
         problems.append(f"路由无效：期望扫描 {expected_scan:.1%}（接近全量）")
     return {
         "ok": not problems,

package/md_cg/run_tests.py

@@ -38,6 +38,23 @@ import sys
 import tempfile
 import time
 
+# ---------------------------------------------------------------- 入口自保证 UTF-8
+# 约束（工作纪律第 15 条）：本调用必须在**任何文件/库 I/O 之前**——utf8_boot.ensure_utf8
+# 在解释器未开 UTF-8 模式时以相同 argv 重启自身（-X utf8），早于它的任何 open/stdio
+# 读写都走 locale 编码（Windows 中文机 = cp936：裸 open 抛 UnicodeDecodeError、中文写
+# 落 GBK 字节）。本文件是包内全量入口（安装态下 README 的门禁命令），必须最先保证。
+# 仓库根入 sys.path 的形态照 hive/exec.py::_md_cg_import 的最小写法（助手在仓根，
+# 不是 md_cg 包目录）。
+# 被 import（本模块非 __main__）时助手只置子进程继承面、绝不重启/退出——F6：静默重启
+# 会吞掉调用方输入。
+_UTF8_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _UTF8_ROOT not in sys.path:
+    sys.path.insert(0, _UTF8_ROOT)
+from utf8_boot import ensure_utf8  # noqa: E402
+
+ensure_utf8(__file__)
+
+
 _REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 #: 逐用例日志目录（重定向目标；默认临时目录，避免污染仓）
 _LOG_DIR = os.environ.get("MDCG_TESTLOG_DIR") or os.path.join(

package/md_cg/scrub.py

@@ -715,8 +715,8 @@ def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
 # ④ 校准偏差
 # --------------------------------------------------------------------------
 
-# 生效条件：对 cg 中每个「layer 不在 SELF_LAYERS」且 evidence_count≥int(min_evidence)（min_evidence=0 时该比较恒假而不早退）的节点，若 protect.is_protected 为假或 override 为真，且 cg.get(nid) 未抛异常并返回真值节点，则取 fm.get("confidence", 0.6)（缺键才回落 0.6，键存在为 None/假值不回落）为 old，算出 round(max(0.0, min(0.99, old+float(offset))),4)，与 old 差<1e-9 时跳过，否则写 fm["confidence"] 与 fm["calibration"] 并调用 cg._write_node 成功时 adjusted+1（写回异常被吞掉不计数），返回 (adjusted, skipped)，其中 skipped 只累计「layer 属 SELF_LAYERS」或被 protect 拦下且非 override 的节点。
-def _apply_offset(cg, offset, *, override=False, min_evidence=1):
+# 生效条件：对 cg 中每个「layer 不在 SELF_LAYERS」且 evidence_count≥int(min_evidence)（min_evidence=0 时该比较恒假而不早退）的节点，若 protect.is_protected 为假或 override 为真，且 cg.get(nid) 未抛异常并返回真值节点，则先以节点真层/敏感度过 protect.guard_overwrite（层闸 + 保护闸，override 为真时先快照 + 审计，越权抛 AccessDenied 且整批中止），再取 fm.get("confidence", 0.6)（缺键才回落 0.6，键存在为 None/假值不回落）为 old，算出 round(max(0.0, min(0.99, old+float(offset))),4)，与 old 差<1e-9 时跳过，否则写 fm["confidence"] 与 fm["calibration"] 并调用 cg._write_node，成功后置 cg._dirty[nid]=e（**标脏**：推进读缓存代际与索引增量日志）并 adjusted+1（写回异常被吞掉不计数），返回 (adjusted, skipped)，其中 skipped 只累计「layer 属 SELF_LAYERS」或被 protect 拦下且非 override 的节点。
+def _apply_offset(cg, offset, *, override=False, min_evidence=1, actor=None):
     nodes = _nodes(cg)
     adjusted = skipped = 0
     for nid, e in nodes.items():
@@ -736,6 +736,20 @@ def _apply_offset(cg, offset, *, override=False, min_evidence=1):
         if not node:
             continue
         fm = node.get("frontmatter") or {}
+        # N222（2026-09-28，同族未接线写点）：本函数是 calibrate 落库动作，此前
+        # 直调 `cg._write_node` 改写**全库** `layer∉(self,anchor)` 且
+        # `evidence_count≥1` 节点的 confidence/calibration——不过 principal 层写
+        # 白名单、不过引擎级保护闸、`override` 形参直通（含 importance≥0.7 的
+        # 不可遗忘节点），无快照无审计。持 sustain 令牌（`tokens.py:190`
+        # `layers_allow=('self',)`）即可改 knowledge 层节点置信度（实测
+        # `n_adjusted=5`，0.8→0.95；`override=True` 再 +1）。落盘前统一过
+        # `protect.guard_overwrite`：层/敏感度取**节点 fm 真值**（不信索引缓存），
+        # 解析与层闸由 `protect.require_layer` 单点承担，越权即 AccessDenied
+        # 整批中止（fail-closed，不静默跳过——否则越权面被伪装成「无可校准节点」）；
+        # `override=True` 走同一闸的显式放行分支（快照 + `_protected_audit.jsonl`）。
+        protect.guard_overwrite(cg, nid, layer=fm.get("layer"),
+                                sensitivity=fm.get("sensitivity"),
+                                override=override, actor=actor)
         old = float(fm.get("confidence", 0.6))
         new = round(max(0.0, min(0.99, old + float(offset))), 4)
         if abs(new - old) < 1e-9:
@@ -746,6 +760,18 @@ def _apply_offset(cg, offset, *, override=False, min_evidence=1):
         try:
             cg._write_node(nid, os.path.join(cg.root, e["path"]), fm,
                            node.get("content") or "")
+            # 标脏（N133 修复，对照先例 md_cg/mdcg.py 的 update_tags / verify
+            # 直写分支 `self._dirty[node_id] = e`）：本函数原先写盘后**完全不
+            # 碰索引**（条目字段集不含 confidence，无需同步），但正因如此
+            # path_gen 不推进 ⇒ 读缓存（默认开）把写盘前的旧 fm 判新鲜——
+            # 同进程「calibrate 后读」拿旧 confidence（其余两处同族写点
+            # forgetting.reinforce / insight.verify 同批补标脏）。标脏同时
+            # 让本写进 `_dirty → flush → _index_log` 重放。**不下沉进
+            # `_write_node`**：该口另有「只对账索引不落盘」的调用方，下沉会
+            # 凭空产生写入代际与自重载。
+            _dirty = getattr(cg, "_dirty", None)
+            if isinstance(_dirty, dict):
+                _dirty[nid] = e
             adjusted += 1
         except Exception:                                 # noqa: BLE001
             pass
@@ -777,7 +803,8 @@ def calibrate(cg, *, apply: bool = False, override: bool = False, actor=None,
     adjusted = skipped = 0
     if apply and abs(offset) > 1e-9:
         adjusted, skipped = _apply_offset(cg, offset, override=override,
-                                          min_evidence=min_evidence)
+                                          min_evidence=min_evidence,
+                                          actor=actor)
         _log(cg, "calibrate", ok=True, offset=offset, gap=gap,
              adjusted=adjusted, actor=actor)
     blind = 0

package/md_cg/security.py

@@ -382,4 +382,50 @@ def can_read_restricted(p) -> bool:
         return False
     if getattr(p, "can_admin", False):
         return True
-    return getattr(p, "role", "") in _RESTRICTED_READER_ROLES
+    return getattr(p, "role", "") in _RESTRICTED_READER_ROLES
+
+
+# --------------------------------------------------------------------------
+# 读可见性可选钩子（跨层唯一实现，批次 68）
+# --------------------------------------------------------------------------
+# 为什么放在本模块：可见性单点 `_readable` 定义在**子类** `MdCGSecure`
+# （mdcos.py:4028），而需要它的读数出口散在**下层/旁路模块**——trust（验证态
+# 台账/describe）、provenance（派生边端点摘要与拓扑）、evolution（演化账本
+# 自由文本）、forgetting（遗忘留痕 jsonl）。这些模块若 `from .mdcos import` 会
+# 成环（mdcos 反向导入它们），故单点放在两侧都依赖的 security.py：
+#   · `visible_to(cg, entry)`   —— 条目级判定（口径 = `_readable`）；
+#   · `node_visible(cg, node_id)` —— 节点 id 级判定（索引取条目 + 缺席处置）。
+# 口径与仓内既有三处可选钩子逐条一致：`mdcos._note_visible`（及本函数的
+# 委派）、`backfill._readable_guard`、`linkref._known_ids`、`stg._scan/_preview`
+# ——「无钩子（纯 MdCGOS，无身份/密级模型）= 不限制；有钩子 = 按判据；
+# 判据异常 = 不可见（fail-closed）；宁可少读，不可 fail-open 泄漏」。
+# 生效条件：cg 有可调用的 _readable 时返回 bool(判定结果)，判定抛异常返回 False；无该属性/不可调用（纯 MdCGOS）时返回 True。
+def visible_to(cg, entry) -> bool:
+    """条目级读可见性（cg 无 `_readable` 钩子时不设限）。"""
+    fn = getattr(cg, "_readable", None)
+    if not callable(fn):
+        return True
+    try:
+        return bool(fn(entry))
+    except Exception:                          # noqa: BLE001 —— 判据异常=不可见
+        return False
+
+
+# 生效条件：cg 无可调用 _readable 时返回 True；有钩子且索引条目为 dict 时返回 bool(visible_to(cg, 条目))（判定异常 False）；索引无该条目/条目非 dict 时返回 bool(principal.can_admin)（有身份模型但不可证可见→fail-closed，设计者不受限，否则删除后的治理留痕反被清空）。
+def node_visible(cg, node_id) -> bool:
+    """节点 id 级读可见性（索引取条目；**缺席 = 不可证可见 → fail-closed**）。
+
+    缺席的两种实情：① 节点从未存在/拼错 id；② 节点已被 forget（索引无条目）。
+    有身份模型时两者都不得被「当作可见」——否则 `_forgetting.jsonl` /
+    `trust` 台账 / 派生边摘要就成了「已删内容」的旁路读出（N205/N226/N229）。
+    例外只给 can_admin（设计者=全局观测与治理本职）：否则删除后的裁决留痕
+    对唯一需要它的人也不可见（与 `_readable` 的 can_admin 豁免同款）。
+    """
+    fn = getattr(cg, "_readable", None)
+    if not callable(fn):
+        return True                            # 无身份模型：无「越权」可言
+    e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
+    if isinstance(e, dict):
+        return visible_to(cg, e)
+    p = getattr(cg, "principal", None)
+    return bool(p is not None and getattr(p, "can_admin", False))

package/md_cg/self_state.py

@@ -355,7 +355,7 @@ def _relation_counts(cg, subject):
     slug = _slug(subject)
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
     out = inn = 0
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tags = set(e.get("tags") or [])
         if TAG_RELATION not in tags and not nid.startswith(RELATION_PREFIX):
             continue
@@ -656,7 +656,7 @@ def relations(cg, subject=None, direction="both"):
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
     slug = _slug(subject) if subject else None
     out = []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tags = set(e.get("tags") or [])
         if TAG_RELATION not in tags and not nid.startswith(RELATION_PREFIX):
             continue
@@ -692,7 +692,7 @@ def index(cg, dim, value, limit=50, with_content=False):
                 "allowed": list(DIMENSIONS)}
     tag = dim_tag(d, value)
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
-    hits = [(nid, e) for nid, e in nodes.items()
+    hits = [(nid, e) for nid, e in list(nodes.items())
             if tag in (e.get("tags") or [])]
     hits.sort(key=lambda kv: (-float(kv[1].get("importance") or 0),
                               -float(kv[1].get("created_at") or 0),
@@ -740,7 +740,7 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
 
     # 1 单例：同 subject 的状态卡只能有一张
     slug = _slug(subject)
-    cards = [n for n, e in nodes.items()
+    cards = [n for n, e in list(nodes.items())
              if TAG_STATE in (e.get("tags") or [])
              and f"state_subject:{slug}" in (e.get("tags") or [])]
     if len(cards) > 1:
@@ -878,7 +878,7 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
             continue
         for v in (vals or []):
             tag = dim_tag(d, v)
-            holders = [n for n, e in nodes.items()
+            holders = [n for n, e in list(nodes.items())
                        if tag in (e.get("tags") or [])]
             if not holders:
                 issues.append(_issue("dimension_orphan", "warn",

package/md_cg/sources.py

@@ -273,8 +273,17 @@ class HiveJobsSource(Source):
       result.json 终态 → **权威确认事件**（progress 可能因强杀缺失 final）：
                           done → 「任务完成(job=…)」；error/timeout/killed → 「任务失败(job=…)」
 
-    排序：job_id 名升序 = 时间升序（job.rs 命名保证 h<unix_ms>_<pid>），
-    跨 job 全序成立；seq 由本源按枚举顺序递增（ingest 去重键 = (session, seq)）。
+    排序：**job_id 名升序**（`sorted(listdir)`，确定性），**不是**时间序——
+    契约 v2（`docs/plans/全中文编码与蜂巢任务标识契约_v2.0.md` §四.5）起 id 改为
+    语义四槽 `h_<身份>_<任务>_<单元>_<编号>`，名序不再等于提交时序：旧形态
+    `h<unix_ms>_<pid>` 才是「名序 = 时间序」的**巧合代理**。据实订正（C2：本仓
+    禁止把代理当结构保证）——本源的时序由来源行自带的 ts 承载，排序只求
+    **跨 job 全序且确定**（seq 由本源按枚举顺序递增，ingest 去重键 = (session, seq)，
+    名序的确定性保证该键跨轮稳定）。
+    诚实边界（**已发现、未在本批动码**）：本源的 `_jobs()` 若需要**真时间序**，
+    应改走与 Rust 侧同判据的 created_ts 真值（`hive/src/job.rs::list_jobs_by_created`
+    的语义，Python 侧对应 `mcp_server._list_jobs_by_created`）——契约 §四.5 的消费者
+    清单未列本源，且改动牵动 md_cg 摄入链语义与其守卫，故留待单独裁决，不静默改。
     解析失败的行/条目计入 self.skipped，不终杀批次。
     """
 
@@ -626,11 +635,14 @@ class FileDispatcher:
 
     # ---- stat：看水位与支持面 ----
 
-# 生效条件：from . import refindex 与 refindex.Ledger(self.cg.root).stat() 均不抛异常时返回该 stat 结果，抛任何异常时返回 {}。
+# 生效条件：from . import refindex 与 refindex.Ledger(self.cg.root).summary() 均不抛异常时返回该 summary 结果，抛任何异常时返回 {}。
     def _ledger_stat(self):
+        # `Ledger` 只有 `summary()`、**没有** `stat()`：此前写 `.stat()` 撞
+        # AttributeError 被下面的 except 吞成 `{}`，于是 `ingest stat` 的水位面
+        # 永远是空且无人知晓（唯一实现面是 `refindex.Ledger.summary`）。
         try:
             from . import refindex
-            return refindex.Ledger(self.cg.root).stat()
+            return refindex.Ledger(self.cg.root).summary()
         except Exception:                                  # noqa: BLE001
             return {}
 
@@ -702,7 +714,7 @@ class FileDispatcher:
                 "counts": counts,
                 "note": "预演：仅统计各链文件数，未做任何写入"}
 
-# 生效条件：root 非目录时返回 ok=False 的「目录不存在」；dry_run 为真时返回 _dry_dir(root)；否则对 doc_ref/code_ref 两链各以 patterns/max_files/max_items/incremental/ledger 调 refindex.index_dir 与 add_items，并把 root 下 **/*.jsonl 前 max_files 个逐个 ingest_jsonl 后返回 out。
+# 生效条件：root 非目录时返回 ok=False 的「目录不存在」；dry_run 为真时返回 _dry_dir(root)；否则对 doc_ref/code_ref 两链各以 patterns/max_files/max_items/incremental/ledger 调 refindex.index_dir(commit=False) 与 add_items 后 ledger.save()，并把 root 下 **/*.jsonl 前 max_files 个逐个 ingest_jsonl 后返回 out。
     def ingest_dir(self, root, layer=None, sensitivity=None, patterns=None,
                    max_files=500, max_items=2000, incremental=False,
                    dry_run=False):
@@ -716,13 +728,18 @@ class FileDispatcher:
         for ref_kind, key in (("doc_ref", "doc"), ("code_ref", "code")):
             items, errors, stats = refindex.index_dir(
                 root, kind=ref_kind, patterns=patterns, max_files=max_files,
-                max_items=max_items, incremental=incremental, ledger=ledger)
+                max_items=max_items, incremental=incremental, ledger=ledger,
+                commit=False)
             ids, sens = refindex.add_items(self.cg, items, kind=ref_kind,
                                            root=root, layer=layer,
                                            sensitivity=sensitivity)
+            # 写序（同 op=index_code/index_doc）：节点先落盘，水位随后——
+            # 中途被杀只会留下「节点新 + 水位旧」，下次增量重切，不会静默漏漂移。
+            ledger.save()
             out["chains"][key] = {
                 "indexed": len(ids), "errors": len(errors),
                 "files": stats.get("files"), "truncated": stats.get("truncated"),
+                "empty_scan": stats.get("empty_scan"),
                 "skipped_unchanged": stats.get("skipped_unchanged", 0),
                 "skipped_suffixes": stats.get("skipped_suffixes", []),
                 "sensitivity": sens}