@furongjun1999/dsh-memory 0.5.1 → 0.6.1

package/md_cg/test_review_cli_visibility.py

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+"""md_cg · review_cli 裁决落盘跨进程可见性守卫（P1b autoflush 第二落点，DSH 端在役实测）
+
+缺陷（修复前）：`review_cli._cg` 构造 `MdCGSecure(_root(args), principal=p)`
+不传 autoflush → 缺省 64。库的索引增量链路是「写入先经 `_stage` 入内存
+`_dirty` 与内存索引，攒够 autoflush 条才 flush() 落分片日志 `_index_log/`」；
+短命进程的**正常退出**另有 main finally `cg.close()` + 库层 atexit 双兜底
+（mdcg.py `_LIVE_CGS`，2026-09-16 取证），但**被 kill / 崩溃退出时两者都不
+执行**（兜底刻意只覆盖正常退出这一条路径）——裁决落盘的少量节点停在内存
+索引、分片日志从未落，盘面节点文件在而索引链路断。DSH 端在役实测：裁决后
+MCP 读面 read null。对照：mcp_server.py:3695-3702 同症状 2026-09-16 已修
+（server 级 autoflush=1 兜底），review_cli 这个短命工具落点被遗漏——本修复
+补齐，与 server 同款。
+
+守卫（四组，全部临时库 + 哑主密钥，绝不触真实 ~/.mdcg）：
+  ① 真实在役入口：subprocess 跑 `python -m md_cg.review_cli accept`（正常
+    完成）→ 进程 B（全新 python 子进程 _load_index + read）断言业务节点与
+    审计记录节点均可见。
+  ② kill 形态可见性：进程 A' 等价直接调库落盘 2 条（无任何显式 flush）后
+    `os._exit(0)`（模拟被杀：close/atexit 全部跳过）→ 进程 B 全新子进程
+    断言读回可见。
+  ③ 落账契约（autoflush=1 的直接可观察效应，**修复前红**）：② 的进程 A'
+    被杀退出后，盘面 `_index_log/` 必须已含其全部写入的索引记录——"写入即
+    落分片日志"，与 mcp_server 的 server 级 autoflush=1 同一契约。
+  ④ 同病工具面：evidence._open_cg / scripts/linkref_backfill /
+    scripts/migrate_restricted 同样补 autoflush=1（前两者行为断言
+    .autoflush==1，后两者源级断言构造语句带参）。
+
+如实边界：本仓 HEAD 上 ①② 的读面断言在修复前已绿——正常路径由 09-16 的
+review_decide 显式 flush（mdcos.py）+ close/atexit 兜底覆盖；kill 形态的
+重开读面由批次39（2026-09-25）`_load_index` 指纹失配全扫自愈兜住。修复前
+红的只有 ③ 的落账契约与在役旧读面（0.4.x 副本 `_load_index` 盲信快照）——
+后者正是 DSH 端观察到 read null 的形态；本守卫把读面断言一并钉住，防上述
+两层兜底未来被移除时旧症复发。
+
+运行：python -m md_cg.test_review_cli_visibility
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from .mdcg import ShardedLog
+from .mdcos import MdCGSecure
+from .security import Principal
+
+PASS = FAIL = 0
+FAILS = []
+
+REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+DUMMY_KEY = "ab" * 32          # 哑主密钥：子进程绝不触真实 ~/.mdcg/master.key
+
+KILL_CHILD = r'''
+import argparse, os, sys
+sys.path.insert(0, sys.argv[2])
+from md_cg import review_cli
+# 等价直接调库落盘：走 review_cli 的生产构造路径 _cg（与 CLI 同一 autoflush），
+# 随后裸 add 两条（无任何显式 flush）——覆盖 review_decide 之外的写入形态。
+cg = review_cli._cg(argparse.Namespace(root=sys.argv[1]))
+sys.stderr.write("staged=0 autoflush=%d\n" % cg.autoflush)
+cg.add("vis-node-1", "P1b 可见性守卫节点一：kill 形态落账。", layer="knowledge",
+       tags=["vis:p1b"])
+cg.add("vis-node-2", "P1b 可见性守卫节点二：kill 形态落账。", layer="knowledge",
+       tags=["vis:p1b"])
+os._exit(0)                     # 硬退：close / atexit 一律不执行（模拟被杀）
+'''
+
+READ_CHILD = r'''
+import sys
+sys.path.insert(0, sys.argv[2])
+from md_cg.mdcos import MdCGSecure
+from md_cg.security import Principal
+p = Principal(actor="vis-reader", clearance="internal", can_write=True,
+              can_admin=True, role="designer", auth_mode="test")
+cg = MdCGSecure(sys.argv[1], principal=p)
+ids = sys.argv[3].split(",")
+print("READ " + " ".join("1" if cg.get(nid) is not None else "0" for nid in ids))
+'''
+
+
+def check(name, cond, detail=""):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  [PASS] {name}" + (f"  · {detail}" if detail else ""))
+    else:
+        FAIL += 1
+        FAILS.append(name)
+        print(f"  [FAIL] {name}  · {detail}")
+
+
+def _child_env(extra=None):
+    """子进程环境：哑密钥 + UTF-8 + PYTHONPATH 指向本仓（纪律 15）。"""
+    env = dict(os.environ)
+    env["MDCG_MASTER_KEY"] = DUMMY_KEY
+    env["PYTHONUTF8"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    env["PYTHONPATH"] = REPO + os.pathsep + env.get("PYTHONPATH", "")
+    env.update(extra or {})
+    return env
+
+
+def _run_cli(root, argv):
+    """跑一次 review_cli（包内入口 python -m md_cg.review_cli，真实在役入口）。"""
+    return subprocess.run(
+        [sys.executable, "-X", "utf8", "-m", "md_cg.review_cli"] + argv,
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+        env=_child_env(), cwd=REPO)
+
+
+def _spawn(code, root, arg3=""):
+    """独立子进程跑一段内嵌脚本（进程 A' 杀退形态 / 进程 B 全新读面）。"""
+    return subprocess.run(
+        [sys.executable, "-X", "utf8", "-c", code, root, REPO, arg3],
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+        env=_child_env())
+
+
+def _propose(root, nid, content):
+    """以原始写入者身份入队一条提案（复刻 DSH 端 agent 形态）。"""
+    cg = MdCGSecure(root, principal=Principal(
+        actor="dsh-memory", clearance="internal", can_write=True,
+        can_admin=False, role="recorder", session="sess_writer_orig"))
+    try:
+        return cg.propose(nid, content, layer="knowledge", tags=["vis:p1b"])
+    finally:
+        cg.close()
+
+
+def _log_ids(root):
+    """读盘面分片日志的记录 id 集（落账契约的观察点）。"""
+    log_dir = os.path.join(root, "_index_log")
+    if not os.path.isdir(log_dir):
+        return None                     # 目录不存在 = 一条都没落过
+    return {rec.get("id") for rec in ShardedLog.read_all(log_dir)
+            if rec.get("id")}
+
+
+def main():
+    roots = []
+    try:
+        # ---------- ① 真实在役入口：review_cli accept → 进程 B 读 ----------
+        print("\n【①】subprocess 跑 review_cli accept（正常完成）→ 进程 B 读")
+        root_1 = tempfile.mkdtemp(prefix="clivis_1_")
+        roots.append(root_1)
+        pid = _propose(root_1, "vis-acc-node",
+                       "P1b 可见性守卫：accept 落盘后其它进程立即可见。")
+        r = _run_cli(root_1, ["accept", pid, "--root", root_1,
+                              "--reason", "可见性守卫"])
+        check("review_cli accept 退出码 0", r.returncode == 0,
+              (r.stdout or r.stderr or "")[:200])
+        b = _spawn(READ_CHILD, root_1, "vis-acc-node")   # 全新子进程 _load_index+read
+        m = re.search(r"READ (\d)", b.stdout or "")
+        check("进程 B 读回业务节点 vis-acc-node 可见",
+              bool(m) and m.group(1) == "1",
+              (b.stdout or b.stderr or "")[:200])
+        pa = MdCGSecure(root_1, principal=Principal(
+            actor="vis-reader", clearance="internal", can_write=True,
+            can_admin=True, role="designer", auth_mode="test"))
+        try:
+            recs = pa.review_records(pid)
+        finally:
+            pa.close()
+        check("进程 B 侧审计记录节点可见（review_records 命中 1 条）",
+              len(recs) == 1, str(recs))
+
+        # ---------- ②③ kill 形态：调库落盘后 os._exit → 落账契约 + 读 ----------
+        print("\n【②③】进程 A' 调库落 2 条即 os._exit（模拟被杀）→ 落账契约 + 进程 B 读")
+        root_2 = tempfile.mkdtemp(prefix="clivis_2_")
+        roots.append(root_2)
+        a = _spawn(KILL_CHILD, root_2)
+        check("进程 A' 经生产构造 _cg（autoflush=1 回显）",
+              a.returncode == 0 and "autoflush=1" in (a.stderr or ""),
+              (a.stderr or "")[:200])
+        ids = _log_ids(root_2)
+        check("③ 落账契约：A' 被杀退出后 _index_log 已含全部 2 条写入记录"
+              "（autoflush=1 写毕即落日志；修复前 autoflush=64 未达阈值=红）",
+              ids is not None and {"vis-node-1", "vis-node-2"} <= ids,
+              "log_ids=%s" % sorted(ids or []))
+        b2 = _spawn(READ_CHILD, root_2, "vis-node-1,vis-node-2")   # 全新子进程读
+        m2 = re.search(r"READ (\d) (\d)", b2.stdout or "")
+        check("② 进程 B 读回 kill 形态的两条节点均可见",
+              bool(m2) and m2.group(1) == "1" and m2.group(2) == "1",
+              (b2.stdout or b2.stderr or "")[:200])
+
+        # ---------- ④ 同病工具面：三处同款补 autoflush=1 ----------
+        print("\n【④】同病工具面 autoflush=1")
+        cg_rv = None
+        try:
+            from . import review_cli as _rv
+            cg_rv = _rv._cg(argparse.Namespace(root=root_1))
+            check("review_cli._cg 构造 autoflush==1", cg_rv.autoflush == 1,
+                  str(cg_rv.autoflush))
+        finally:
+            if cg_rv is not None:
+                cg_rv.close()
+        from . import evidence as _ev
+        cg_ev = _ev._open_cg(root_1)
+        try:
+            check("evidence._open_cg 构造 autoflush==1", cg_ev.autoflush == 1,
+                  str(cg_ev.autoflush))
+        finally:
+            cg_ev.close()
+        for rel, anchor in (
+                ("scripts/linkref_backfill.py",
+                 "cg = MdCGSecure(a.root, principal=p, autoflush=1)"),
+                ("scripts/migrate_restricted.py", None)):
+            with open(os.path.join(REPO, rel), encoding="utf-8") as f:
+                src = f.read()
+            if anchor is not None:
+                ok = anchor in src
+            else:
+                # migrate_restricted 构造跨多行：断言构造语句带 autoflush=1
+                ok = re.search(r"MdCGSecure\([^)]*?auth_mode=\"test\"\), "
+                               r"autoflush=1\)", src, re.S) is not None
+            check("%s 构造语句带 autoflush=1（源级断言）" % rel, ok)
+    finally:
+        for r_ in roots:
+            shutil.rmtree(r_, ignore_errors=True)
+
+    print("\n" + "=" * 64)
+    print(f"PASS={PASS}  FAIL={FAIL}")
+    if FAILS:
+        print("失败项：" + "；".join(FAILS))
+    return 0 if FAIL == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/test_review_conformance.py

