@furongjun1999/dsh-memory 0.4.11 → 0.5.1

package/md_cg/interop.py

@@ -0,0 +1,338 @@
+# -*- coding: utf-8 -*-
+"""互验工具库（批次10，互验定稿 §7 的 python 落地）。
+
+三断言（§7.5）：
+  A1  verifier_instance != subject_instance          —— 是两个人
+  A2  verifier_fingerprint != subject_fingerprint    —— 指纹不同
+  A3  verifier_fingerprint == 本轮冻结值             —— 看同一把尺子（承重墙）
+任一不成立 → 验证结论作废。
+
+verdict 脱敏硬门禁（§7.3）：入库即公开，只允许结构化事实（指纹/断言/计数/
+SHA/迭代 id/时间戳/符号化路径）；禁止 spec 正文/prompt/result.content/
+API 信息/本机绝对路径——违规抛 InteropSanityError。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# 判据面实现（2026-09-24 修复）：包内模块；出货包不含 scripts/，且 DSH 沙箱
+# 禁子进程管道，故**进程内**调用。MDCG_JUDGMENT_MANIFEST 可指向外部实现文件
+# （自定义判据面时用；按文件路径加载，需提供 collect()/digest()）。
+MANIFEST_ENV = "MDCG_JUDGMENT_MANIFEST"
+
+_FORBIDDEN_RES = [
+    (re.compile(r"[A-Za-z]:[\\\\/]"), "本机绝对路径（盘符）"),
+    (re.compile(r"/Users/|/home/"), "本机绝对路径（unix 家目录）"),
+    (re.compile(r"https?://[^\s\"']*(api|key|token)", re.I), "API 端点/凭证 URL"),
+    (re.compile(r"sk[-_][A-Za-z0-9]{8,}"), "疑似 API key"),
+    # issue #37 J5 扩面（纵深防御的真实宽度对齐声明）：
+    (re.compile(r"\\\\[A-Za-z0-9_$.-]+\\"), "本机绝对路径（UNC）"),
+    (re.compile(r"/Volumes/"), "本机绝对路径（macOS 挂载）"),
+    (re.compile(r"(?:^|[\s\"'(=,])/(?:etc|usr|var|opt|root|tmp|private)/"),
+     "本机绝对路径（unix）"),
+    (re.compile(r"(?:^|[\s\"'(=,])~/"), "家目录缩写 ~"),
+    (re.compile(r"\$HOME"), "家目录变量"),
+    (re.compile(r"\b(?:ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}"
+                r"|github_pat_[A-Za-z0-9_]{20,}|AIza[A-Za-z0-9_-]{20,}"
+                r"|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,})"),
+     "公开密钥形态"),
+    (re.compile(r"Bearer\s+[A-Za-z0-9._~+/=-]{20,}"), "Bearer 凭证"),
+    (re.compile(r"\b(?:user_prompt|result\.content|spec_body|system_prompt)"
+                r"\b\s*[::=]", re.I), "prompt/content 文本形态"),
+]
+_FORBIDDEN_KEYS = {"prompt", "content", "spec", "api_key", "base", "model",
+                   "system_prompt", "user_prompt", "content_head"}
+
+
+class InteropSanityError(ValueError):
+    """verdict 脱敏门禁违规（入库即公开，违规内容不得落盘）。"""
+
+
+def _manifest_module():
+    """取判据面实现模块，优先级：
+
+      ① `MDCG_JUDGMENT_MANIFEST` 外部实现（自定义判据面）
+      ② **源码树的 `scripts/judgment_manifest.py`**——验证器侧（hive runner /
+         serve 心跳）用它算 digest，A3 要求两侧**同一份实现**；源码树在时
+         必须用它，否则两侧判据面构成一旦分叉，digest 必不相等（A3 全红）。
+      ③ 包内 `md_cg/judgment_manifest.py`——出货包不含 `scripts/`，
+         安装态回落此处（构成与 ② 同步维护）。
+    """
+    override = (os.environ.get(MANIFEST_ENV) or "").strip()
+    if override:
+        if not os.path.isfile(override):
+            raise RuntimeError(
+                f"{MANIFEST_ENV} 指向的文件不存在：{override}")
+        return _load_manifest_file(override)
+    src = os.path.join(HERE, "scripts", "judgment_manifest.py")
+    if os.path.isfile(src):
+        return _load_manifest_file(src)
+    from . import judgment_manifest as mod
+    return mod
+
+
+def _load_manifest_file(path):
+    """按路径加载判据面实现（需提供 collect()/digest()）。"""
+    import importlib.util
+    spec = importlib.util.spec_from_file_location(
+        "_mdcg_judgment_manifest_ext", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    for fn in ("collect", "digest"):
+        if not callable(getattr(mod, fn, None)):
+            raise RuntimeError(f"{path} 不是合法判据面实现（缺 {fn}()）")
+    return mod
+
+
+def _manifest(action: str):
+    """判据面清单/指纹（进程内，无子进程）。
+
+    历史（2026-09-24 修复）：0.4.x 以 `subprocess.run([python, scripts/
+    judgment_manifest.py, ...])` 取清单——出货包不含 scripts/，安装态必抛
+    FileNotFoundError（判据面是运行时依赖，不是可选工具）；且 DSH 文件沙箱
+    禁止子进程管道（CreatePipe → WinError 5），该写法在受限宿主里连空库都跑不动。
+    现改为直接调用包内模块，语义（PATTERNS/排序/digest 算法）与原脚本逐字一致。
+    """
+    mod = _manifest_module()
+    manifest = mod.collect()
+    if action == "--digest":
+        return mod.digest(manifest)
+    return json.dumps(manifest, ensure_ascii=False)
+
+
+def freeze(iter_id: str, out_dir: str = None) -> dict:
+    """第 0 步：记录本轮判据面冻结凭证（A3 的比对基准）。
+
+    out_dir 缺省 = hive/interop/<iter_id>/；显式传入时视为最终目录（不拼 iter_id）。
+    注意（issue #37 J6）：verify_runner 固定读 repo 标准位置——显式 out_dir
+    冻结的凭证**不被 runner 识别**（仅适用于单测/离线留痕），此处显式警告。
+    """
+    if out_dir is not None:
+        sys.stderr.write("[interop] 警告：显式 out_dir 的冻结凭证不被 "
+                         "verify_runner 识别（runner 固定读 hive/interop/"
+                         "<iter_id>/frozen.json）——仅适用于单测/离线留痕\n")
+    manifest = json.loads(_manifest(""))
+    credential = {
+        "iter_id": iter_id,
+        "frozen_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "digest": _manifest("--digest"),
+        "files": manifest["files"],
+        # 判据面是源码树概念：安装态（出货包）只有 md_cg/test_*.py 一组可得。
+        # 缺失组随凭证落盘 → A3 两侧布局不一致时可判因，而不是只见「指纹不符」。
+        "missing_patterns": manifest.get("missing_patterns") or [],
+    }
+    if out_dir is None:
+        out_dir = os.path.join(HERE, "hive", "interop", iter_id)
+    os.makedirs(out_dir, exist_ok=True)
+    fp = os.path.join(out_dir, "frozen.json")
+    with open(fp, "w", encoding="utf-8") as f:
+        json.dump(credential, f, ensure_ascii=False, indent=2)
+    credential["_path"] = fp
+    return credential
+
+
+def assert_a3(frozen: dict, verifier_fingerprint: str) -> dict:
+    """A3（承重墙）：验证者声明的判据面指纹 == 本轮冻结值。"""
+    ok = verifier_fingerprint == frozen.get("digest")
+    return {"assertion": "A3", "ok": ok,
+            "frozen": frozen.get("digest"), "actual": verifier_fingerprint}
+
+
+def assert_a1(verifier_instance: str, subject_instance: str) -> dict:
+    return {"assertion": "A1",
+            "ok": bool(verifier_instance and subject_instance
+                       and verifier_instance != subject_instance),
+            "verifier": verifier_instance, "subject": subject_instance}
+
+
+def assert_a2(verifier_fingerprint: str, subject_fingerprint: str) -> dict:
+    """A2（辅助断言）：两实例指纹不同。**subject_fp 为派发方自报值，本断言不核验
+    其真伪**（issue #37 J2：复用 #27 的 self-reported 分层标注）——设计定稿
+    （§7.5）明示 A1/A2 起两进程即自动成立、不构成保证，防线在 A3（冻结值）。
+    """
+    ok = bool(verifier_fingerprint and subject_fingerprint
+              and verifier_fingerprint != subject_fingerprint)
+    return {"assertion": "A2", "ok": ok,
+            "verifier": verifier_fingerprint, "subject": subject_fingerprint,
+            "subject_fp_source": "self-reported"}
+
+
+def sanity_check_verdict(verdict: dict) -> None:
+    """脱敏硬门禁：递归扫描 verdict 全部键与字符串值，违规即抛。"""
+    def walk(obj, path="$"):
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if str(k).lower() in _FORBIDDEN_KEYS:
+                    raise InteropSanityError(
+                        f"{path}.{k}: 禁止字段（spec 正文/prompt/API 信息不得入库）")
+                walk(v, f"{path}.{k}")
+        elif isinstance(obj, list):
+            for i, v in enumerate(obj):
+                walk(v, f"{path}[{i}]")
+        elif isinstance(obj, str):
+            for i, (pat, why) in enumerate(_FORBIDDEN_RES):
+                if pat.search(obj):
+                    raise InteropSanityError(
+                        f"{path}: 疑似 {why}（命中 {i} 号规则）")
+
+    walk(verdict)
+
+
+# issue #37 J5：黑名单天然漏——补「字符集 + 形状」白名单校验（与本仓
+# 「能机械判的绝不猜」纪律同源）。verdict 的结构是固定契约，任何越权字段
+# 或坏形状（指纹非十六进制、计数非整数、枚举外值）在落盘前即拒。
+_ALLOWED_TOP = {"iter_id", "verifier_instance", "verifier_fingerprint",
+                "subject_instance", "subject_fingerprint", "suite_origin",
+                "frozen_at", "verdict", "passed", "failed", "details",
+                "valid", "assertions_ok", "failure_reason"}
+_SHAPE_FP = re.compile(r"[0-9a-f]{12,64}")
+
+
+def shape_check_verdict(verdict: dict) -> None:
+    """形状白名单：顶层字段集 ⊆ 契约集；指纹=12-64 位十六进制；枚举与计数
+    类型受检。与 sanity_check_verdict（脱敏黑名单）互补，构成双门禁。"""
+    extra = set(verdict) - _ALLOWED_TOP
+    if extra:
+        raise InteropSanityError(f"未知顶层字段（越权）: {sorted(extra)}")
+    for k in ("verifier_fingerprint", "subject_fingerprint"):
+        v = verdict.get(k)
+        if v and not _SHAPE_FP.fullmatch(str(v)):
+            raise InteropSanityError(
+                f"{k}: 非指纹形状（期望 12-64 位十六进制）: {str(v)[:24]!r}")
+    if verdict.get("verdict") not in ("pass", "fail"):
+        raise InteropSanityError(
+            f"verdict 非法枚举: {verdict.get('verdict')!r}")
+    if verdict.get("failure_reason") not in (
+            None, "suite_failed", "assertions_failed", "both"):
+        raise InteropSanityError(
+            f"failure_reason 非法枚举: {verdict.get('failure_reason')!r}")
+    for k in ("passed", "failed"):
+        v = verdict.get(k)
+        if not isinstance(v, int) or isinstance(v, bool) or v < 0:
+            raise InteropSanityError(f"{k}: 非非负整数: {v!r}")
+
+
+def make_verdict(iter_id: str, verifier_instance: str, verifier_fingerprint: str,
+                 subject_instance: str, subject_fingerprint: str,
+                 suite_origin: str, frozen_at: str, verdict: str,
+                 passed: int, failed: int, details=None,
+                 suite_ok: bool = None) -> dict:
+    """§7.3 契约构造 + 脱敏门禁（违规即抛，绝不落盘）。
+
+    批次 23（v20 API 一致性）：产出**直接含门禁 `_REQUIRED` 全部字段**
+    （valid/assertions_ok/failure_reason，J1/J3 语义与
+    `verify_runner._compose_semantics` 同口径）——此前 make_verdict 不产
+    这三字段、只有 verify_runner 写盘前补齐，直连 make_verdict →
+    write_verdict_to_repo 会被门禁判 exit 3（形状非法）。suite_ok 可选：
+    调用方知道套件面成败时传入以精确 failure_reason；不传则按可推导部分
+    诚实标注（failed>0 → assertions_failed），不编造 suite 面。
+    """
+    valid = (verdict == "pass")
+    assertions_ok = (int(failed) == 0)
+    if valid and assertions_ok:
+        failure_reason = None
+    elif assertions_ok:
+        failure_reason = "suite_failed"
+    elif suite_ok is False:
+        failure_reason = "both"
+    else:
+        # failed>0：断言面确定败；suite 面未知（None）或已知真 → 枚举取断言面
+        failure_reason = "assertions_failed"
+    v = {
+        "iter_id": iter_id,
+        "verifier_instance": verifier_instance,
+        "verifier_fingerprint": verifier_fingerprint,
+        "subject_instance": subject_instance,
+        "subject_fingerprint": subject_fingerprint,
+        "suite_origin": suite_origin,
+        "frozen_at": frozen_at,
+        "verdict": verdict,
+        "valid": valid,
+        "assertions_ok": assertions_ok,
+        "failure_reason": failure_reason,
+        "passed": passed,
+        "failed": failed,
+        "details": details or [],
+    }
+    sanity_check_verdict(v)
+    return v
+
+
+# ---------------------------------------------------------------- 批次11：时序原语
+
+def dispatch_verify_job(verifier_jobs_dir: str, iter_id: str,
+                        subject_fingerprint: str, timeout_s: int = 1800) -> dict:
+    """§7.4 步骤3（★非阻塞★）：把验证任务作为普通蜂巢 job 投到验证实例的
+    jobs 目录——文件协议即接口，写 spec.json 即完成投递，立即返回不等待
+    （进度靠验证实例心跳的 iter_id/progress 拉取，不阻塞轮询）。
+
+    subject_fingerprint 经 spec.env 传给验证执行器（主实例候选的判据面指纹，
+    A2 的比对输入）。
+    """
+    jobs = os.path.abspath(verifier_jobs_dir)
+    runner = os.path.join(HERE, "hive", "verify_runner.py")
+    spec = {
+        "model": "cmd",
+        "user_prompt": f"互验执行 iter={iter_id}",
+        "command": [sys.executable, runner, iter_id],
+        "timeout_s": max(5, min(3600, timeout_s)),
+        "env": {"SUBJECT_FP": subject_fingerprint, "ITER_ID": iter_id},
+    }
+    from .fsutil import ShardedLog  # noqa: F401  确认依赖在位
+    jd = os.path.join(jobs, f"h{int(time.time() * 1000)}_disp")
+    os.makedirs(jd, exist_ok=True)
+    with open(os.path.join(jd, "spec.json"), "w", encoding="utf-8") as f:
+        json.dump(spec, f, ensure_ascii=False)
+    with open(os.path.join(jd, "status.json"), "w", encoding="utf-8") as f:
+        json.dump({"state": "pending"}, f)
+    out = {"ok": True, "dispatched": jd, "iter_id": iter_id,
+           "note": "非阻塞投递完成——进度靠验证实例心跳拉取，不轮询不等待"}
+    # hive/ 是源码树子系统（出货包不含）：投递本身成功，但没有可执行 runner 时
+    # 消费端会静默失败 → 显式报警，不假装这一票能跑（2026-09-24 补齐）。
+    if not os.path.isfile(runner):
+        out["warning"] = (f"验证 runner 不存在：{runner}——投递已落盘，但本次"
+                          "验证不会被消费（hive/ 为源码树子系统，安装态需另行提供）")
+    return out
+
+
+def write_verdict_to_repo(verdict: dict, repo: str = HERE,
+                          do_commit: bool = False) -> dict:
+    """§7.3 留痕：verdict 写 hive/interop/<iter_id>/（受版本控制目录，
+    **不用** hive/jobs/——该目录 .gitignore 且含运行态）。
+
+    脱敏门禁在 make_verdict 已过；此处落盘前再过一次（纵深）——issue #37 J5
+    后为 sanity（脱敏黑名单）+ shape（形状白名单）双门禁。do_commit=True 时
+    git add+commit（**不自动 push**——推送由使用者/编排触发，§7.3 双清单
+    人工确认环节保留）。
+    """
+    sanity_check_verdict(verdict)
+    shape_check_verdict(verdict)
+    it = verdict.get("iter_id") or ""
+    if not re.fullmatch(r"[A-Za-z0-9_.-]{1,80}", it):
+        raise ValueError(f"iter_id 非法（入库路径组成部分）: {it!r}")
+    out_dir = os.path.join(repo, "hive", "interop", it)
+    os.makedirs(out_dir, exist_ok=True)
+    fp = os.path.join(out_dir, "verdict.json")
+    with open(fp, "w", encoding="utf-8") as f:
+        json.dump(verdict, f, ensure_ascii=False, indent=2)
+    out = {"ok": True, "path": fp}
+    if do_commit:
+        import subprocess
+        r1 = subprocess.run(["git", "add", os.path.relpath(fp, repo)],
+                            cwd=repo, capture_output=True, text=True,
+                            encoding="utf-8", errors="replace")
+        r2 = subprocess.run(
+            ["git", "commit", "-q", "-m",
+             f"interop(verifier): iter={it} verdict={verdict.get('verdict')} "
+             f"passed={verdict.get('passed')} failed={verdict.get('failed')}"],
+            cwd=repo, capture_output=True, text=True,
+            encoding="utf-8", errors="replace")
+        out["committed"] = r2.returncode == 0
+        if r2.returncode != 0:
+            out["commit_err"] = (r2.stderr or r1.stderr)[:200]
+    return out

package/md_cg/judgment_manifest.py

@@ -0,0 +1,177 @@
+# -*- coding: utf-8 -*-
+"""判据面清单生成器（批次8b，互验定稿 §7.6「机器可读清单未定义」缺口收口）。
+
+**本模块是 `scripts/judgment_manifest.py` 的包内等价实现**（2026-09-24 修复）：
+出货包 `files` 不含 `scripts/`，而 `md_cg/interop.py` 原先以子进程调用该脚本
+——安装态必抛 FileNotFoundError，且受限宿主（DSH 文件沙箱）禁子进程管道
+（CreatePipe → WinError 5）。判据面是**运行时依赖**，故搬进包内。
+
+⚠ **判据面构成必须与源码树逐条同源**（A3 的硬约束）：验证器侧（hive runner /
+hive serve 心跳）用的是 `scripts/judgment_manifest.py`，两侧 PATTERNS 一旦
+不同，digest 必不相等 → A3 红。因此：
+  ① 本文件的 PATTERNS / 排序 / digest 算法与 `scripts/` 版**逐字同步**
+     （含 issue #36 的七组构成）；
+  ② `md_cg/interop.py` **优先加载源码树的 `scripts/judgment_manifest.py`**，
+     只有它不在（安装态）才回落到本模块。
+
+判据面 = 验证实例 A3 断言（判据面文件集合 hash==冻结值）的覆盖对象。
+候选面 = hive/src/**（被验证的源码）。
+物理分离成立后：候选弱化判据面任一文件 → 判据面 hash 不变、候选面变化被
+判据面覆盖 → 弱化必红（zcode 外评 break#3 的结构性收口）。
+
+用法（包内入口）：
+  python -m md_cg.judgment_manifest                    # 输出 JSON（清单+sha256+分组计数）
+  python -m md_cg.judgment_manifest --digest           # 仅输出组合指纹（纯值，A3 输入）
+  python -m md_cg.judgment_manifest --check-coverage   # 覆盖完备性守卫（issue #36）
+  python -m md_cg.judgment_manifest --verify <冻结的manifest.json>
+
+清单组成（§7.6 定稿；issue #36 补齐「跑什么=冻结什么」同源）：
+  hive/tests/*.rs         Rust 侧承重断言（judgment_surface.rs）
+  hive/test_*.py          hive Python 测试套件
+  scripts/run_tests.py    全量测试入口
+  scripts/test_*.py       scripts 侧测试
+  md_cg/test_*.py         Python 侧测试套件
+  compiler/tests/*.py     compiler 测试
+  swarm/tests/*.py        swarm 测试
+
+安装态（出货包）只有 `md_cg/test_*.py` 一组可得——其余组命中数为 0，
+`missing_patterns` 显式随清单与冻结凭证落盘（不静默少算）；A3 两侧必须在
+同一种布局下取值，否则 digest 天然不等（见 `md_cg/interop.py` 的说明）。
+"""
+import hashlib
+import json
+import os
+import sys
+
+# 包内位置 = <插件根>/md_cg/judgment_manifest.py → 上溯两级回到插件根
+# （与 scripts/ 版的 os.path.dirname(dirname(__file__)) 同值）。
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+PATTERNS = [
+    ("hive/tests", "*.rs"),
+    ("hive", "test_*.py"),
+    ("scripts", "run_tests.py"),
+    ("scripts", "test_*.py"),
+    ("md_cg", "test_*.py"),
+    ("compiler/tests", "*.py"),
+    ("swarm/tests", "*.py"),
+]
+
+
+# 生效条件：无必需形参；遍历 PATTERNS 逐组取 HERE 下子目录中匹配的文件（目录不存在或零命中则 groups 计数为 0 且该组进 missing_patterns），按相对路径排序后返回 {"algorithm","groups","files","missing_patterns"}。
+def collect() -> dict:
+    """收集判据面清单（分组计数 + 缺失组显式上报）。"""
+    files = []
+    groups = {}
+    for sub, pat in PATTERNS:
+        base = os.path.join(HERE, sub)
+        n = 0
+        if os.path.isdir(base):
+            import fnmatch
+            for name in sorted(os.listdir(base)):
+                full = os.path.join(base, name)
+                if not os.path.isfile(full):
+                    continue
+                if fnmatch.fnmatch(name, pat):
+                    rel = os.path.relpath(full, HERE).replace("\\", "/")
+                    files.append(rel)
+                    n += 1
+        groups[f"{sub}/{pat}"] = n
+    files.sort()
+    out = {"algorithm": "sha256", "groups": groups, "files": [],
+           # 零命中组（目录不存在、或目录在但空）：安装态/裸 clone 的判据面不完整，
+           # 必须随清单可见——否则「少算」会被当成「判据面完好」。
+           "missing_patterns": sorted(k for k, v in groups.items() if not v)}
+    for rel in files:
+        with open(os.path.join(HERE, rel), "rb") as fh:
+            h = hashlib.sha256(fh.read()).hexdigest()
+        out["files"].append({"path": rel, "sha256": h})
+    return out
+
+
+# 生效条件：scripts/run_tests.py 在（源码树）时以 _discovered_files() 为唯一执行清单真源，逐文件判定是否落在冻结 PATTERNS 覆盖域内（域外=collect 永不收=漏冻）返回缺失列表；rt 不在（安装态）时返回 None——调用方须如实说明「无法核对」，不得当作通过。批次 23 域覆盖语义（与 scripts 版同口径，v20 D-36-1：集合差形式在 collect 超集下恒空=假牙）。
+def coverage_gap(manifest: dict):
+    """覆盖完备性守卫（issue #36）：「跑什么」⊆「冻结什么」。
+
+    批次 23 起与 `scripts/` 版同口径——**域覆盖判定**：每个 run_tests
+    会跑的文件必须落在冻结 PATTERNS 的覆盖域内（域外 = collect 永不收
+    → 不进判据指纹 → 漏冻）。v20 D-36-1：集合差形式在 collect 超集下
+    恒空（假牙）。安装态（run_tests 不在）返回 None——调用方须如实
+    说明「无法核对」，不得当作通过。
+    """
+    import fnmatch
+    import importlib.util
+    rt_path = os.path.join(HERE, "scripts", "run_tests.py")
+    if not os.path.isfile(rt_path):
+        return None
+    spec = importlib.util.spec_from_file_location("run_tests", rt_path)
+    rt = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(rt)
+    gap = []
+    for rel in rt._discovered_files():
+        rel = str(rel).replace("\\", "/")
+        if not any(fnmatch.fnmatch(rel, f"{sub}/{pat}")
+                   for sub, pat in PATTERNS):
+            gap.append(rel)
+    return sorted(gap)
+
+
+# 生效条件：manifest 含 "files"（每项 path/sha256）时返回 sha256("path:hash\n" 按清单序拼接)；files 为空时返回空串拼接结果（sha256 of ""）。
+def digest(manifest: dict) -> str:
+    """判据面组合指纹（批次10，A3/A2 的输入）：sha256("path:hash\\n" 按清单序拼接)。
+
+    服务端（hive serve 心跳 fingerprint）与验证器共用同一算法——清单变更
+    （新增/删除/任一文件改动）必改 digest，缺一不可。
+    """
+    lines = "".join(f"{f['path']}:{f['sha256']}\n" for f in manifest["files"])
+    return hashlib.sha256(lines.encode("utf-8")).hexdigest()
+
+
+# 生效条件：argv 为空时打印全量清单 JSON 并返回 0；--digest 打印指纹返回 0；--check-coverage 在源码树缺 run_tests.py 时打印 UNVERIFIABLE 返回 2、否则按缺口 PASS/FAIL 返回 0/1；--verify <path> 比对冻结清单 PASS/FAIL 返回 0/1。
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    manifest = collect()
+    if argv[:1] == ["--digest"]:
+        print(digest(manifest))
+        return 0
+    if argv[:1] == ["--check-coverage"]:
+        gap = coverage_gap(manifest)
+        if gap is None:
+            print(json.dumps({
+                "verdict": "UNVERIFIABLE",
+                "reason": "scripts/run_tests.py 不在（安装态）——覆盖完备性守卫"
+                          "属源码树门禁，本环境无法核对（不冒充通过）",
+                "groups": manifest["groups"],
+                "file_count": len(manifest["files"]),
+            }, ensure_ascii=False, indent=2))
+            return 2
+        print(json.dumps({
+            "verdict": "PASS" if not gap else "FAIL",
+            "missing": gap,
+            "groups": manifest["groups"],
+            "file_count": len(manifest["files"]),
+        }, ensure_ascii=False, indent=2))
+        return 0 if not gap else 1
+    if argv[:1] == ["--verify"]:
+        if len(argv) < 2:
+            print("用法：--verify <冻结的manifest.json>", file=sys.stderr)
+            return 2
+        with open(argv[1], encoding="utf-8") as fh:
+            frozen = json.load(fh)
+        cur = {f["path"]: f["sha256"] for f in manifest["files"]}
+        froz = {f["path"]: f["sha256"] for f in frozen["files"]}
+        added = sorted(set(cur) - set(froz))
+        removed = sorted(set(froz) - set(cur))
+        changed = sorted(p for p in set(cur) & set(froz) if cur[p] != froz[p])
+        ok = not (added or removed or changed)
+        print(json.dumps({
+            "verdict": "PASS" if ok else "FAIL",
+            "added": added, "removed": removed, "changed": changed,
+        }, ensure_ascii=False, indent=2))
+        return 0 if ok else 1
+    print(json.dumps(manifest, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())