@furongjun1999/dsh-memory 0.4.10 → 0.5.0

package/md_cg/evidence.py

@@ -1,581 +1,581 @@
-# -*- coding: utf-8 -*-
-"""跨节点证据存储（蜂群互联 v0.3）。
-
-攻 §9.1 盲区：`identity.infer_position` 只统计**本根**带 `subject:<id>` 标签的
-证据节点，跨节点时对端观测对本节点不可见。本模块给出最小可测的交换机制：
-
-  ① **节点名片**（card）——`node_id` / 根路径 / 版本状态 / 签名器公开信息；
-  ② **证据包**（pack）——从本根导出「我对某主体的观测」，**由本节点签名**；
-  ③ **导入**（import）——验签 → 落本根（带 `source:<node>` 标签）→ 可审计、可拒收。
-
-设计边界（承 D-1 / D-4）：
-
-  · 内核**不做密码学**：签名/验签一律经 `signer.sign_for / verify_for`，
-    跨节点证据要求子系统策略 `sign_on` 含 `evidence`（由智能体自决）；
-  · 内核**不保证全局共识**（0.0.3 局部不可知）：只保证「来源可溯 + 可拒收 + 留痕」；
-  · 证据是**他证**（来源节点对主体的观测），不是主体自证；自证走 `identity.anchor`；
-  · **禁止转手**：已导入的跨节点证据（带 `xnode:cross`）不参与再次导出，
-    否则 A 可以把「C 说 B 怎样」洗成「A 说 B 怎样」，来源链断裂。
-
-诚实边界：本层验证的是「**这条证据确实来自该节点**」，
-**不是**「这条证据为真」——后者需节点侧的可信执行，属工程侧责任。
-
-零第三方依赖。
-"""
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import os
-import sys
-import time
-
-from . import identity as _identity
-from . import signer as _signer
-
-NODE_ID_ENV = "MDCG_NODE_ID"
-SWARM_DIR_ENV = "MDCG_SWARM_DIR"
-ROOT_ENV = "MDCG_ROOT"
-
-DEFAULT_DIR = os.path.join(os.path.expanduser("~"), ".mdcg")
-DEFAULT_SWARM_DIR = os.path.join(DEFAULT_DIR, "swarm")
-
-SUBSYSTEM = "swarm"          # 子系统名：智能体可对它声明签名策略（D-4）
-SIGN_ACTION = "evidence"
-SCHEMA = 1
-KIND = "mdcg.evidence.pack"
-CARD_KIND = "mdcg.node.card"
-
-TAG_XNODE = "xnode:cross"
-SOURCE_PREFIX = "source:"
-
-MAX_ITEMS = 500              # 单包条目上限（防灌包）
-MAX_TEXT = 4000              # 单条正文上限
-
-
-class EvidenceError(Exception):
-    """跨节点证据层错误（fail-closed）。"""
-
-
-# --------------------------------------------------------------------------
-# 路径与身份
-# --------------------------------------------------------------------------
-
-# 生效条件：当传入 path 为真值时返回 path；否则若环境变量 SWARM_DIR_ENV 为真值则返回其值；否则返回模块级常量 DEFAULT_SWARM_DIR。
-def swarm_dir(path: str = None) -> str:
-    return path or os.environ.get(SWARM_DIR_ENV) or DEFAULT_SWARM_DIR
-
-
-# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "peers")。
-def peers_dir(swarm: str = None) -> str:
-    return os.path.join(swarm_dir(swarm), "peers")
-
-
-# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "inbox")。
-def inbox_dir(swarm: str = None) -> str:
-    return os.path.join(swarm_dir(swarm), "inbox")
-
-
-# 生效条件：当传入 root 为真值时返回 root；否则返回环境变量 ROOT_ENV 的值（可能为 None）。
-def _root_of(root: str = None) -> str:
-    return root or os.environ.get(ROOT_ENV)
-
-
-# 生效条件：当 explicit 或环境变量 NODE_ID_ENV strip 后非空时返回该值；否则若 _root_of(root) 返回真值，返回基于规范绝对路径的 'node-<12hex>'；否则抛出 EvidenceError。
-def node_id(root: str = None, explicit: str = None) -> str:
-    """本节点身份。
-
-    优先 `MDCG_NODE_ID`（生产环境应显式设置，保证跨机器稳定）；
-    缺省从根路径派生 `node-<12hex>`（同机可复现，跨机器不保证唯一）。
-    """
-    nid = (explicit or os.environ.get(NODE_ID_ENV) or "").strip()
-    if nid:
-        return nid
-    r = _root_of(root)
-    if not r:
-        raise EvidenceError(
-            "无法确定节点身份：请设 MDCG_NODE_ID（推荐）或 MDCG_ROOT")
-    key = os.path.normcase(os.path.abspath(r))
-    return "node-" + hashlib.sha256(key.encode("utf-8")).hexdigest()[:12]
-
-
-# 生效条件：包内 md_cg.theory 可导入且 _th.check() 成功时返回 {version, accepted, theory_ok}；任何异常（版本层缺失或校验失败）一律吞掉返回 {}，不阻断证据层主流程；
-def _theory_state() -> dict:
-    try:
-        from . import theory as _th
-        st = _th.check()
-        return {"version": st.get("version"),
-                "accepted": list(st.get("accepted_versions") or []),
-                "theory_ok": bool(st.get("theory_ok"))}
-    except Exception:                              # 版本层缺失不阻断证据层
-        return {}
-
-
-# 生效条件：当传入 obj 时，返回其 json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(',',':')).encode("utf-8") 字节。
-def _canon(obj) -> bytes:
-    return json.dumps(obj, ensure_ascii=False, sort_keys=True,
-                      separators=(",", ":")).encode("utf-8")
-
-
-# 生效条件：当传入 s 时，返回 str(s) 中每个字符若为字母数字或 '_' '-' 则保留，否则替换为 '_' 的字符串。
-def _slug(s) -> str:
-    return "".join(ch if (ch.isalnum() or ch in "_-") else "_" for ch in str(s))
-
-
-# --------------------------------------------------------------------------
-# 节点名片（发现）
-# --------------------------------------------------------------------------
-
-# 生效条件：当传入 root、subsystem（默认常量 SUBSYSTEM）、signers_file 时，基于 _signer.policy_for 和 _signer.get_signer 返回名片字典，其中 root 为 os.path.abspath(_root_of(root)) 若 _root_of(root) 真值否则 None。
-def card(root: str = None, *, subsystem: str = SUBSYSTEM,
-         signers_file: str = None) -> dict:
-    """本节点名片：身份 + 版本 + 签名器公开信息（**不含密钥**）。"""
-    pol = _signer.policy_for(subsystem, signers_file)
-    s = _signer.get_signer(pol.get("signer"))
-    r = _root_of(root)
-    return {
-        "schema": SCHEMA, "kind": CARD_KIND,
-        "node_id": node_id(root),
-        "root": os.path.abspath(r) if r else None,
-        "theory": _theory_state(),
-        "signer": s.public(),
-        "subsystem": subsystem,
-        "policy": {"sign_on": list(pol.get("sign_on") or []),
-                   "require_peer_signature": bool(pol.get("require_peer_signature")),
-                   "on_verify_fail": pol.get("on_verify_fail")},
-        "created_at": time.time(),
-    }
-
-
-# 生效条件：当传入 root、swarm、subsystem（默认常量 SUBSYSTEM）、signers_file 时，调用 card 得到 c，将 c 以 JSON 写入 peers_dir(swarm)/<c["node_id"]>.json，返回 {"ok": True, "file": p, "card": c}。
-def publish_card(root: str = None, *, swarm: str = None,
-                 subsystem: str = SUBSYSTEM, signers_file: str = None) -> dict:
-    """把本节点名片写入共享目录 `peers/<node_id>.json`（0600）。"""
-    c = card(root, subsystem=subsystem, signers_file=signers_file)
-    p = os.path.join(peers_dir(swarm), c["node_id"] + ".json")
-    _write_json(p, c)
-    return {"ok": True, "file": p, "card": c}
-
-
-# 生效条件：当 peers_dir(swarm) 是目录时，遍历其中 .json 文件，加载为 dict 且 kind 等于常量 CARD_KIND 的名片，若 exclude_self 为真则排除 node_id 等于 node_id(root) 的名片（node_id(root) 抛 EvidenceError 时 self_id 为 None 不排除），返回按文件名排序的列表及计数；目录不存在则返回空列表。
-def peers(swarm: str = None, *, exclude_self: bool = True,
-          root: str = None) -> dict:
-    """发现共享目录里的对端名片（按 node_id 排序）。"""
-    d = peers_dir(swarm)
-    out, self_id = [], None
-    if exclude_self:
-        try:
-            self_id = node_id(root)
-        except EvidenceError:
-            self_id = None
-    if os.path.isdir(d):
-        for fn in sorted(os.listdir(d)):
-            if not fn.endswith(".json"):
-                continue
-            try:
-                with open(os.path.join(d, fn), "r", encoding="utf-8") as f:
-                    c = json.load(f)
-            except (OSError, ValueError):
-                continue
-            if not isinstance(c, dict) or c.get("kind") != CARD_KIND:
-                continue
-            if self_id and c.get("node_id") == self_id:
-                continue
-            out.append(c)
-    return {"dir": d, "count": len(out), "peers": out}
-
-
-# --------------------------------------------------------------------------
-# 证据包：导出
-# --------------------------------------------------------------------------
-
-_PACK_FIELDS = ("schema", "kind", "pack_id", "from_node", "from_root",
-                "theory", "created_at", "subjects", "items")
-
-
-# 生效条件：当传入 pack 字典时，返回仅含模块级常量 _PACK_FIELDS 中字段（缺失字段取 pack.get(k) 得到 None）的规范化 JSON 字节。
-def _pack_payload(pack: dict) -> bytes:
-    """签名载荷：固定字段 + 排序序列化，同参数必同字节。"""
-    body = {}
-    for k in _PACK_FIELDS:
-        body[k] = pack.get(k)
-    return _canon(body)
-
-
-# 生效条件：当传入 cg、subjects、since 时，遍历 cg.index["nodes"] 中按 node_id 排序的节点，仅收集标签含常量 TAG_OBS、不含 TAG_ANCHOR/TAG_TRAIT、不含 TAG_XNODE、能提取 subject: 标签且该 subject 在 subjects（subjects 为真时）或不限制（subjects 假值时）、且若 since 为真且 ts 为真则要求 float(ts) >= float(since) 的节点，返回含 node_id、subject、text（截断 MAX_TEXT）、kind、role、layer、过滤后的 tags、importance、verification_basis、ts 的列表。
-def _collect(cg, subjects=None, since=None) -> list:
-    """收集本根**本地原始**观测证据（排除档案节点与已导入的跨节点证据）。"""
-    want = set(subjects or [])
-    items = []
-    nodes = cg.index.get("nodes") or {}
-    for nid in sorted(nodes):
-        e = nodes[nid]
-        tg = set(e.get("tags") or [])
-        if _identity.TAG_OBS not in tg:
-            continue
-        if tg & {_identity.TAG_ANCHOR, _identity.TAG_TRAIT}:
-            continue
-        if TAG_XNODE in tg:                        # 禁止转手（防洗证据）
-            continue
-        subj = ""
-        for t in tg:
-            if isinstance(t, str) and t.startswith("subject:"):
-                subj = t[len("subject:"):]
-                break
-        if not subj or (want and subj not in want):
-            continue
-        node = cg.get(nid) or {}
-        fm = node.get("frontmatter") or {}
-        ts = fm.get("ts") or fm.get("created_at") or e.get("ts") or 0
-        if since and ts and float(ts) < float(since):
-            continue
-        items.append({
-            "node_id": nid,
-            "subject": subj,
-            "text": (node.get("content") or "")[:MAX_TEXT],
-            "kind": fm.get("kind"),
-            "role": fm.get("role"),
-            "layer": e.get("layer"),
-            "tags": sorted(t for t in tg
-                           if isinstance(t, str)
-                           and not t.startswith("subject:")
-                           and not t.startswith(SOURCE_PREFIX)
-                           and t != TAG_XNODE),
-            "importance": fm.get("importance"),
-            "verification_basis": (e.get("verification_basis")
-                                   or fm.get("verification_basis")),
-            "ts": ts,
-        })
-    return items
-
-
-# 生效条件：当传入 cg、subjects、since、swarm、subsystem（默认 SUBSYSTEM）、signers_file、require_signature（默认 True）时，收集证据并截断至常量 MAX_ITEMS，用 _signer.sign_for 以常量 SIGN_ACTION 签名，若 require_signature 为真且签名未成功则抛出 EvidenceError，否则返回含 pack、count、truncated、signed 的字典。
-def export_pack(cg, *, subjects=None, since=None, swarm: str = None,
-                subsystem: str = SUBSYSTEM, signers_file: str = None,
-                require_signature: bool = True) -> dict:
-    """导出本节点对（指定）主体的观测证据包，并签名。
-
-    `require_signature=True`（默认）：策略未对 `evidence` 签名即抛错——
-    跨节点证据没有签名就不可溯源，宁可不产出。
-    """
-    items = _collect(cg, subjects=subjects, since=since)
-    truncated = len(items) > MAX_ITEMS
-    items = items[:MAX_ITEMS]
-    nid = node_id(getattr(cg, "root", None))
-    pack = {
-        "schema": SCHEMA, "kind": KIND,
-        "from_node": nid,
-        "from_root": os.path.abspath(getattr(cg, "root", "") or ""),
-        "theory": _theory_state(),
-        "created_at": time.time(),
-        "subjects": sorted(set(subjects or [])),
-        "items": items,
-    }
-    pid = hashlib.sha256(_canon({"n": nid, "t": pack["created_at"],
-                                 "c": len(items)})).hexdigest()[:12]
-    pack["pack_id"] = "pack-" + pid
-
-    sigres = _signer.sign_for(subsystem, _pack_payload(pack),
-                              action=SIGN_ACTION, path=signers_file)
-    pack["sig"] = {"signer": sigres.get("signer"),
-                   "signature": sigres.get("signature") or "",
-                   "signed": bool(sigres.get("signed"))}
-    if require_signature and not pack["sig"]["signed"]:
-        raise EvidenceError(
-            f"子系统 {subsystem} 策略未对 {SIGN_ACTION} 签名，证据包不可溯源。"
-            f"请先声明：set_policy({subsystem!r}, sign_on=['handshake','{SIGN_ACTION}'])")
-    return {"ok": True, "pack": pack, "count": len(items),
-            "truncated": truncated, "signed": pack["sig"]["signed"]}
-
-
-# 生效条件：当传入 pack、path、swarm 时，若 path 为假值则用 os.path.join(inbox_dir(swarm), f"{_slug(pack.get('from_node'))}__{pack.get('pack_id')}.json") 生成路径，将 pack 以 JSON 写入该路径并返回 {"ok": True, "file": path}。
-def write_pack(pack: dict, path: str = None, swarm: str = None) -> dict:
-    """把证据包落盘到收件箱（或指定路径）。"""
-    if not path:
-        path = os.path.join(inbox_dir(swarm),
-                            f"{_slug(pack.get('from_node'))}__{pack.get('pack_id')}.json")
-    _write_json(path, pack)
-    return {"ok": True, "file": path}
-
-
-# --------------------------------------------------------------------------
-# 证据包：导入
-# --------------------------------------------------------------------------
-
-# 生效条件：当 src 是 dict 时直接返回 src；否则以 src 为路径打开 JSON 文件并返回 json.load(f)。
-def _read_pack(src) -> dict:
-    if isinstance(src, dict):
-        return src
-    with open(src, "r", encoding="utf-8") as f:
-        return json.load(f)
-
-
-# 生效条件：当 pack 为 dict 且 kind 等于常量 KIND、int(pack.get("schema") or 0) 不大于常量 SCHEMA、from_node strip 后非空、items 为 list 时返回空字符串；否则按序返回对应错误字符串（非 dict、kind 不符、schema 过新、缺 from_node、缺 items）。
-def _validate(pack: dict) -> str:
-    if not isinstance(pack, dict):
-        return "证据包不是 JSON 对象"
-    if pack.get("kind") != KIND:
-        return f"不是证据包（kind={pack.get('kind')!r}）"
-    if int(pack.get("schema") or 0) > SCHEMA:
-        return f"证据包 schema 过新：{pack.get('schema')} > {SCHEMA}"
-    if not (pack.get("from_node") or "").strip():
-        return "证据包缺少 from_node（来源不可溯）"
-    if not isinstance(pack.get("items"), list):
-        return "证据包缺少 items"
-    return ""
-
-
-# 生效条件：当传入 from_node 和 orig 时，返回 f"xnode_{_slug(from_node)}_{_slug(orig)}"。
-def _xnode_id(from_node: str, orig: str) -> str:
-    return f"xnode_{_slug(from_node)}_{_slug(orig)}"
-
-
-# 生效条件：当传入 pack、reason、swarm、**kw 时，构建含 at、reason、from_node、pack_id 及 kw 中非 None 项的拒绝记录，尝试追加到 inbox_dir(swarm)/_rejected.jsonl（OSError 忽略），返回 {"ok": False, "rejected": True, "reason": reason, "from_node": ...} 并合并 kw 中非 None 项。
-def _note_reject(pack: dict, reason: str, swarm: str = None, **kw) -> dict:
-    rec = {"at": time.time(), "reason": reason,
-           "from_node": (pack or {}).get("from_node"),
-           "pack_id": (pack or {}).get("pack_id")}
-    rec.update({k: v for k, v in kw.items() if v is not None})
-    try:
-        from .fsutil import append_jsonl
-        os.makedirs(inbox_dir(swarm), exist_ok=True)
-        append_jsonl(os.path.join(inbox_dir(swarm), "_rejected.jsonl"), rec)
-    except OSError:
-        pass
-    out = {"ok": False, "rejected": True, "reason": reason,
-           "from_node": rec.get("from_node")}
-    out.update({k: v for k, v in kw.items() if v is not None})
-    return out
-
-
-# 生效条件：当传入 cg、src、subsystem（默认 SUBSYSTEM）、swarm、signers_file、archive（默认 True）时，依次读取 src 为 pack、_validate 校验、来源 node_id 不等于本节点、_signer.verify_for 验签成功、且有签名或 signer 等于 "null" 方可通过；通过则对 pack["items"] 前常量 MAX_ITEMS 项中 subject/text 非空者以 _identity.observe 写入（带常量 TAG_XNODE 和 SOURCE_PREFIX 标签，importance 默认 0.5，verification_basis 默认 "data"），统计 written/skipped，若 archive 为真则写包到收件箱，返回含 ok、from_node、pack_id、imported、skipped、truncated、node_ids、archived 的字典；任一拒绝分支调用 _note_reject 返回拒绝结果。
-def import_pack(cg, src, *, subsystem: str = SUBSYSTEM, swarm: str = None,
-                signers_file: str = None, archive: bool = True) -> dict:
-    """导入对端证据包：验签 → 落本根（带 `source:<node>` 标签）。
-
-    fail-closed：结构不合法、来源即本节点、验签失败、缺签名 → 一律拒收并留痕。
-    """
-    try:
-        pack = _read_pack(src)
-    except (OSError, ValueError) as e:
-        return _note_reject({}, f"证据包读取失败：{e}", swarm=swarm)
-
-    err = _validate(pack)
-    if err:
-        return _note_reject(pack, err, swarm=swarm)
-
-    from_node = pack["from_node"].strip()
-    if from_node == node_id(getattr(cg, "root", None)):
-        return _note_reject(pack, "证据包来源即本节点（拒绝自导入）", swarm=swarm)
-
-    signature = ((pack.get("sig") or {}).get("signature") or "").strip()
-    vres = _signer.verify_for(subsystem, _pack_payload(pack), signature,
-                              action=SIGN_ACTION, path=signers_file)
-    if not vres.get("ok"):
-        return _note_reject(pack, f"验签失败：{vres.get('reason') or '未知'}",
-                            swarm=swarm, on_fail=vres.get("on_fail"))
-    if not signature and (pack.get("sig") or {}).get("signer") != "null":
-        return _note_reject(pack, "证据包缺少签名（跨节点证据必须可溯源）",
-                            swarm=swarm)
-
-    items = pack["items"][:MAX_ITEMS]
-    written, skipped = [], 0
-    for it in items:
-        if not isinstance(it, dict):
-            skipped += 1
-            continue
-        subj = (it.get("subject") or "").strip()
-        text = (it.get("text") or "").strip()
-        if not subj or not text:
-            skipped += 1
-            continue
-        tags = [TAG_XNODE, f"{SOURCE_PREFIX}{from_node}"]
-        tags += [t for t in (it.get("tags") or [])
-                 if isinstance(t, str) and t
-                 and not t.startswith("subject:")
-                 and not t.startswith(SOURCE_PREFIX)
-                 and t not in (TAG_XNODE, _identity.TAG_ANCHOR, _identity.TAG_TRAIT)]
-        imp = it.get("importance")
-        _identity.observe(
-            cg, subj, text,
-            kind=it.get("kind"), role=it.get("role"),
-            layer=it.get("layer") or "knowledge",
-            tags=tags,
-            importance=0.5 if imp is None else imp,
-            verification_basis=it.get("verification_basis") or "data",
-            node_id=_xnode_id(from_node, it.get("node_id") or subj),
-            override=True)
-        written.append(_xnode_id(from_node, it.get("node_id") or subj))
-
-    archived = ""
-    if archive:
-        try:
-            archived = write_pack(pack, swarm=swarm)["file"]
-        except OSError:
-            archived = ""
-    return {"ok": True, "from_node": from_node, "pack_id": pack.get("pack_id"),
-            "imported": len(written), "skipped": skipped,
-            "truncated": len(pack["items"]) > MAX_ITEMS,
-            "node_ids": written, "archived": archived}
-
-
-# --------------------------------------------------------------------------
-# 查询
-# --------------------------------------------------------------------------
-
-# 生效条件：当传入 cg、subject、source、limit（默认 100）时，收集标签含常量 TAG_XNODE 的节点，若 subject 为真则仅保留 subject 标签等于 subject 的节点，若 source 为真则仅保留 source 标签等于 source 的节点，返回最后 int(limit or 100) 条记录（limit 为假值如 0 时取 100）的 count 与列表。
-def evidence(cg, *, subject: str = None, source: str = None,
-             limit: int = 100) -> dict:
-    """列本根已导入的跨节点证据（按来源/主体过滤）。"""
-    out = []
-    nodes = cg.index.get("nodes") or {}
-    for nid in sorted(nodes):
-        e = nodes[nid]
-        tg = set(e.get("tags") or [])
-        if TAG_XNODE not in tg:
-            continue
-        subj, src = "", ""
-        for t in tg:
-            if isinstance(t, str) and t.startswith("subject:"):
-                subj = t[len("subject:"):]
-            elif isinstance(t, str) and t.startswith(SOURCE_PREFIX):
-                src = t[len(SOURCE_PREFIX):]
-        if subject and subj != subject:
-            continue
-        if source and src != source:
-            continue
-        node = cg.get(nid) or {}
-        out.append({"node_id": nid, "subject": subj, "source": src,
-                    "layer": e.get("layer"),
-                    "content": (node.get("content") or "")[:400]})
-    out = out[-int(limit or 100):]
-    return {"count": len(out), "evidence": out}
-
-
-# 生效条件：无参数调用时返回包含模块级常量 SUBSYSTEM、SIGN_ACTION、SWARM_DIR_ENV、NODE_ID_ENV、ROOT_ENV、MAX_ITEMS、MAX_TEXT 及 swarm_dir() 等字段的自描述字典。
-def catalog() -> dict:
-    return {
-        "layer": "跨节点证据存储（蜂群互联 v0.3）",
-        "question": "跨节点：你凭什么这么说",
-        "blindspot": "§9.1 单根假设——对端观测对本节点不可见",
-        "invariants": ["来源可溯", "可拒收", "全程留痕", "禁止转手"],
-        "subsystem": SUBSYSTEM,
-        "sign_action": SIGN_ACTION,
-        "swarm_dir": swarm_dir(),
-        "pack_fields": list(_PACK_FIELDS),
-        "limits": {"max_items": MAX_ITEMS, "max_text": MAX_TEXT},
-        "env": {"node_id": NODE_ID_ENV, "swarm_dir": SWARM_DIR_ENV,
-                "root": ROOT_ENV},
-        "honest_boundary": "验证的是「证据来自该节点」，不是「证据为真」",
-    }
-
-
-# --------------------------------------------------------------------------
-# 工具
-# --------------------------------------------------------------------------
-
-# 生效条件：当传入 path 和 obj 时，在 path 所在目录（若 dirname 为空则 "."）创建目录，将 obj 以 JSON 写入 path+".tmp"（ensure_ascii=False, indent=1, sort_keys=True），尝试 chmod 0600，替换到 path，返回 path。
-def _write_json(path: str, obj) -> str:
-    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
-    tmp = path + ".tmp"
-    with open(tmp, "w", encoding="utf-8") as f:
-        json.dump(obj, f, ensure_ascii=False, indent=1, sort_keys=True)
-    try:
-        os.chmod(tmp, 0o600)
-    except OSError:
-        pass
-    os.replace(tmp, path)
-    return path
-
-
-# 生效条件：当传入 root 且 _root_of(root) 返回真值时，以 designer 角色 Principal（tenant 取 os.environ.get("MDCG_TENANT", "default") 的实际值，actor 取 os.environ.get("MDCG_ACTOR", "swarm-cli") 的实际值）打开 MdCGSecure；否则抛出 EvidenceError。
-def _open_cg(root: str = None):
-    """CLI 用：以 designer 身份打开根（令牌路径仍推荐走 MCP）。"""
-    from .mdcos import MdCGSecure
-    from .security import Principal
-    from .tokens import role_spec
-    r = _root_of(root)
-    if not r:
-        raise EvidenceError("缺少根目录：请设 MDCG_ROOT 或传 --root")
-    spec = role_spec("designer")
-    p = Principal(tenant=os.environ.get("MDCG_TENANT", "default"),
-                  actor=os.environ.get("MDCG_ACTOR", "swarm-cli"),
-                  clearance="private", can_write=True, can_admin=True,
-                  role="designer", layers_allow=spec["layers_allow"],
-                  ops_allow=spec["ops_allow"], auth_mode="legacy_env")
-    return MdCGSecure(r, principal=p)
-
-
-# 生效条件：当传入 obj 时，打印 json.dumps(obj, ensure_ascii=False, indent=1, default=str)。
-def _print(obj):
-    print(json.dumps(obj, ensure_ascii=False, indent=1, default=str))
-
-
-# 生效条件：argv 为 None 时取 sys.argv[1:]；经 argparse 解析后必填子命令（catalog/card/export/import 等）之一，参数缺失或非法由 argparse 直接退出；返回进程退出码；
-def main(argv=None):
-    ap = argparse.ArgumentParser(
-        prog="python -m md_cg.evidence",
-        description="跨节点证据存储：名片 / 导出 / 导入（v0.3）")
-    ap.add_argument("--root", default=None, help="认知图根（默认 MDCG_ROOT）")
-    ap.add_argument("--swarm", default=None, help="共享目录（默认 ~/.mdcg/swarm）")
-    ap.add_argument("--signers-file", default=None)
-    sub = ap.add_subparsers(dest="cmd", required=True)
-
-    sub.add_parser("catalog", help="自描述")
-    sub.add_parser("card", help="本节点名片")
-    sub.add_parser("publish", help="发布名片到共享目录")
-    sub.add_parser("peers", help="发现对端名片")
-
-    p_ex = sub.add_parser("export", help="导出证据包")
-    p_ex.add_argument("--subject", action="append", default=None)
-    p_ex.add_argument("--out", default=None, help="输出文件（默认写收件箱）")
-
-    p_im = sub.add_parser("import", help="导入证据包")
-    p_im.add_argument("path")
-
-    p_ls = sub.add_parser("ls", help="列已导入的跨节点证据")
-    p_ls.add_argument("--subject", default=None)
-    p_ls.add_argument("--source", default=None)
-    p_ls.add_argument("--limit", type=int, default=100)
-
-    a = ap.parse_args(argv)
-    cg = None
-    try:
-        if a.cmd == "catalog":
-            _print(catalog())
-        elif a.cmd == "card":
-            _print(card(a.root, signers_file=a.signers_file))
-        elif a.cmd == "publish":
-            _print(publish_card(a.root, swarm=a.swarm,
-                                signers_file=a.signers_file))
-        elif a.cmd == "peers":
-            _print(peers(a.swarm, root=a.root))
-        elif a.cmd == "export":
-            cg = _open_cg(a.root)
-            res = export_pack(cg, subjects=a.subject, swarm=a.swarm,
-                              signers_file=a.signers_file)
-            _print(write_pack(res["pack"], path=a.out, swarm=a.swarm)
-                   if a.out else res)
-        elif a.cmd == "import":
-            cg = _open_cg(a.root)
-            _print(import_pack(cg, a.path, swarm=a.swarm,
-                               signers_file=a.signers_file))
-        elif a.cmd == "ls":
-            cg = _open_cg(a.root)
-            _print(evidence(cg, subject=a.subject, source=a.source,
-                            limit=a.limit))
-    except (EvidenceError, _signer.SignerError) as e:
-        print(f"[md_cg.evidence] {e}", file=sys.stderr)
-        return 2
-    finally:
-        if cg is not None:
-            try:
-                cg.close()          # 落盘索引，保证跨进程可见
-            except Exception:       # noqa: BLE001 —— 关闭失败不掩盖主流程结果
-                pass
-    return 0
-
-
-if __name__ == "__main__":
+# -*- coding: utf-8 -*-
+"""跨节点证据存储（蜂群互联 v0.3）。
+
+攻 §9.1 盲区：`identity.infer_position` 只统计**本根**带 `subject:<id>` 标签的
+证据节点，跨节点时对端观测对本节点不可见。本模块给出最小可测的交换机制：
+
+  ① **节点名片**（card）——`node_id` / 根路径 / 版本状态 / 签名器公开信息；
+  ② **证据包**（pack）——从本根导出「我对某主体的观测」，**由本节点签名**；
+  ③ **导入**（import）——验签 → 落本根（带 `source:<node>` 标签）→ 可审计、可拒收。
+
+设计边界（承 D-1 / D-4）：
+
+  · 内核**不做密码学**：签名/验签一律经 `signer.sign_for / verify_for`，
+    跨节点证据要求子系统策略 `sign_on` 含 `evidence`（由智能体自决）；
+  · 内核**不保证全局共识**（0.0.3 局部不可知）：只保证「来源可溯 + 可拒收 + 留痕」；
+  · 证据是**他证**（来源节点对主体的观测），不是主体自证；自证走 `identity.anchor`；
+  · **禁止转手**：已导入的跨节点证据（带 `xnode:cross`）不参与再次导出，
+    否则 A 可以把「C 说 B 怎样」洗成「A 说 B 怎样」，来源链断裂。
+
+诚实边界：本层验证的是「**这条证据确实来自该节点**」，
+**不是**「这条证据为真」——后者需节点侧的可信执行，属工程侧责任。
+
+零第三方依赖。
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+
+from . import identity as _identity
+from . import signer as _signer
+
+NODE_ID_ENV = "MDCG_NODE_ID"
+SWARM_DIR_ENV = "MDCG_SWARM_DIR"
+ROOT_ENV = "MDCG_ROOT"
+
+DEFAULT_DIR = os.path.join(os.path.expanduser("~"), ".mdcg")
+DEFAULT_SWARM_DIR = os.path.join(DEFAULT_DIR, "swarm")
+
+SUBSYSTEM = "swarm"          # 子系统名：智能体可对它声明签名策略（D-4）
+SIGN_ACTION = "evidence"
+SCHEMA = 1
+KIND = "mdcg.evidence.pack"
+CARD_KIND = "mdcg.node.card"
+
+TAG_XNODE = "xnode:cross"
+SOURCE_PREFIX = "source:"
+
+MAX_ITEMS = 500              # 单包条目上限（防灌包）
+MAX_TEXT = 4000              # 单条正文上限
+
+
+class EvidenceError(Exception):
+    """跨节点证据层错误（fail-closed）。"""
+
+
+# --------------------------------------------------------------------------
+# 路径与身份
+# --------------------------------------------------------------------------
+
+# 生效条件：当传入 path 为真值时返回 path；否则若环境变量 SWARM_DIR_ENV 为真值则返回其值；否则返回模块级常量 DEFAULT_SWARM_DIR。
+def swarm_dir(path: str = None) -> str:
+    return path or os.environ.get(SWARM_DIR_ENV) or DEFAULT_SWARM_DIR
+
+
+# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "peers")。
+def peers_dir(swarm: str = None) -> str:
+    return os.path.join(swarm_dir(swarm), "peers")
+
+
+# 生效条件：当传入 swarm 参数（假值回落到 swarm_dir 的默认逻辑）时，返回 os.path.join(swarm_dir(swarm), "inbox")。
+def inbox_dir(swarm: str = None) -> str:
+    return os.path.join(swarm_dir(swarm), "inbox")
+
+
+# 生效条件：当传入 root 为真值时返回 root；否则返回环境变量 ROOT_ENV 的值（可能为 None）。
+def _root_of(root: str = None) -> str:
+    return root or os.environ.get(ROOT_ENV)
+
+
+# 生效条件：当 explicit 或环境变量 NODE_ID_ENV strip 后非空时返回该值；否则若 _root_of(root) 返回真值，返回基于规范绝对路径的 'node-<12hex>'；否则抛出 EvidenceError。
+def node_id(root: str = None, explicit: str = None) -> str:
+    """本节点身份。
+
+    优先 `MDCG_NODE_ID`（生产环境应显式设置，保证跨机器稳定）；
+    缺省从根路径派生 `node-<12hex>`（同机可复现，跨机器不保证唯一）。
+    """
+    nid = (explicit or os.environ.get(NODE_ID_ENV) or "").strip()
+    if nid:
+        return nid
+    r = _root_of(root)
+    if not r:
+        raise EvidenceError(
+            "无法确定节点身份：请设 MDCG_NODE_ID（推荐）或 MDCG_ROOT")
+    key = os.path.normcase(os.path.abspath(r))
+    return "node-" + hashlib.sha256(key.encode("utf-8")).hexdigest()[:12]
+
+
+# 生效条件：包内 md_cg.theory 可导入且 _th.check() 成功时返回 {version, accepted, theory_ok}；任何异常（版本层缺失或校验失败）一律吞掉返回 {}，不阻断证据层主流程；
+def _theory_state() -> dict:
+    try:
+        from . import theory as _th
+        st = _th.check()
+        return {"version": st.get("version"),
+                "accepted": list(st.get("accepted_versions") or []),
+                "theory_ok": bool(st.get("theory_ok"))}
+    except Exception:                              # 版本层缺失不阻断证据层
+        return {}
+
+
+# 生效条件：当传入 obj 时，返回其 json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(',',':')).encode("utf-8") 字节。
+def _canon(obj) -> bytes:
+    return json.dumps(obj, ensure_ascii=False, sort_keys=True,
+                      separators=(",", ":")).encode("utf-8")
+
+
+# 生效条件：当传入 s 时，返回 str(s) 中每个字符若为字母数字或 '_' '-' 则保留，否则替换为 '_' 的字符串。
+def _slug(s) -> str:
+    return "".join(ch if (ch.isalnum() or ch in "_-") else "_" for ch in str(s))
+
+
+# --------------------------------------------------------------------------
+# 节点名片（发现）
+# --------------------------------------------------------------------------
+
+# 生效条件：当传入 root、subsystem（默认常量 SUBSYSTEM）、signers_file 时，基于 _signer.policy_for 和 _signer.get_signer 返回名片字典，其中 root 为 os.path.abspath(_root_of(root)) 若 _root_of(root) 真值否则 None。
+def card(root: str = None, *, subsystem: str = SUBSYSTEM,
+         signers_file: str = None) -> dict:
+    """本节点名片：身份 + 版本 + 签名器公开信息（**不含密钥**）。"""
+    pol = _signer.policy_for(subsystem, signers_file)
+    s = _signer.get_signer(pol.get("signer"))
+    r = _root_of(root)
+    return {
+        "schema": SCHEMA, "kind": CARD_KIND,
+        "node_id": node_id(root),
+        "root": os.path.abspath(r) if r else None,
+        "theory": _theory_state(),
+        "signer": s.public(),
+        "subsystem": subsystem,
+        "policy": {"sign_on": list(pol.get("sign_on") or []),
+                   "require_peer_signature": bool(pol.get("require_peer_signature")),
+                   "on_verify_fail": pol.get("on_verify_fail")},
+        "created_at": time.time(),
+    }
+
+
+# 生效条件：当传入 root、swarm、subsystem（默认常量 SUBSYSTEM）、signers_file 时，调用 card 得到 c，将 c 以 JSON 写入 peers_dir(swarm)/<c["node_id"]>.json，返回 {"ok": True, "file": p, "card": c}。
+def publish_card(root: str = None, *, swarm: str = None,
+                 subsystem: str = SUBSYSTEM, signers_file: str = None) -> dict:
+    """把本节点名片写入共享目录 `peers/<node_id>.json`（0600）。"""
+    c = card(root, subsystem=subsystem, signers_file=signers_file)
+    p = os.path.join(peers_dir(swarm), c["node_id"] + ".json")
+    _write_json(p, c)
+    return {"ok": True, "file": p, "card": c}
+
+
+# 生效条件：当 peers_dir(swarm) 是目录时，遍历其中 .json 文件，加载为 dict 且 kind 等于常量 CARD_KIND 的名片，若 exclude_self 为真则排除 node_id 等于 node_id(root) 的名片（node_id(root) 抛 EvidenceError 时 self_id 为 None 不排除），返回按文件名排序的列表及计数；目录不存在则返回空列表。
+def peers(swarm: str = None, *, exclude_self: bool = True,
+          root: str = None) -> dict:
+    """发现共享目录里的对端名片（按 node_id 排序）。"""
+    d = peers_dir(swarm)
+    out, self_id = [], None
+    if exclude_self:
+        try:
+            self_id = node_id(root)
+        except EvidenceError:
+            self_id = None
+    if os.path.isdir(d):
+        for fn in sorted(os.listdir(d)):
+            if not fn.endswith(".json"):
+                continue
+            try:
+                with open(os.path.join(d, fn), "r", encoding="utf-8") as f:
+                    c = json.load(f)
+            except (OSError, ValueError):
+                continue
+            if not isinstance(c, dict) or c.get("kind") != CARD_KIND:
+                continue
+            if self_id and c.get("node_id") == self_id:
+                continue
+            out.append(c)
+    return {"dir": d, "count": len(out), "peers": out}
+
+
+# --------------------------------------------------------------------------
+# 证据包：导出
+# --------------------------------------------------------------------------
+
+_PACK_FIELDS = ("schema", "kind", "pack_id", "from_node", "from_root",
+                "theory", "created_at", "subjects", "items")
+
+
+# 生效条件：当传入 pack 字典时，返回仅含模块级常量 _PACK_FIELDS 中字段（缺失字段取 pack.get(k) 得到 None）的规范化 JSON 字节。
+def _pack_payload(pack: dict) -> bytes:
+    """签名载荷：固定字段 + 排序序列化，同参数必同字节。"""
+    body = {}
+    for k in _PACK_FIELDS:
+        body[k] = pack.get(k)
+    return _canon(body)
+
+
+# 生效条件：当传入 cg、subjects、since 时，遍历 cg.index["nodes"] 中按 node_id 排序的节点，仅收集标签含常量 TAG_OBS、不含 TAG_ANCHOR/TAG_TRAIT、不含 TAG_XNODE、能提取 subject: 标签且该 subject 在 subjects（subjects 为真时）或不限制（subjects 假值时）、且若 since 为真且 ts 为真则要求 float(ts) >= float(since) 的节点，返回含 node_id、subject、text（截断 MAX_TEXT）、kind、role、layer、过滤后的 tags、importance、verification_basis、ts 的列表。
+def _collect(cg, subjects=None, since=None) -> list:
+    """收集本根**本地原始**观测证据（排除档案节点与已导入的跨节点证据）。"""
+    want = set(subjects or [])
+    items = []
+    nodes = cg.index.get("nodes") or {}
+    for nid in sorted(nodes):
+        e = nodes[nid]
+        tg = set(e.get("tags") or [])
+        if _identity.TAG_OBS not in tg:
+            continue
+        if tg & {_identity.TAG_ANCHOR, _identity.TAG_TRAIT}:
+            continue
+        if TAG_XNODE in tg:                        # 禁止转手（防洗证据）
+            continue
+        subj = ""
+        for t in tg:
+            if isinstance(t, str) and t.startswith("subject:"):
+                subj = t[len("subject:"):]
+                break
+        if not subj or (want and subj not in want):
+            continue
+        node = cg.get(nid) or {}
+        fm = node.get("frontmatter") or {}
+        ts = fm.get("ts") or fm.get("created_at") or e.get("ts") or 0
+        if since and ts and float(ts) < float(since):
+            continue
+        items.append({
+            "node_id": nid,
+            "subject": subj,
+            "text": (node.get("content") or "")[:MAX_TEXT],
+            "kind": fm.get("kind"),
+            "role": fm.get("role"),
+            "layer": e.get("layer"),
+            "tags": sorted(t for t in tg
+                           if isinstance(t, str)
+                           and not t.startswith("subject:")
+                           and not t.startswith(SOURCE_PREFIX)
+                           and t != TAG_XNODE),
+            "importance": fm.get("importance"),
+            "verification_basis": (e.get("verification_basis")
+                                   or fm.get("verification_basis")),
+            "ts": ts,
+        })
+    return items
+
+
+# 生效条件：当传入 cg、subjects、since、swarm、subsystem（默认 SUBSYSTEM）、signers_file、require_signature（默认 True）时，收集证据并截断至常量 MAX_ITEMS，用 _signer.sign_for 以常量 SIGN_ACTION 签名，若 require_signature 为真且签名未成功则抛出 EvidenceError，否则返回含 pack、count、truncated、signed 的字典。
+def export_pack(cg, *, subjects=None, since=None, swarm: str = None,
+                subsystem: str = SUBSYSTEM, signers_file: str = None,
+                require_signature: bool = True) -> dict:
+    """导出本节点对（指定）主体的观测证据包，并签名。
+
+    `require_signature=True`（默认）：策略未对 `evidence` 签名即抛错——
+    跨节点证据没有签名就不可溯源，宁可不产出。
+    """
+    items = _collect(cg, subjects=subjects, since=since)
+    truncated = len(items) > MAX_ITEMS
+    items = items[:MAX_ITEMS]
+    nid = node_id(getattr(cg, "root", None))
+    pack = {
+        "schema": SCHEMA, "kind": KIND,
+        "from_node": nid,
+        "from_root": os.path.abspath(getattr(cg, "root", "") or ""),
+        "theory": _theory_state(),
+        "created_at": time.time(),
+        "subjects": sorted(set(subjects or [])),
+        "items": items,
+    }
+    pid = hashlib.sha256(_canon({"n": nid, "t": pack["created_at"],
+                                 "c": len(items)})).hexdigest()[:12]
+    pack["pack_id"] = "pack-" + pid
+
+    sigres = _signer.sign_for(subsystem, _pack_payload(pack),
+                              action=SIGN_ACTION, path=signers_file)
+    pack["sig"] = {"signer": sigres.get("signer"),
+                   "signature": sigres.get("signature") or "",
+                   "signed": bool(sigres.get("signed"))}
+    if require_signature and not pack["sig"]["signed"]:
+        raise EvidenceError(
+            f"子系统 {subsystem} 策略未对 {SIGN_ACTION} 签名，证据包不可溯源。"
+            f"请先声明：set_policy({subsystem!r}, sign_on=['handshake','{SIGN_ACTION}'])")
+    return {"ok": True, "pack": pack, "count": len(items),
+            "truncated": truncated, "signed": pack["sig"]["signed"]}
+
+
+# 生效条件：当传入 pack、path、swarm 时，若 path 为假值则用 os.path.join(inbox_dir(swarm), f"{_slug(pack.get('from_node'))}__{pack.get('pack_id')}.json") 生成路径，将 pack 以 JSON 写入该路径并返回 {"ok": True, "file": path}。
+def write_pack(pack: dict, path: str = None, swarm: str = None) -> dict:
+    """把证据包落盘到收件箱（或指定路径）。"""
+    if not path:
+        path = os.path.join(inbox_dir(swarm),
+                            f"{_slug(pack.get('from_node'))}__{pack.get('pack_id')}.json")
+    _write_json(path, pack)
+    return {"ok": True, "file": path}
+
+
+# --------------------------------------------------------------------------
+# 证据包：导入
+# --------------------------------------------------------------------------
+
+# 生效条件：当 src 是 dict 时直接返回 src；否则以 src 为路径打开 JSON 文件并返回 json.load(f)。
+def _read_pack(src) -> dict:
+    if isinstance(src, dict):
+        return src
+    with open(src, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# 生效条件：当 pack 为 dict 且 kind 等于常量 KIND、int(pack.get("schema") or 0) 不大于常量 SCHEMA、from_node strip 后非空、items 为 list 时返回空字符串；否则按序返回对应错误字符串（非 dict、kind 不符、schema 过新、缺 from_node、缺 items）。
+def _validate(pack: dict) -> str:
+    if not isinstance(pack, dict):
+        return "证据包不是 JSON 对象"
+    if pack.get("kind") != KIND:
+        return f"不是证据包（kind={pack.get('kind')!r}）"
+    if int(pack.get("schema") or 0) > SCHEMA:
+        return f"证据包 schema 过新：{pack.get('schema')} > {SCHEMA}"
+    if not (pack.get("from_node") or "").strip():
+        return "证据包缺少 from_node（来源不可溯）"
+    if not isinstance(pack.get("items"), list):
+        return "证据包缺少 items"
+    return ""
+
+
+# 生效条件：当传入 from_node 和 orig 时，返回 f"xnode_{_slug(from_node)}_{_slug(orig)}"。
+def _xnode_id(from_node: str, orig: str) -> str:
+    return f"xnode_{_slug(from_node)}_{_slug(orig)}"
+
+
+# 生效条件：当传入 pack、reason、swarm、**kw 时，构建含 at、reason、from_node、pack_id 及 kw 中非 None 项的拒绝记录，尝试追加到 inbox_dir(swarm)/_rejected.jsonl（OSError 忽略），返回 {"ok": False, "rejected": True, "reason": reason, "from_node": ...} 并合并 kw 中非 None 项。
+def _note_reject(pack: dict, reason: str, swarm: str = None, **kw) -> dict:
+    rec = {"at": time.time(), "reason": reason,
+           "from_node": (pack or {}).get("from_node"),
+           "pack_id": (pack or {}).get("pack_id")}
+    rec.update({k: v for k, v in kw.items() if v is not None})
+    try:
+        from .fsutil import append_jsonl
+        os.makedirs(inbox_dir(swarm), exist_ok=True)
+        append_jsonl(os.path.join(inbox_dir(swarm), "_rejected.jsonl"), rec)
+    except OSError:
+        pass
+    out = {"ok": False, "rejected": True, "reason": reason,
+           "from_node": rec.get("from_node")}
+    out.update({k: v for k, v in kw.items() if v is not None})
+    return out
+
+
+# 生效条件：当传入 cg、src、subsystem（默认 SUBSYSTEM）、swarm、signers_file、archive（默认 True）时，依次读取 src 为 pack、_validate 校验、来源 node_id 不等于本节点、_signer.verify_for 验签成功、且有签名或 signer 等于 "null" 方可通过；通过则对 pack["items"] 前常量 MAX_ITEMS 项中 subject/text 非空者以 _identity.observe 写入（带常量 TAG_XNODE 和 SOURCE_PREFIX 标签，importance 默认 0.5，verification_basis 默认 "data"），统计 written/skipped，若 archive 为真则写包到收件箱，返回含 ok、from_node、pack_id、imported、skipped、truncated、node_ids、archived 的字典；任一拒绝分支调用 _note_reject 返回拒绝结果。
+def import_pack(cg, src, *, subsystem: str = SUBSYSTEM, swarm: str = None,
+                signers_file: str = None, archive: bool = True) -> dict:
+    """导入对端证据包：验签 → 落本根（带 `source:<node>` 标签）。
+
+    fail-closed：结构不合法、来源即本节点、验签失败、缺签名 → 一律拒收并留痕。
+    """
+    try:
+        pack = _read_pack(src)
+    except (OSError, ValueError) as e:
+        return _note_reject({}, f"证据包读取失败：{e}", swarm=swarm)
+
+    err = _validate(pack)
+    if err:
+        return _note_reject(pack, err, swarm=swarm)
+
+    from_node = pack["from_node"].strip()
+    if from_node == node_id(getattr(cg, "root", None)):
+        return _note_reject(pack, "证据包来源即本节点（拒绝自导入）", swarm=swarm)
+
+    signature = ((pack.get("sig") or {}).get("signature") or "").strip()
+    vres = _signer.verify_for(subsystem, _pack_payload(pack), signature,
+                              action=SIGN_ACTION, path=signers_file)
+    if not vres.get("ok"):
+        return _note_reject(pack, f"验签失败：{vres.get('reason') or '未知'}",
+                            swarm=swarm, on_fail=vres.get("on_fail"))
+    if not signature and (pack.get("sig") or {}).get("signer") != "null":
+        return _note_reject(pack, "证据包缺少签名（跨节点证据必须可溯源）",
+                            swarm=swarm)
+
+    items = pack["items"][:MAX_ITEMS]
+    written, skipped = [], 0
+    for it in items:
+        if not isinstance(it, dict):
+            skipped += 1
+            continue
+        subj = (it.get("subject") or "").strip()
+        text = (it.get("text") or "").strip()
+        if not subj or not text:
+            skipped += 1
+            continue
+        tags = [TAG_XNODE, f"{SOURCE_PREFIX}{from_node}"]
+        tags += [t for t in (it.get("tags") or [])
+                 if isinstance(t, str) and t
+                 and not t.startswith("subject:")
+                 and not t.startswith(SOURCE_PREFIX)
+                 and t not in (TAG_XNODE, _identity.TAG_ANCHOR, _identity.TAG_TRAIT)]
+        imp = it.get("importance")
+        _identity.observe(
+            cg, subj, text,
+            kind=it.get("kind"), role=it.get("role"),
+            layer=it.get("layer") or "knowledge",
+            tags=tags,
+            importance=0.5 if imp is None else imp,
+            verification_basis=it.get("verification_basis") or "data",
+            node_id=_xnode_id(from_node, it.get("node_id") or subj),
+            override=True)
+        written.append(_xnode_id(from_node, it.get("node_id") or subj))
+
+    archived = ""
+    if archive:
+        try:
+            archived = write_pack(pack, swarm=swarm)["file"]
+        except OSError:
+            archived = ""
+    return {"ok": True, "from_node": from_node, "pack_id": pack.get("pack_id"),
+            "imported": len(written), "skipped": skipped,
+            "truncated": len(pack["items"]) > MAX_ITEMS,
+            "node_ids": written, "archived": archived}
+
+
+# --------------------------------------------------------------------------
+# 查询
+# --------------------------------------------------------------------------
+
+# 生效条件：当传入 cg、subject、source、limit（默认 100）时，收集标签含常量 TAG_XNODE 的节点，若 subject 为真则仅保留 subject 标签等于 subject 的节点，若 source 为真则仅保留 source 标签等于 source 的节点，返回最后 int(limit or 100) 条记录（limit 为假值如 0 时取 100）的 count 与列表。
+def evidence(cg, *, subject: str = None, source: str = None,
+             limit: int = 100) -> dict:
+    """列本根已导入的跨节点证据（按来源/主体过滤）。"""
+    out = []
+    nodes = cg.index.get("nodes") or {}
+    for nid in sorted(nodes):
+        e = nodes[nid]
+        tg = set(e.get("tags") or [])
+        if TAG_XNODE not in tg:
+            continue
+        subj, src = "", ""
+        for t in tg:
+            if isinstance(t, str) and t.startswith("subject:"):
+                subj = t[len("subject:"):]
+            elif isinstance(t, str) and t.startswith(SOURCE_PREFIX):
+                src = t[len(SOURCE_PREFIX):]
+        if subject and subj != subject:
+            continue
+        if source and src != source:
+            continue
+        node = cg.get(nid) or {}
+        out.append({"node_id": nid, "subject": subj, "source": src,
+                    "layer": e.get("layer"),
+                    "content": (node.get("content") or "")[:400]})
+    out = out[-int(limit or 100):]
+    return {"count": len(out), "evidence": out}
+
+
+# 生效条件：无参数调用时返回包含模块级常量 SUBSYSTEM、SIGN_ACTION、SWARM_DIR_ENV、NODE_ID_ENV、ROOT_ENV、MAX_ITEMS、MAX_TEXT 及 swarm_dir() 等字段的自描述字典。
+def catalog() -> dict:
+    return {
+        "layer": "跨节点证据存储（蜂群互联 v0.3）",
+        "question": "跨节点：你凭什么这么说",
+        "blindspot": "§9.1 单根假设——对端观测对本节点不可见",
+        "invariants": ["来源可溯", "可拒收", "全程留痕", "禁止转手"],
+        "subsystem": SUBSYSTEM,
+        "sign_action": SIGN_ACTION,
+        "swarm_dir": swarm_dir(),
+        "pack_fields": list(_PACK_FIELDS),
+        "limits": {"max_items": MAX_ITEMS, "max_text": MAX_TEXT},
+        "env": {"node_id": NODE_ID_ENV, "swarm_dir": SWARM_DIR_ENV,
+                "root": ROOT_ENV},
+        "honest_boundary": "验证的是「证据来自该节点」，不是「证据为真」",
+    }
+
+
+# --------------------------------------------------------------------------
+# 工具
+# --------------------------------------------------------------------------
+
+# 生效条件：当传入 path 和 obj 时，在 path 所在目录（若 dirname 为空则 "."）创建目录，将 obj 以 JSON 写入 path+".tmp"（ensure_ascii=False, indent=1, sort_keys=True），尝试 chmod 0600，替换到 path，返回 path。
+def _write_json(path: str, obj) -> str:
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(obj, f, ensure_ascii=False, indent=1, sort_keys=True)
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+    return path
+
+
+# 生效条件：当传入 root 且 _root_of(root) 返回真值时，以 designer 角色 Principal（tenant 取 os.environ.get("MDCG_TENANT", "default") 的实际值，actor 取 os.environ.get("MDCG_ACTOR", "swarm-cli") 的实际值）打开 MdCGSecure；否则抛出 EvidenceError。
+def _open_cg(root: str = None):
+    """CLI 用：以 designer 身份打开根（令牌路径仍推荐走 MCP）。"""
+    from .mdcos import MdCGSecure
+    from .security import Principal
+    from .tokens import role_spec
+    r = _root_of(root)
+    if not r:
+        raise EvidenceError("缺少根目录：请设 MDCG_ROOT 或传 --root")
+    spec = role_spec("designer")
+    p = Principal(tenant=os.environ.get("MDCG_TENANT", "default"),
+                  actor=os.environ.get("MDCG_ACTOR", "swarm-cli"),
+                  clearance="private", can_write=True, can_admin=True,
+                  role="designer", layers_allow=spec["layers_allow"],
+                  ops_allow=spec["ops_allow"], auth_mode="legacy_env")
+    return MdCGSecure(r, principal=p)
+
+
+# 生效条件：当传入 obj 时，打印 json.dumps(obj, ensure_ascii=False, indent=1, default=str)。
+def _print(obj):
+    print(json.dumps(obj, ensure_ascii=False, indent=1, default=str))
+
+
+# 生效条件：argv 为 None 时取 sys.argv[1:]；经 argparse 解析后必填子命令（catalog/card/export/import 等）之一，参数缺失或非法由 argparse 直接退出；返回进程退出码；
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="python -m md_cg.evidence",
+        description="跨节点证据存储：名片 / 导出 / 导入（v0.3）")
+    ap.add_argument("--root", default=None, help="认知图根（默认 MDCG_ROOT）")
+    ap.add_argument("--swarm", default=None, help="共享目录（默认 ~/.mdcg/swarm）")
+    ap.add_argument("--signers-file", default=None)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("catalog", help="自描述")
+    sub.add_parser("card", help="本节点名片")
+    sub.add_parser("publish", help="发布名片到共享目录")
+    sub.add_parser("peers", help="发现对端名片")
+
+    p_ex = sub.add_parser("export", help="导出证据包")
+    p_ex.add_argument("--subject", action="append", default=None)
+    p_ex.add_argument("--out", default=None, help="输出文件（默认写收件箱）")
+
+    p_im = sub.add_parser("import", help="导入证据包")
+    p_im.add_argument("path")
+
+    p_ls = sub.add_parser("ls", help="列已导入的跨节点证据")
+    p_ls.add_argument("--subject", default=None)
+    p_ls.add_argument("--source", default=None)
+    p_ls.add_argument("--limit", type=int, default=100)
+
+    a = ap.parse_args(argv)
+    cg = None
+    try:
+        if a.cmd == "catalog":
+            _print(catalog())
+        elif a.cmd == "card":
+            _print(card(a.root, signers_file=a.signers_file))
+        elif a.cmd == "publish":
+            _print(publish_card(a.root, swarm=a.swarm,
+                                signers_file=a.signers_file))
+        elif a.cmd == "peers":
+            _print(peers(a.swarm, root=a.root))
+        elif a.cmd == "export":
+            cg = _open_cg(a.root)
+            res = export_pack(cg, subjects=a.subject, swarm=a.swarm,
+                              signers_file=a.signers_file)
+            _print(write_pack(res["pack"], path=a.out, swarm=a.swarm)
+                   if a.out else res)
+        elif a.cmd == "import":
+            cg = _open_cg(a.root)
+            _print(import_pack(cg, a.path, swarm=a.swarm,
+                               signers_file=a.signers_file))
+        elif a.cmd == "ls":
+            cg = _open_cg(a.root)
+            _print(evidence(cg, subject=a.subject, source=a.source,
+                            limit=a.limit))
+    except (EvidenceError, _signer.SignerError) as e:
+        print(f"[md_cg.evidence] {e}", file=sys.stderr)
+        return 2
+    finally:
+        if cg is not None:
+            try:
+                cg.close()          # 落盘索引，保证跨进程可见
+            except Exception:       # noqa: BLE001 —— 关闭失败不掩盖主流程结果
+                pass
+    return 0
+
+
+if __name__ == "__main__":
     sys.exit(main())