@@ -204,7 +204,14 @@ def main():
         pids = []
         for p in procs:
             out, _err = p.communicate(timeout=120)
-            pids.append(json.loads(out.strip()))
+            try:
+                pids.append(json.loads(out.strip()))
+            except ValueError:
+                # N170 诊断增强：worker 崩溃时 stdout 为空，裸 json.loads 只会
+                # 报 JSONDecodeError 盲盒——把 returncode/stderr 带出来定位。
+                raise AssertionError(
+                    "worker propose 输出非 JSON（rc=%s）stderr=%s"
+                    % (p.returncode, (_err or "")[-500:])) from None
         check("4 进程返回同一 pid", len(set(pids)) == 1, str(pids))
         inbox2 = os.path.join(root2, "hippocampus", "inbox.jsonl")
         with open(inbox2, encoding="utf-8") as f:
@@ -269,8 +276,19 @@ def main():
         outs = []
         for p in procs:
             out, _err = p.communicate(timeout=180)
+            if not out.strip():
+                # N170 诊断增强：空输出先亮 worker 现场（rc/stderr），不再
+                # 留给下方 json.loads 一个盲盒崩溃。
+                print("  [DIAG] decide worker rc=%s stderr=%s"
+                      % (p.returncode, (_err or "")[-500:]))
             outs.append(out.strip())
