@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/test_trust.py

@@ -0,0 +1,361 @@
+"""可验证记忆单元（trust）验收：状态机 / 依赖图 / 双时间轴 / 失效传播 / 闸门 / 输出协议。
+
+运行：python -m md_cg.test_trust   （或 python md_cg/test_trust.py）
+范式：无第三方依赖的直接运行脚本（assert + 计数 + 非零退出），对齐 md_cg/test_*.py。
+
+覆盖面（每个断言都在验「语义」而非「实现细节」）：
+  ① 纯函数裁决：can_transition / check / require_transition
+  ② as_deps 解析与 parse_time 容错
+  ③ validity 双时间轴四态
+  ④ state_of 缺省语义 + stamp 幂等
+  ⑤ set_state 端到端（负路由 / 幂等 / 审计留痕 / 保护节点）
+  ⑥ cg.add 覆写继承（全量重建 fm 不丢验证态与依赖）
+  ⑦ 依赖反查索引 + 缓存失效
+  ⑧ 一跳同步传播 mark_dependents（预演 / 落盘 / 幂等）
+  ⑨ 多跳异步 propagate（BFS 可达 / 默认预演）
+  ⑩ 写入闸门 E050 / E051 / 哨兵与自述豁免（真源 nodefile.declares_dependency；
+     收窄裁定 b：仅 `@<节点 id>` 显式引用算依赖声明，自然语言自述不算）
+  ⑪ 输出协议 statushdr（四态符号 / 开关）
+  ⑫ 巡检 patrol 只读 + catalog 自描述
+"""
+import json
+import os
+import shutil
+import sys
+import tempfile
+
+try:
+    from . import trust, statushdr, nodefile, writepipe
+    from .mdcg import MdCG
+except ImportError:                                  # 直接脚本运行
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from md_cg import trust, statushdr, nodefile, writepipe
+    from md_cg.mdcg import MdCG
+
+PASS = 0
+FAIL = []
+
+
+def ok(cond, label):
+    global PASS
+    if cond:
+        PASS += 1
+    else:
+        FAIL.append(label)
+        print("  FAIL: " + label)
+
+
+def eq(got, want, label):
+    ok(got == want, "%s（got=%r want=%r）" % (label, got, want))
+
+
+def phase(name):
+    print("--- " + name)
+
+
+A, B, C, D = ("mem_1789810000001", "mem_1789810000002",
+              "mem_1789810000003", "mem_1789810000004")
+
+
+def ccg(node, deps=None, **kw):
+    """构造一条 CCG 契约正文（六要素齐；子功能按 deps 给出，**显式 @ 引用形态**）。
+
+    注意：跨节点依赖的声明形态是 `@<节点 id>`（收窄裁定 b，2026-09-19）——
+    自然语言自述子功能不构成依赖声明，故此处必须带 `@`，否则本文件的闸门断言
+    测的就不是依赖链路了。
+    """
+    sub = ("依赖 " + "、".join("@" + d for d in deps)) if deps else "无"
+    return ("# 功能名：%s\n# 生效条件：无条件\n# 子功能：%s\n# 执行：无\n"
+            "# 验证方式：test\n# 不适用条件：无\n\n正文。" % (node, sub))
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="mdcg_test_trust_")
+    cg = MdCG(root=os.path.join(tmp, "kg"))
+
+    # ---------------------------------------------------------------- ① 纯函数裁决
+    phase("① 裁决")
+    ok(trust.can_transition("unverified", "verified"), "unverified→verified 合法")
+    ok(trust.can_transition("verified", "doubted"), "verified→doubted 合法")
+    ok(trust.can_transition("unverified", "doubted"), "unverified→doubted 合法（负证据）")
+    ok(not trust.can_transition("verified", "unverified"), "verified→unverified 拒绝（回落）")
+    ok(not trust.can_transition("doubted", "expired"), "doubted→expired 拒绝（跳级）")
+    ok(not trust.can_transition("unverified", "nope"), "未知状态拒绝")
+    eq(trust.check("verified", "verified")[1], "noop", "同状态查得 noop")
+    eq(trust.check("verified", "unverified")[1], "illegal_transition", "非法迁移码")
+    ok(trust.check("verified", "unverified", protected=True, override=False)[0] is False,
+       "受保护节点拒绝降级")
+    ok(trust.check("unverified", "verified", protected=True, override=False)[0] is True,
+       "受保护节点允许升级")
+    ok(trust.check("verified", "doubted", protected=True, override=True)[0] is True,
+       "override 放行合法降级（verified→doubted）")
+    ok(trust.check("verified", "unverified", protected=True, override=True)[0] is False,
+       "override 不豁免非法迁移（合法性优先于保护）")
+    raised = False
+    try:
+        trust.require_transition("verified", "unverified")
+    except trust.TrustError:
+        raised = True
+    ok(raised, "require_transition 非法即抛 TrustError")
+    ok(trust.is_downgrade("verified", "doubted"), "verified→doubted 是降级")
+
+    # ---------------------------------------------------------------- ② 解析容错
+    phase("② 解析")
+    eq(trust.as_deps(["b", "a", "b"]), ["a", "b"], "as_deps 列表去重排序")
+    eq(trust.as_deps("x"), ["x"], "as_deps 单串")
+    eq(trust.as_deps(None), [], "as_deps None")
+    eq(trust.as_deps([None, ""]), [], "as_deps 过滤空值")
+    eq(trust.as_deps("a, b"), ["a", "b"], "as_deps 逗号串")
+    ok(trust.parse_time("2020-01-01") is not None, "parse_time 日期串")
+    ok(trust.parse_time(None) is None, "parse_time None")
+    ok(trust.parse_time(1700000000.0) == 1700000000.0, "parse_time 数字直通")
+    ok(trust.parse_time("不是时间") is None, "parse_time 非法容错")
+
+    # ---------------------------------------------------------------- ③ 双时间轴
+    phase("③ 时间轴")
+    eq(trust.validity({"valid_from": "2020-01-01", "valid_until": "2030-01-01"})[0],
+       "active", "区间内=active")
+    eq(trust.validity({"valid_from": "2099-01-01"})[0], "not_yet", "未来=not_yet")
+    eq(trust.validity({"valid_until": "2001-01-01"})[0], "expired", "过去=expired")
+    eq(trust.validity({})[0], "unknown", "无时间轴=unknown（不受限，非 active）")
+    eq(trust.validity(None)[0], "unknown", "非 dict 亦 unknown（不猜测）")
+    # 2026-09-19 阶段一：规范键优先 + 别名回落 + 信念时间（第三类语义）物理隔离
+    eq(trust.validity({"effective_from": "2099-01-01"})[0], "not_yet",
+       "规范键起点生效")
+    eq(trust.validity({"effective_from": "2099-01-01",
+                       "valid_from": "2020-01-01"})[0], "not_yet",
+       "规范键优先于历史键")
+    eq(trust.validity({"effective_until": "坏值",
+                       "valid_until": "2001-01-01"})[0], "expired",
+       "规范键不可解析 → 继续回落别名（不猜测定案）")
+    eq(trust.validity({"effective_until": "2001-01-01"})[0], "expired",
+       "规范键终点生效")
+    eq(trust.validity({"believed_at": "2001-01-01"})[0], "unknown",
+       "信念时间不参与时效判定（第三类语义）")
+    ok(trust.believed_at({"believed_at": "2020-01-01"}) is not None
+       and trust.believed_at({}) is None, "believed_at 读取器（epoch/None）")
+
+    # ---------------------------------------------------------------- ④ 缺省与幂等
+    phase("④ 缺省/幂等")
+    eq(trust.state_of({}), "unverified", "缺字段按 unverified")
+    eq(trust.state_of(None), "unverified", "None 按 unverified")
+    fm = {}
+    r1 = trust.stamp(fm, "verified", reason="t", actor="t")
+    eq(r1[1], "ok", "stamp 首次迁移 code=ok")
+    eq(trust.state_of(fm), "verified", "stamp 落字段")
+    before = json.dumps(fm, sort_keys=True, default=str)
+    r2 = trust.stamp(fm, "verified", reason="t", actor="t")
+    eq(json.dumps(fm, sort_keys=True, default=str), before, "同状态 stamp 不重复写")
+    eq(r2[1], "noop", "同状态 stamp code=noop（幂等不写盘）")
+
+    # ---------------------------------------------------------------- ⑤ set_state 端到端
+    phase("⑤ set_state")
+    missing = trust.set_state(cg, "mem_not_exist", "verified")
+    ok(missing.get("ok") is False and missing.get("error") == "node_not_found",
+       "不存在节点负路由 node_not_found")
+    cg.add(A, ccg("上游"), layer="knowledge", tags=["t1"])
+    r = cg.set_verification(A, "verified", reason="首次", actor="tester",
+                            evidence="ev-1", method="test")
+    ok(r.get("ok") and r.get("changed"), "set_verification verified 成功")
+    eq(trust.state_of((cg.get(A) or {}).get("frontmatter")), "verified",
+       "fm 落 verification_state")
+    eq((cg.index["nodes"][A] or {}).get("verification_state"), "verified",
+       "索引快照同步（免读文件）")
+    r2 = cg.set_verification(A, "verified", reason="重复", actor="tester")
+    ok(r2.get("ok") and r2.get("changed") is False, "幂等：同状态 changed=False")
+    led = trust.load_ledger(cg, node_id=A)
+    ok(len(led) >= 1, "审计台账留痕")
+    ok(all("to" in x for x in led), "台账含 to 字段")
+    bad = cg.set_verification(A, "unverified", reason="回落", actor="tester")
+    ok(bad.get("ok") is False, "非法迁移负路由不抛")
+
+    # ---------------------------------------------------------------- ⑥ 覆写继承
+    phase("⑥ 覆写继承")
+    cg.add(B, ccg("下游", [A]), layer="knowledge", depends_on=[A],
+           valid_from="2020-01-01", valid_until="2030-01-01")
+    cg.set_verification(B, "verified", reason="t", actor="t")
+    cg.add(B, ccg("下游 v2", [A]), layer="knowledge", depends_on=[A])
+    fmb = (cg.get(B) or {}).get("frontmatter") or {}
+    eq(trust.state_of(fmb), "verified", "覆写后验证态继承（防静默打回）")
+    eq(fmb.get("depends_on"), [A], "覆写后依赖继承")
+    eq(fmb.get("valid_from"), "2020-01-01", "覆写后时间轴继承")
+    # 阶段一：规范键与信念时间的覆写继承（同 lifecycle/verification 的坑）
+    cg.add(B, ccg("下游 v3", [A]), layer="knowledge", depends_on=[A],
+           effective_from="2021-01-01", effective_until="2031-01-01",
+           believed_at="2022-01-01")
+    fmb3 = (cg.get(B) or {}).get("frontmatter") or {}
+    eq(fmb3.get("effective_from"), "2021-01-01", "新规范参数落规范键")
+    eq("valid_from" in fmb3, False, "落规范键时剔同族历史键（禁同族双写歧义）")
+    eq(fmb3.get("believed_at"), "2022-01-01", "信念时间写入落 believed_at")
+    cg.add(B, ccg("下游 v4", [A]), layer="knowledge", depends_on=[A])
+    fmb4 = (cg.get(B) or {}).get("frontmatter") or {}
+    eq(fmb4.get("effective_from"), "2021-01-01", "覆写后规范起点继承")
+    eq(fmb4.get("effective_until"), "2031-01-01", "覆写后规范终点继承")
+    eq(fmb4.get("believed_at"), "2022-01-01", "覆写后信念时间继承")
+
+    # ---------------------------------------------------------------- ⑦ 反查索引
+    phase("⑦ 反查索引")
+    idx = trust.dependents_index(cg)
+    ok(B in idx.get(A, []), "反查：谁依赖 A")
+    eq(trust.deps_of(cg, B), [A], "正查：B 依赖谁")
+    cg.add(D, ccg("新下游", [A]), layer="knowledge", depends_on=[A])
+    trust.invalidate_cache(cg)
+    ok(D in trust.dependents_index(cg).get(A, []), "写后缓存失效可重建")
+
+    # ---------------------------------------------------------------- ⑧ 一跳传播
+    phase("⑧ 一跳同步传播")
+    dry = trust.mark_dependents(cg, A, reason="预演", apply=False)
+    ok(dry.get("dry_run") and len(dry.get("dependents") or []) >= 2,
+       "预演列出全部下游且不改盘")
+    eq(dry.get("dependents"), sorted(dry.get("dependents") or []), "下游有序输出")
+    ok(trust.state_of((cg.get(B) or {}).get("frontmatter")) == "verified",
+       "预演未改盘（B 仍 verified）")
+    wet = trust.mark_dependents(cg, A, reason="上游变动", actor="tester", trigger="t")
+    ok(wet.get("changed") >= 2, "落盘：下游全部标存疑")
+    eq(trust.state_of((cg.get(B) or {}).get("frontmatter")), "doubted", "B 已 doubted")
+    eq(trust.state_of((cg.get(D) or {}).get("frontmatter")), "doubted", "D 已 doubted")
+    again = trust.mark_dependents(cg, A, reason="重复", actor="tester")
+    eq(again.get("changed"), 0, "重复传播幂等（changed=0）")
+    none_dep = trust.mark_dependents(cg, C, reason="无下游")
+    eq(none_dep.get("changed"), 0, "无下游不报错")
+
+    # ---------------------------------------------------------------- ⑨ 多跳传播
+    phase("⑨ 多跳异步传播")
+    cg.add(C, ccg("中继", [D]), layer="knowledge", depends_on=[D])
+    cg.set_verification(D, "verified", reason="t", actor="t")
+    cg.set_verification(C, "verified", reason="t", actor="t")
+    cg.set_verification(A, "expired", reason="时间到", actor="tester")
+    dry2 = trust.propagate(cg)
+    ok(dry2.get("dry_run"), "propagate 默认预演")
+    ok(dry2.get("reachable", 0) >= 2, "预演可达多跳下游")
+    wet2 = trust.propagate(cg, apply=True, actor="tester")
+    ok(wet2.get("dry_run") is False, "apply=True 落盘")
+    eq(trust.state_of((cg.get(B) or {}).get("frontmatter")), "doubted",
+       "一跳下游 doubted")
+    eq(trust.state_of((cg.get(C) or {}).get("frontmatter")), "doubted",
+       "二跳下游 doubted（BFS 可达）")
+
+    # ---------------------------------------------------------------- ⑩ 写入闸门
+    phase("⑩ 写入闸门")
+    ok(nodefile.declares_dependency(ccg("x", [A])), "显式 @ 引用判为 True")
+    ok(not nodefile.declares_dependency(ccg("x")), "「无」哨兵判为 False")
+    ok(not nodefile.declares_dependency("# 功能名：x\n\n正文"), "无该行判为 False")
+    ok(not nodefile.declares_dependency("# 子功能：无（不依赖其他单元）"),
+       "哨兵带括号说明仍为 False")
+    # 收窄裁定 b（2026-09-19）：区分「自述子功能」与「跨节点依赖」——只有显式
+    # `@<节点 id>` 引用才构成依赖声明；自然语言自述不算。否则 CCG 编译产物（六要素
+    # 必含「子功能」行）落库后会被 E050 永久锁死（test_ccgc V16f 即该死锁的实证）。
+    ok(not nodefile.is_dep_sentinel("无法确定依赖范围"),
+       "「无法确定」不得误判为哨兵")
+    ok(not nodefile.declares_dependency("# 子功能：无法确定依赖范围"),
+       "自然语言自述不算依赖声明（收窄 b）")
+    ok(not nodefile.declares_dependency(
+        "# 子功能：按扩展名把文件路由到对应摄取器"),
+       "CCG 编译产物形态的自述子功能不构成依赖声明（V16f 死锁根因）")
+    ok(not nodefile.declares_dependency("# 子功能：联系 user@example.com"),
+       "邮箱形态的 @ 不误判为引用（@ 左侧为标识符字符）")
+    ok(not nodefile.declares_dependency("# 子功能：@所有人 知悉"),
+       "中文 @ 不误判为引用（id 须以 [A-Za-z0-9_] 起头）")
+    eq(nodefile.dep_refs("依赖 @mem_a、@code_b 与 @mem_a（回指 @mem_a）"),
+       ["mem_a", "code_b"], "多引用去重保序提取")
+    eq(nodefile.dep_refs("@code_3552109b6163"), ["code_3552109b6163"],
+       "行首 @ 命中（左侧非标识符字符即可）")
+    eq(nodefile.dep_refs("无"), [], "哨兵值提取为空列表")
+    g1 = writepipe._gate_deps({"cg": cg, "nid": "mem_x1",
+                               "a": {"content": ccg("x", [A]),
+                                     "depends_on": [A]}, "verdict": {}})
+    ok(g1 is None, "声明且目标可解析→放行")
+    g2 = writepipe._gate_deps({"cg": cg, "nid": "mem_x2",
+                               "a": {"content": ccg("x", [A]),
+                                     "depends_on": A}, "verdict": {}})
+    ok(g2 is None, "单值形态同样放行（as_deps 容错）")
+    g2b = writepipe._gate_deps({"cg": cg, "nid": "mem_x2b",
+                                "a": {"content": ccg("x", [A]),
+                                      "depends_on": "%s, mem_ghost2" % A},
+                                "verdict": {}})
+    eq((g2b or {}).get("error"), "E051", "逗号串逐项解析（含悬空即拒）")
+    g3 = writepipe._gate_deps({"cg": cg, "nid": "mem_x3",
+                               "a": {"content": "# 功能名：x\n# 子功能：依赖 @mem_ghost\n"},
+                               "verdict": {}})
+    eq((g3 or {}).get("error"), "E050", "显式 @ 声明却无字段→E050 硬拒")
+    ok((g3 or {}).get("committed") is False, "硬拒体 committed=False")
+    g3b = writepipe._gate_deps({"cg": cg, "nid": "mem_x3b",
+                                "a": {"content": "# 功能名：x\n# 子功能：依赖某物\n"},
+                                "verdict": {}})
+    ok(g3b is None, "自然语言自述子功能不触发闸门（收窄 b 的行为面）")
+    g4 = writepipe._gate_deps({"cg": cg, "nid": "mem_x4",
+                               "a": {"content": ccg("x", ["mem_ghost"]),
+                                     "depends_on": ["mem_ghost"]}, "verdict": {}})
+    eq((g4 or {}).get("error"), "E051", "依赖悬空→E051 硬拒")
+    eq((g4 or {}).get("missing"), ["mem_ghost"], "E051 回带缺失目标")
+    g5 = writepipe._gate_deps({"cg": cg, "nid": "mem_x5",
+                               "a": {"content": ccg("x")}, "verdict": {}})
+    ok(g5 is None, "哨兵值不触发闸门")
+    names = writepipe.default_pipeline().names()
+    ok("deps" in str(names) and "trust" in str(names), "闸与观察者已注册默认链")
+
+    # ---------------------------------------------------------------- ⑪ 输出协议
+    phase("⑪ 输出协议")
+    head_b = statushdr.render(cg, B)
+    ok(bool(head_b), "doubted 节点有状态头")
+    ok(statushdr.MARK_DOUBTED in head_b, "状态头含存疑符号")
+    head_a = statushdr.render(cg, A)
+    ok(statushdr.MARK_ABNORMAL in head_a or statushdr.MARK_EXPIRED in head_a
+       or bool(head_a), "异常/过期节点有状态头")
+    ok(isinstance(statushdr.attach_heads(cg, {"node_id": B}), dict), "attach_heads 返回 dict")
+    ok(statushdr.enabled(), "状态头默认开启")
+
+    # ---------------------------------------------------------------- ⑫ 巡检与自描述
+    phase("⑫ 巡检/自描述")
+    rep = trust.patrol(cg)
+    ok(rep.get("readonly") is True, "巡检只读标记")
+    ok(rep.get("nodes", 0) >= 4, "巡检统计节点数")
+    ok(rep.get("doubted_count", 0) >= 2, "巡检统计存疑积压")
+    snap = trust.state_of((cg.get(B) or {}).get("frontmatter"))
+    trust.patrol(cg)
+    eq(trust.state_of((cg.get(B) or {}).get("frontmatter")), snap, "巡检不改状态")
+    cat = trust.catalog(cg.root)
+    for key in ("layer", "question", "states", "state_field", "deps_field",
+                "time_fields", "ledger", "discipline"):
+        ok(key in cat, "catalog 含键 " + key)
+    ok("unverified" in cat["states"] and "doubted" in cat["states"], "catalog 状态枚举")
+    s = trust.summary(cg)
+    ok(isinstance(s, dict) and "doubted" in s, "summary 轻量摘要")
+    de = trust.describe(cg, B)
+    ok(de.get("ok") and de.get("depends_on") == [A], "describe 单节点全貌")
+    ok(de.get("depended_by") is not None, "describe 含反查")
+
+    # ---------------------------------------------------------------- ⑬ MCP 面接线
+    phase("⑬ MCP 面：status op / 状态头 / 写闸硬拒")
+    from md_cg import mcp_server as MS
+    st = MS._cg_call(cg, {"op": "status", "node_id": A})
+    eq(st.get("ok"), True, "op=status 单节点返回 ok")
+    eq(st.get("state") or st.get("verification_state"), "expired", "status 透出验证态")
+    ok(bool(st.get("status_head")), "status 带状态头")
+    ok(isinstance(st.get("ledger"), list), "status 带履历台账")
+    ok("depended_by" in st or "dependents" in st, "status 带下游反查")
+    sm = MS._cg_call(cg, {"op": "status"})
+    ok(isinstance(sm.get("summary"), dict), "op=status 摘要形态返回 summary")
+    ok("status_head" in sm or "status_heads" in sm, "摘要形态亦挂状态头")
+    sl = MS._cg_call(cg, {"op": "status", "action": "ledger"})
+    ok(isinstance(sl.get("rows"), list), "action=ledger 读台账")
+
+    # 写闸硬拒（MCP 端到端）：正文声明依赖却无可解析目标 → E050 / 悬空 → E051
+    r50 = MS._cg_call(cg, {"op": "write", "content": ccg("闸门缺声明", [A]),
+                           "content_kind": "text", "layer": "knowledge"})
+    eq((r50 or {}).get("error"), "E050", "写闸硬拒 E050（声明依赖却无 depends_on）")
+    r51 = MS._cg_call(cg, {"op": "write", "content": ccg("闸门悬空", ["mem_ghost_zz"]),
+                           "content_kind": "text", "layer": "knowledge",
+                           "depends_on": ["mem_ghost_zz"]})
+    eq((r51 or {}).get("error"), "E051", "写闸硬拒 E051（依赖目标悬空）")
+    ok(not (cg.get("mem_ghost_zz") or {}), "悬空目标未落盘（闸门真拒非事后回滚）")
+
+    shutil.rmtree(tmp, ignore_errors=True)
+    print("\nPASS=%d FAIL=%d" % (PASS, len(FAIL)))
+    if FAIL:
+        for f in FAIL:
+            print("  - " + f)
+        sys.exit(1)
+
+
+main()