-        check("4 项裁决全部成功", all(json.loads(o).get("ok") for o in outs),
+        douts = []
+        for o in outs:
+            try:
+                douts.append(json.loads(o))
+            except ValueError:
+                douts.append({"ok": False})
+        check("4 项裁决全部成功", all(d.get("ok") for d in douts),
               str([o[:40] for o in outs]))
         drecs = cg3.decisions()
         check("decisions 读回恰好 4 条（无交错丢失）", len(drecs) == 4,
@@ -305,7 +323,7 @@ def main():
 
         def _neg_n():
             """负记忆条目数（rejected 层）——NOOP 不得增加它。"""
-            return sum(1 for e in cg5.index["nodes"].values()
+            return sum(1 for e in list(cg5.index["nodes"].values())
                        if (e.get("layer") or "") == "rejected")
 
         nb = _neg_n()

package/md_cg/test_security_audit_v21.py

@@ -224,11 +224,11 @@ def v21_8_sensitive_family():
              "service-account.json"]
     for fn in leaks:
         p = os.path.join(base, fn)
-        open(p, "w").close()
+        open(p, "w", encoding="utf-8").close()
         check(f"  拒读：{fn}", m._sensitive_read(p) is not None)
     for fn in ("notes.md", "readme.md", "data.json"):
         p = os.path.join(base, fn)
-        open(p, "w").close()
+        open(p, "w", encoding="utf-8").close()
         check(f"  不误伤：{fn}", m._sensitive_read(p) is None)
 
 

package/md_cg/test_server_version.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+"""test_server_version.py · SERVER_VERSION 与包版本联动守卫（issue #42）
+
+根因：md_cg/mcp_server.py 与 hive/hive_mcp/mcp_server.py 的 SERVER_VERSION
+硬编码 "0.1.0"，从未随发版联动——MCP 握手 serverInfo.version 向客户端自报
+假版本（外部用户实测：包 0.5.1 握手自报 0.1.0）。
+修复：SERVER_VERSION 改为 _package_version() 动态读包根 package.json。
+
+守卫断言：
+  ① md_cg.SERVER_VERSION == package.json 的 version（动态联动）
+  ② hive_mcp.SERVER_VERSION == 同一 package.json version（同族同源）
+  ③ 两值 != "0.1.0"（防回退硬编码——当前发布版本必非 0.1.0）
+  ④ _package_version 对坏路径回落 "0.1.0" 不抛（保底契约）
+"""
+import json
+import os
+import sys
+import unittest.mock as mock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+PASS = 0
+FAIL = 0
+
+
+def check(name, cond, detail=""):
+    global PASS, FAIL
+    if cond:
+        PASS += 1
+        print(f"  [ok] {name}")
+    else:
+        FAIL += 1
+        print(f"  [✘] {name}  {detail}")
+
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+with open(os.path.join(ROOT, "package.json"), encoding="utf-8") as f:
+    PKG_VERSION = json.load(f).get("version")
+
+print(f"== 包版本基准: {PKG_VERSION} ==")
+
+# ①② 动态联动
+from md_cg import mcp_server as mdcg_server  # noqa: E402
+from hive.hive_mcp import mcp_server as hive_server  # noqa: E402
+
+check("① md_cg SERVER_VERSION == package.json version",
+      mdcg_server.SERVER_VERSION == PKG_VERSION,
+      f"got {mdcg_server.SERVER_VERSION!r} want {PKG_VERSION!r}")
+check("② hive SERVER_VERSION == package.json version",
+      hive_server.SERVER_VERSION == PKG_VERSION,
+      f"got {hive_server.SERVER_VERSION!r} want {PKG_VERSION!r}")
+
+# ③ 防硬编码回退（issue #42 的 0.1.0 即硬编码脱节形态）
+check("③ 两值均非硬编码 0.1.0",
+      mdcg_server.SERVER_VERSION != "0.1.0" and hive_server.SERVER_VERSION != "0.1.0",
+      "出现 0.1.0 说明动态读取失效回退")
+
+# ④ 回落保底契约：读 package.json 失败 → "0.1.0" 不抛（保底不阻塞启动）
+try:
+    with mock.patch("builtins.open", side_effect=OSError("deny")):
+        v = mdcg_server._package_version()
+    check("④ _package_version 读取失败回落 0.1.0 不抛", v == "0.1.0", f"got {v!r}")
+except Exception as e:  # noqa: BLE001
+    check("④ _package_version 读取失败回落 0.1.0 不抛", False, f"raised {e!r}")
+
+print(f"== 结果: {PASS} 通过 / {FAIL} 失败 ==")
+sys.exit(1 if FAIL else 0)

package/md_cg/test_srcindex.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+"""真源索引契约层守卫（P0）：通用层覆盖任意文件 / 细化层仅可读文本 / 伴随文本挂通用层 / 回读逐字节。
+
+判据姿态（P0 两次踩坑的产物，勿简化回「猜粒度」）：
+  · **不猜提取器粒度**：细化层单位数与 `docindex.extract` 条数**平权**（units == extract + 1），
+    H1 节合并、过短节并入等语义归提取器，本层只保证「它切几节我就几条」；
+  · **哈希单一实现**：行区间哈希委托 `codeindex.region_hash`（sha1 前 12 位）；本模块自写第二份
+    的行为已被 5b/5c 抓出并删除——两处算法会让漂移检测永远 hash_match=True；
+  · **伴随文本挂通用层**：媒体不进可读文本分支，挂错层等于废掉多模态语义通道（6b 抓出）。
+
+实验纪律：全程 `tempfile` 临时目录 + 合成件（含**假魔数**的合成二进制，绝不用真实媒体/私有数据）；
+不写任何库面、不碰在役库、不出网。运行：退出码 0 = 全绿。
+"""
+from __future__ import annotations
+
+import io
+import os
+import shutil
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg import codeindex                 # noqa: E402
+from md_cg import docindex                  # noqa: E402
+from md_cg import srcindex as S             # noqa: E402
+
+PASS = FAIL = 0
+FAILS = []
+
+
+def ck(cid: str, ok: bool, detail: str = "") -> None:
+    global PASS, FAIL
+    if ok:
+        PASS += 1
+    else:
+        FAIL += 1
+        FAILS.append("%s %s" % (cid, detail))
+    print("  %s %s%s" % ("OK  " if ok else "FAIL", cid, "" if ok else "  " + detail))
+
+
+def w(path: str, data) -> str:
+    if isinstance(data, bytes):
+        with open(path, "wb") as f:
+            f.write(data)
+    else:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(data)
+    return path
+
+
+DOC = "\n".join([
+    "# 合成文档标题", "", "这是一段引言。", "",
+    "## 小节一", "", "小节一的正文，足够长以通过提取器的最小长度判断。", "",
+    "## 小节二", "", "小节二的正文，同样足够长，并带一行说明。", "",
+    "## 小节三", "", "小节三的正文。",
+])
+CCG = "\n".join([
+    "# 功能名：合成样例", "# 生效条件：仅用于 P0 契约层守卫；合成件、非真实数据",
+    "## 小节一", "正文一",
+])
+
+
+def main() -> int:
+    tmp = tempfile.mkdtemp(prefix="p0_srcindex_")
+    try:
+        md = w(os.path.join(tmp, "说明.md"), DOC)
+        ccg = w(os.path.join(tmp, "带条件.md"), CCG)
+        png = w(os.path.join(tmp, "pic.png"), b"\x89PNG\r\n\x1a\n" + b"\x00\x01\x02" * 40)
+        w(os.path.join(tmp, "pic.md"), "# pic 简介\n\n这是伴随文本（sidecar）")
+        mp4 = w(os.path.join(tmp, "clip.mp4"), b"\x00\x00\x00\x18ftypmp42" + b"\x00" * 64)
+        raw = w(os.path.join(tmp, "blob.dat"), bytes(range(256)) * 4)
+        weird = w(os.path.join(tmp, "t.txt"), b"abc\x00def")            # NUL ⇒ 不可读
+        fake = w(os.path.join(tmp, "disguised.txt"), b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+        empty = w(os.path.join(tmp, "empty.md"), "")
+
+        # ① 通用层：任意文件都有 ≥1 条 whole 单位（含空文件/不可读二进制）
+        for label, p in (("md", md), ("png", png), ("mp4", mp4), ("raw", raw),
+                         ("nul", weird), ("empty", empty)):
+            us = S.units(p)
+            ck("1a[%s] 通用层恒在" % label,
+               bool(us) and us[0]["span"]["unit"] == "whole" and bool(us[0]["span_hash"]),
+               "units=%d" % len(us))
+
+        # ② 细化层：与 docindex.extract 平权（不猜粒度）
+        for label, p in (("md", md), ("ccg", ccg)):
+            text = io.open(p, encoding="utf-8").read()
+            want = len(docindex.extract(text, path=p)) + 1
+            got = len(S.units(p))
+            ck("2a[%s] 单位数 == extract+1" % label, got == want, "units=%d want=%d" % (got, want))
+        ck("2b[png] 无细化层", all(u["span"]["unit"] == "whole" for u in S.units(png)))
+        ck("2c[NUL 文本] 判不可读、不细化",
+           all(u["span"]["unit"] == "whole" for u in S.units(weird)))
+        ck("2d[空文件] 不细化且不抛", len(S.units(empty)) == 1)
+
+        # ③ 类型判据：魔数优先于扩展名；未知类型不拒
+        ck("3a[魔数优先] .txt 内容为 PNG ⇒ image/png",
+           S.sniff_type(fake) == "image/png", S.sniff_type(fake))
+        ck("3b[扩展名兜底] .md ⇒ text/markdown", S.sniff_type(md) == "text/markdown")
+        ck("3c[未知不拒] .dat ⇒ octet-stream",
+           S.sniff_type(raw) == "application/octet-stream", S.sniff_type(raw))
+
+        # ④ 哈希判别力：改 1 字节 ⇒ file_hash 变；旧单位回读 hash_match=False
+        u0 = S.units(md)[0]
+        h0 = u0["src"]["file_hash"]
+        w(md, DOC.replace("这是一段引言。", "这是一段引言！"))
+        u1 = S.units(md)[0]
+        ck("4a[1 字节改判] file_hash 变", h0 != u1["src"]["file_hash"])
+        ck("4b[陈旧检出] 旧单位回读 hash_match=False",
+           S.read_unit(u0).get("hash_match") is False)
+        ck("4c[新鲜一致] 新单位回读 hash_match=True",
+           S.read_unit(u1).get("hash_match") is True)
+
+        # ⑤ 行区间回读逐字节 + 与 codeindex.region_hash 单一实现
+        lu = [u for u in S.units(md) if u["span"]["unit"] == "line"][0]
+        got = S.read_unit(lu)
+        lines = io.open(md, encoding="utf-8").read().split("\n")
+        want_text = "\n".join(lines[lu["span"]["start"] - 1:lu["span"]["end"]])
+        ck("5a[区间逐字节]", got.get("text") == want_text, repr(got.get("text"))[:60])
+        ck("5b[区间哈希一致]", got.get("hash_match") is True)
+        ck("5c[哈希单一实现] 委托 codeindex.region_hash",
+           codeindex.region_hash(lines, lu["span"]["start"], lu["span"]["end"])
+           == S.region_hash("\n".join(lines), lu["span"]["start"], lu["span"]["end"])
+           == got["hash"])
+
+        # ⑥ 伴随文本挂**通用层**（媒体条目的语义通道）
+        comps = S.companions(png)
+        u_png = S.units(png)[0]
+        ck("6a[sidecar 发现]", any(c["kind"] == "sidecar" for c in comps),
+           str([c["name"] for c in comps]))
+        ck("6b[挂进通用层] media 条目 text_view 含伴随文本且带 companions",
+           "伴随文本" in u_png["text_view"] and bool(u_png.get("companions")))
+
+        # ⑦ 未实现 locator 必须显式不静默
+        bad = S.read_unit({"src": {"path": md}, "span": {"unit": "time", "t0": 0, "t1": 1}})
+        ck("7a[time 显式不支持]", bad.get("ok") is False and "time" in bad.get("error", ""),
+           str(bad)[:80])
+
+        # ⑧ CCG 条件面进入细化层（且与该文件的 CCG 行相关）
+        ccg_units = S.units(ccg)
+        ck("8a[条件面非空]", any(u.get("condition_space") for u in ccg_units),
+           str([bool(u.get("condition_space")) for u in ccg_units]))
+        ck("8b[CCG 行落在细化层]",
+           any("生效条件" in (u.get("text_view") or "") or
+               "生效条件" in str(u.get("condition_space"))
+               for u in ccg_units if u["span"]["unit"] == "line"),
+           str([u.get("text_view") for u in ccg_units if u["span"]["unit"] == "line"])[:90])
+
+        # ⑨ 能力自陈与实现一致（契约漂移守卫）
+        cap = S.capability()
+        ck("9a[units 自陈]", tuple(cap["units"]) == S.UNITS == ("whole", "line"))
+        ck("9b[未实现项自陈]", set(cap["not_implemented"]) == {"time", "region", "byte"})
+        ck("9c[零依赖/不写状态]", cap["deps"] == [] and cap["writes_state"] is False)
+
+        # ⑩ 不存在路径：fail-closed 抛，而不是静默造条目
+        try:
+            S.units(os.path.join(tmp, "不存在.bin"))
+            ck("10a[不存在 fail-closed]", False, "未抛")
+        except OSError:
+            ck("10a[不存在 fail-closed]", True)
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    print("\n结果：PASS %d / FAIL %d" % (PASS, FAIL))
+    if FAILS:
+        print("失败项：" + "；".join(FAILS))
+    return 0 if FAIL == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())