package/md_cg/test_twophase.py

@@ -0,0 +1,286 @@
+# -*- coding: utf-8 -*-
+"""test_twophase · 写入两段式提交（Pi 可学习优点 ③）
+
+验收口径（交接文档 §3③）：
+- 写入在**闸门通过后先落 intent**（含内容指纹），落盘完成再落 outcome；
+- 「kill -9 模拟半途写入后重启」→ 对账**正确补账**（内容确已落盘）或
+  **如实标记**（未落盘 / 指纹不符），不假装成功；
+- 对账幂等、账本 append-only、不重放写入；
+- 未落盘的分支（闸门拒绝 / 入队）不产生 intent——没打算写就不记账。
+
+运行：python -m md_cg.test_twophase
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import traceback
+
+from . import twophase, writepipe
+from .mdcos import MdCGSecure
+from .security import Principal
+
+_ok = 0
+_fail = []
+_seq = [0]
+
+
+def check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("[ok] " + name)
+    else:
+        _fail.append(name)
+        print("[FAIL] %s  · %s" % (name, str(detail)[:240]))
+
+
+def _mk_cg(tmp, role="designer"):
+    _seq[0] += 1
+    root = os.path.join(tmp, "root_%02d_%s" % (_seq[0], role))
+    p = Principal(tenant="default", actor="t_" + role, role=role,
+                  can_write=(role != "guest"), can_admin=(role == "designer"))
+    return MdCGSecure(root, principal=p)
+
+
+def _policy(tmp, required=("PASSED",), forbidden=("FORBIDDEN_WORD",)):
+    path = os.path.join(tmp, "policy.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({"forbidden": list(forbidden),
+                   "required": list(required)}, f)
+    os.environ["MDCG_POLICY_FILE"] = path
+    return path
+
+
+def _lines(cg):
+    p = twophase.log_path(cg)
+    if not os.path.isfile(p):
+        return []
+    with open(p, encoding="utf-8", errors="replace") as f:
+        return [x for x in f.read().splitlines() if x.strip()]
+
+
+def _recs(cg):
+    return twophase.records(cg)
+
+
+def _idx(cg, nid):
+    return (cg.index.get("nodes") or {}).get(nid) or {}
+
+
+def _phases(cg, nid=None):
+    return [r.get("phase") for r in _recs(cg)
+            if nid is None or r.get("id") == nid]
+
+
+def _run(tmp):
+    _policy(tmp)
+    pipe = writepipe.install_default_gates(writepipe.WritePipeline())
+
+    # ---------- ① 正常落盘：intent + outcome 成对 ----------
+    cg = _mk_cg(tmp)
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "两段式正常落盘 PASSED",
+                            "layer": "knowledge"})
+    nid = out.get("id")
+    check("①1 写入成功（committed）", out.get("committed") is True, out)
+    recs = _recs(cg)
+    ph = [r["phase"] for r in recs if r.get("id") == nid]
+    check("①2 账本两行成对（intent → outcome）", ph == ["intent", "outcome"], ph)
+    intent = [r for r in recs if r.get("id") == nid
+              and r["phase"] == "intent"][0]
+    oc = [r for r in recs if r.get("id") == nid and r["phase"] == "outcome"][0]
+    check("①3 intent 带内容指纹（对账的判据）",
+          bool(intent.get("content_hash")), intent)
+    check("①4 outcome 记 committed + 同 iid",
+          oc.get("status") == twophase.STATUS_COMMITTED
+          and oc.get("iid") == intent.get("iid"), oc)
+    check("①5 指纹走 nodefile 唯一真源（含写盘尾换行归一）",
+          intent.get("content_hash")
+          == twophase.nodefile.content_hash("两段式正常落盘 PASSED"),
+          (intent.get("content_hash"),
+           twophase.nodefile.content_hash("两段式正常落盘 PASSED")))
+    check("①6 正常写入后无未结清意图", cg.pending_writes() == [])
+
+    # ---------- ② intent 真的**先于**落盘（真实执行路径内观测） ----------
+    cg2 = _mk_cg(tmp)
+    _orig = writepipe._executor
+    seen = {}
+
+    def _probe(ctx):
+        seen["has_intent"] = any(
+            r.get("phase") == "intent" and r.get("id") == ctx["nid"]
+            for r in _recs(ctx["cg"]))
+        seen["has_outcome"] = any(
+            r.get("phase") == "outcome" and r.get("id") == ctx["nid"]
+            for r in _recs(ctx["cg"]))
+        seen["node_exists"] = bool(ctx["cg"].get(ctx["nid"]))
+        return _orig(ctx)
+
+    writepipe._executor = _probe
+    try:
+        pipe.execute(cg2, {"content_kind": "text",
+                           "content": "先行持久化探针 PASSED",
+                           "layer": "knowledge"})
+    finally:
+        writepipe._executor = _orig
+    check("②1 进入执行器时 intent 已落账（先行持久化成立）",
+          seen.get("has_intent") is True, seen)
+    check("②2 进入执行器时**尚无** outcome 且节点未落盘",
+          seen.get("has_outcome") is False
+          and seen.get("node_exists") is False, seen)
+
+    # ---------- ③ 半途崩溃：落盘已完成、outcome 未写 ----------
+    cg3 = _mk_cg(tmp)
+    nid3 = "mem_2pc_c3"
+    tok = twophase.begin(cg3, nid3, "崩溃在落盘之后 PASSED", layer="knowledge",
+                         actor="test:crash")
+    cg3.add(nid3, "崩溃在落盘之后 PASSED", layer="knowledge")
+    check("③1 崩溃现场：有 intent 无 outcome",
+          _phases(cg3, nid3) == ["intent"]
+          and len(cg3.pending_writes()) == 1)
+    rep = cg3.reconcile_writes()
+    check("③2 对账补账（内容指纹吻合 → committed）",
+          rep.get("unpaired") == 1 and rep.get("committed") == 1
+          and rep.get("interrupted") == 0, rep)
+    check("③3 补出的 outcome 标 reconciled + 判据可审计",
+          any(r.get("phase") == "outcome" and r.get("reconciled")
+              and r.get("reason") == twophase.R_NODE_OK
+              for r in _recs(cg3)), _recs(cg3)[-1])
+    check("③4 对账后 pending 归零",
+          cg3.pending_writes() == [])
+
+    # ---------- ④ 半途崩溃：根本没落盘 ----------
+    cg4 = _mk_cg(tmp)
+    twophase.begin(cg4, "mem_2pc_c4", "崩溃在落盘之前 PASSED",
+                   layer="knowledge")
+    rep4 = cg4.reconcile_writes()
+    check("④1 未落盘 → 如实标记 interrupted（不假装成功）",
+          rep4.get("unpaired") == 1 and rep4.get("interrupted") == 1
+          and rep4.get("committed") == 0, rep4)
+    check("④2 interrupted 判据 = node_missing",
+          rep4["details"][0]["reason"] == twophase.R_NODE_MISSING, rep4)
+    check("④3 未落盘节点确实不在库（标记与实际一致）",
+          cg4.get("mem_2pc_c4") is None)
+
+    # ---------- ⑤ 指纹不符：落了别的正文 ----------
+    cg5 = _mk_cg(tmp)
+    twophase.begin(cg5, "mem_2pc_c5", "意图写的是这一段 PASSED")
+    cg5.add("mem_2pc_c5", "实际落的是另一段 PASSED", layer="knowledge")
+    rep5 = cg5.reconcile_writes()
+    check("⑤1 指纹不符 → interrupted（content_mismatch）",
+          rep5.get("interrupted") == 1
+          and rep5["details"][0]["reason"] == twophase.R_MISMATCH, rep5)
+    check("⑤2 对账**不覆盖**既有正文（只标记不重放）",
+          "实际落的是另一段" in (cg5.get("mem_2pc_c5") or {}).get("content", ""))
+
+    # ---------- ⑥ dry-run / 幂等 / append-only ----------
+    cg6 = _mk_cg(tmp)
+    twophase.begin(cg6, "mem_2pc_c6", "dry-run 用例 PASSED")
+    before = _lines(cg6)
+    dry = cg6.reconcile_writes(apply=False)
+    check("⑥1 dry-run 报告未结清但不改账本",
+          dry.get("unpaired") == 1 and dry.get("applied") is False
+          and _lines(cg6) == before, dry)
+    cg6.reconcile_writes()
+    n_after_first = len(_lines(cg6))
+    rep6b = cg6.reconcile_writes()
+    check("⑥2 对账幂等（二次无未结清、不追加行）",
+          rep6b.get("unpaired") == 0
+          and len(_lines(cg6)) == n_after_first, rep6b)
+    check("⑥3 账本 append-only（原记录逐字保留）",
+          _lines(cg6)[:len(before)] == before)
+    snap = _lines(cg6)
+    cg6.pending_writes()
+    check("⑥4 pending 只读（不改账本）", _lines(cg6) == snap)
+
+    # ---------- ⑦ 执行器抛异常 → outcome=error，异常照抛 ----------
+    cg7 = _mk_cg(tmp, role="guest")     # guest 无写权限 → 库层拒绝
+    pipe7 = writepipe.WritePipeline()   # 不装闸：直接打执行器
+    raised = None
+    try:
+        pipe7.execute(cg7, {"content": "无权限写入 PASSED",
+                            "layer": "knowledge"})
+    except Exception as exc:            # AccessDenied 或其子类
+        raised = type(exc).__name__
+    check("⑦1 库层权限拒绝照抛（两段式不改错误语义）", raised is not None,
+          raised)
+    check("⑦2 失败也留痕：outcome=error 且无 committed",
+          any(r.get("phase") == "outcome"
+              and r.get("status") == twophase.STATUS_ERROR
+              for r in _recs(cg7)), _recs(cg7))
+    check("⑦3 失败不留未结清意图（已配对）", cg7.pending_writes() == [])
+
+    # ---------- ⑧ 未落盘的分支不记账 ----------
+    cg8 = _mk_cg(tmp)
+    out8 = pipe.execute(cg8, {"content_kind": "text",
+                              "content": "这段含 FORBIDDEN_WORD 应被拒",
+                              "layer": "knowledge"})
+    check("⑧1 闸门拒绝分支：committed=False",
+          out8.get("committed") is False, out8.get("moved_to"))
+    check("⑧2 未落盘 → **不产生** intent（没打算写就不记账）",
+          _phases(cg8) == [], _recs(cg8))
+    check("⑧3 对账在空账本上恒无未结清",
+          cg8.reconcile_writes().get("unpaired") == 0)
+
+    # ---------- ⑨ gated 替代执行路径也成对 ----------
+    cg9 = _mk_cg(tmp)
+    out9 = pipe.execute(cg9, {"content_kind": "text",
+                              "content": "gated 主动遗忘路径 PASSED",
+                              "layer": "contextual", "gated": True,
+                              "importance": 0.5})
+    nid9 = out9.get("id")
+    ph9 = _phases(cg9, nid9)
+    check("⑨1 gated 路径账本成对（intent → outcome）",
+          ph9 == ["intent", "outcome"], ph9)
+    oc9 = [r for r in _recs(cg9)
+           if r.get("id") == nid9 and r["phase"] == "outcome"][0]
+    check("⑨2 结局与 verdict 一致（committed 当且仅当落盘）",
+          (oc9.get("status") == twophase.STATUS_COMMITTED)
+          == bool(out9.get("committed")), (oc9, out9.get("committed")))
+    check("⑨3 gated 结局无未结清（自己落盘的路径也结清）",
+          cg9.pending_writes() == [])
+
+    # ---------- ⑩ 边界 ----------
+    cg10 = _mk_cg(tmp)
+    check("⑩1 空账本：records/pending/reconcile 均不炸",
+          _recs(cg10) == [] and cg10.pending_writes() == []
+          and cg10.reconcile_writes().get("unpaired") == 0)
+    bad = os.path.join(cg10.root, "_write_2pc.jsonl")
+    with open(bad, "a", encoding="utf-8") as f:
+        f.write("{坏行不是 json\n")
+    check("⑩2 坏行跳过不炸（账本读侧容错）",
+          isinstance(_recs(cg10), list))
+    check("⑩3 指纹算法与 nodefile 同源（唯一真源，防漂移）",
+          twophase.nodefile.content_hash("abc")
+          == __import__("hashlib").sha256(b"abc").hexdigest()[:12])
+    check("⑩4 账本文件在 root 下（随记忆库一起备份/迁移）",
+          os.path.dirname(twophase.log_path(cg10)) == cg10.root)
+    check("⑩5 对账只增行不删行（append-only 结构保证）",
+          len(_lines(cg10)) >= 1 and all(l.strip() for l in _lines(cg10)))
+
+
+def main():
+    tmp = tempfile.mkdtemp(prefix="twophase_")
+    old = os.environ.pop("MDCG_POLICY_FILE", None)
+    try:
+        _run(tmp)
+    except Exception:
+        traceback.print_exc()
+        _fail.append("未捕获异常")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+        if old is not None:
+            os.environ["MDCG_POLICY_FILE"] = old
+        else:
+            os.environ.pop("MDCG_POLICY_FILE", None)
+    print("\ntest_twophase: %d 通过 / %d 失败" % (_ok, len(_fail)))
+    if _fail:
+        print("失败项：" + "、".join(_fail))
+    raise SystemExit(1 if _fail else 0)
+
+
+if __name__ == "__main__":
+    main()