@furongjun1999/dsh-memory 0.4.7 → 0.4.8

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()

package/md_cg/test_writepipe.py

@@ -0,0 +1,210 @@
+# -*- coding: utf-8 -*-
+"""写入路径拦截器链（writepipe）验收：Pi 钩子化移植（交接文档 §3⑥）。
+
+验收口径：
+- 默认链行为与重构前 _cg_dispatch write 分支逐字节一致
+  （ACCEPT 直写 / REJECT 负记忆 / DEFER 入队 + 幂等去重联动 / gated 闸 /
+  冲突 cvd 透传）；
+- 新增/移除一个拦截器不改核心文件（register/unregister 即插即拔）；
+- 角色/层权限校验结构上不可被拦截器绕过（反面清单：信任必须结构强制）；
+- REWRITE（拦截器改写 ctx["a"]["content"]）/ 链序 / 短路 / after 观测者。
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import traceback
+
+from . import writepipe
+from .mdcos import MdCGSecure
+from .security import AccessDenied, Principal
+
+_ok = 0
+_bad = []
+_seq = [0]
+
+
+def _check(name, cond, detail=""):
+    global _ok
+    if cond:
+        _ok += 1
+        print("  ok   %s" % name)
+    else:
+        _bad.append("%s %s" % (name, detail))
+        print("  FAIL %s %s" % (name, detail))
+
+
+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 main():
+    tmp = tempfile.mkdtemp(prefix="writepipe_")
+    old_policy = os.environ.pop("MDCG_POLICY_FILE", None)
+    try:
+        _run(tmp)
+    except Exception:
+        traceback.print_exc()
+        _bad.append("未捕获异常")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+        if old_policy is not None:
+            os.environ["MDCG_POLICY_FILE"] = old_policy
+        else:
+            os.environ.pop("MDCG_POLICY_FILE", None)
+    print("\nwritepipe 验收：%d 通过%s" % (
+        _ok, ("，%d 失败：%s" % (len(_bad), "; ".join(_bad))) if _bad else ""))
+    return 1 if _bad else 0
+
+
+def _run(tmp):
+    policy = _policy(tmp)
+
+    # ---------- 1 默认链：与重构前 write 分支行为一致 ----------
+    pipe = writepipe.install_default_gates(writepipe.WritePipeline())
+    cg = _mk_cg(tmp)
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "要素齐全 PASSED",
+                            "layer": "knowledge"})
+    _check("默认链ACCEPT直写", out.get("committed") is True and out.get("ok") is True,
+           repr(out))
+    _check("冲突闸cvd透传", isinstance(out.get("consistency"), dict), repr(out))
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "含 FORBIDDEN_WORD 的违禁内容",
+                            "layer": "knowledge"})
+    _check("REJECT负记忆", out.get("moved_to") == "rejected"
+           and out.get("committed") is False, repr(out))
+
+    # DEFER（无规则文件 → 无法判定 → 入审核队列）+ 幂等去重联动
+    os.environ.pop("MDCG_POLICY_FILE", None)
+    a = {"content_kind": "text", "content": "无规则可判的内容",
+         "layer": "knowledge"}
+    out1 = pipe.execute(cg, dict(a))
+    _check("DEFER入队", out1.get("moved_to") == "review_queue"
+           and bool(out1.get("pid")), repr(out1))
+    out2 = pipe.execute(cg, dict(a))
+    _check("幂等去重联动", out2.get("dedup") is True
+           and out2.get("dup_of") == out1.get("pid"), repr(out2))
+    os.environ["MDCG_POLICY_FILE"] = policy
+
+    out = pipe.execute(cg, {"content_kind": "text",
+                            "content": "PASSED 情境记忆", "gated": True,
+                            "layer": "contextual"})
+    _check("gated闸代执行", "gate" in out, repr(out))
+
+    # ---------- 2 注册/移除拦截器不改核心文件 ----------
+    singleton = writepipe.default_pipeline()
+
+    def _block_skipme(ctx):
+        if "SKIPME" in (ctx["a"].get("content") or ""):
+            return {"ok": False, "committed": False,
+                    "moved_to": "hook_blocked", "by": "test_block"}
+        return None
+
+    singleton.register_before("test_block", _block_skipme)
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("注册即拦", out.get("moved_to") == "hook_blocked", repr(out))
+    singleton.unregister_before("test_block")
+    out = singleton.execute(cg, {"content_kind": "text",
+                                 "content": "PASSED SKIPME",
+                                 "layer": "knowledge"})
+    _check("移除即恢复(核心文件零改动)", out.get("committed") is True, repr(out))
+    _check("单例默认链", singleton.names()["before"]
+           == ["audit", "consistency", "gated"],
+           repr(singleton.names()))
+
+    # ---------- 3 链序 / 短路 / REWRITE ----------
+    p3 = writepipe.WritePipeline()
+    order = []
+    p3.register_before("g1", lambda ctx: order.append("g1") or None)
+    p3.register_before("g2", lambda ctx: order.append("g2") or None)
+    p3.register_before("g3", lambda ctx: order.append("g3")
+                       or {"ok": False, "moved_to": "halt"})
+    cg3 = _mk_cg(tmp)
+    out = p3.execute(cg3, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("链序按注册序", order == ["g1", "g2", "g3"], repr(order))
+    _check("终态短路不落盘", out.get("moved_to") == "halt"
+           and "id" not in out and "committed" not in out, repr(out))
+
+    p4 = writepipe.WritePipeline()
+    p4.register_before("rw", lambda ctx:
+                       ctx["a"].__setitem__("content",
+                                            ctx["a"].get("content") + " REWRITTEN")
+                       or None)
+    cg4 = _mk_cg(tmp)
+    out = p4.execute(cg4, {"content_kind": "text", "content": "PASSED",
+                           "layer": "knowledge"})
+    _check("REWRITE改写生效", out.get("committed") is True
+           and bool(cg4.search("REWRITTEN")), repr(out))
+
+    # ---------- 4 权限结构上不可被拦截器绕过 ----------
+    cg_guest = _mk_cg(tmp, role="guest")
+    p5 = writepipe.WritePipeline()
+    p5.register_before("always_pass", lambda ctx: None)
+    try:
+        p5.execute(cg_guest, {"content_kind": "text", "content": "PASSED",
+                              "consistency": False, "layer": "knowledge"})
+        _check("权限不可绕", False, "guest 写入未被拒")
+    except AccessDenied:
+        _check("权限不可绕", True)
+    except Exception as e:  # noqa: BLE001
+        _check("权限不可绕", False,
+               "异常类型=%s:%s" % (type(e).__name__, e))
+
+    # ---------- 5 after 观测者 ----------
+    p6 = writepipe.WritePipeline()
+    seen = []
+    p6.register_after("spy", lambda ctx, out: seen.append(out.get("committed")))
+    cg6 = _mk_cg(tmp)
+    p6.execute(cg6, {"content_kind": "text", "content": "PASSED",
+                     "layer": "knowledge"})
+    _check("after观测成功", seen == [True], repr(seen))
+
+    def _boom(ctx, out):
+        raise RuntimeError("after钩子故障")
+
+    p6.register_after("boom", _boom)
+    try:
+        p6.execute(cg6, {"content_kind": "text", "content": "PASSED 二次",
+                         "layer": "knowledge"})
+        _check("after故障不吞", False, "异常被静默")
+    except RuntimeError:
+        _check("after故障不吞", True)
+
+    # ---------- 6 注册表卫生 ----------
+    p7 = writepipe.WritePipeline()
+    p7.register_before("x", lambda ctx: None)
+    p7.register_before("x", lambda ctx: None)  # 同名幂等替换
+    _check("同名幂等注册", p7.names()["before"] == ["x"], repr(p7.names()))
+    try:
+        p7.register_before("y", 123)
+        _check("类型守卫", False, "非可调用未拒")
+    except TypeError:
+        _check("类型守卫", True)
+    _check("注销返回布尔", p7.unregister_before("x") is True
+           and p7.unregister_before("x") is False)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/theory.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """md_cg · 版本层（蜂群互联 · 层0）
 
-设计依据：`docs/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
+设计依据：`docs/swarm/蜂群互联_v0.1.md` §2.3 / §3.1 / §10。
 
 版本更新权 = 蜂群**唯一核心权限**（严格唯一，仅 designer）。本模块只做
 「声明 + 校验」两件事，不做跨节点证据交换（§9.1 属存在约束，留待 v0.3）：

package/md_cg/tokens.py

@@ -53,7 +53,9 @@ ALL_LAYERS = ("anchor", "structural", "knowledge", "contextual", "self",
               "rejected", "unresolved", "goals")
 
 # 认知图 op 全集（与 mcp_server._cg_call 对齐，供 ops_allow 收窄）
-ALL_OPS = ("info", "route", "read", "write", "goal", "recent", "verify",
+#   help  按需披露入口：工具面投影（见 md_cg/tool_face.py）后，被外置的完整
+#         op/参数语义在此从真源取回；只读元信息，不经角色闸（不属于写/裁决面）
+ALL_OPS = ("help", "info", "route", "read", "write", "goal", "task", "recent", "verify",
            "review", "forget", "protect", "identity", "consistency",
            "metacognition", "self_state", "evolution", "sustain", "scrub",
            "predict", "causal", "whitebox", "index_code", "index_doc", "ref",
@@ -71,7 +73,13 @@ ALL_OPS = ("info", "route", "read", "write", "goal", "recent", "verify",
            #                情景重构（reconstruct）+ 盲区学习（learn）+
            #                结构洞察（outlook）；写入 action 按 can_write 收窄，
            #                learn/apply 与批量落库走 require_admin
-           "session", "ingest", "export", "maintain", "consolidate", "insight")
+           "session", "ingest", "export", "maintain", "consolidate", "insight",
+           # P3 新增（记忆可靠性闸，见 docs 讨论）：
+           #   ccg  CCG 六要素编译器（compile/review/attest/link/recalibrate/units）
+           #        —— 对话记录→六要素候选→**编外复核**→落库；裁定 A：编译者不得自证
+           #        （E041 机械拒绝 verifier == compiled_by）。复核通道优先蜂巢
+           #        reflect/verify 单元，不可用则提示配置或降级 harness 端子代理。
+           "ccg")
 
 
 class TokenError(Exception):
@@ -102,8 +110,12 @@ ROLE_SPECS = OrderedDict([
         # session=记会话要点；ingest=摄取外部文件流（记录单元本职）
         # maintain=写入前馈 prefeed（apply 类批量改写仍被 require_admin 拦截）
         # insight=记录洞见事件（record）；verify/learn 在分发层按单位职责收窄
-        "ops_allow": ["info", "route", "read", "write", "goal", "recent",
-                      "session", "ingest", "maintain", "insight"],
+        # ccg=CCG 六要素编译器（记录单元本职：保存观测/过程/结果与误差）；
+        #     其准入不靠 admin 闸而靠签章机械闸（E040/E041/E042）——编译者不得自证
+        # task=结构层任务台账（工程做到哪一步/结果是什么）——记录单元本职：
+        #     保存过程与结果；「不得自证」由 done 时的结果必填闸承接
+        "ops_allow": ["info", "route", "read", "write", "goal", "task", "recent",
+                      "session", "ingest", "maintain", "insight", "ccg"],
         "delegable": False,
         "forbidden": ["self/anchor 层", "private/secret 密级", "裁决与删除"],
     }),
@@ -177,6 +189,32 @@ POSITION_ROLES = ("record", "reflect", "verify", "output", "sustain")
 
 DELEGABLE_ROLES = tuple(r for r, s in ROLE_SPECS.items() if s["delegable"])
 
+# --------------------------------------------------------------------------
+# 蜂巢编排器（hive/orch.py）派生收窄面 · 单一真源
+# --------------------------------------------------------------------------
+# 设计依据（取证 2026-09-16，源码级：本文件 derive() + md_cg/mdcos.py 的
+# require_admin 闸门）：
+#   ① 编排器要「能裁决子代理冲突」→ 必须过 `MdCGSecure.review_decide` 的库层
+#      `require_admin`。而 `derive()` 的 `can_admin = spec.can_admin and
+#      parent.can_admin`（**不可收窄**）→ 唯一可行 role 是 designer。
+#      （`narrowed_principal()` 的 can_admin 恒 False，裁决会被库层拒 —— 这是被
+#      代码证据排除的路径，不是偏好取舍。）
+#   ② 因此「不给 delete / 不给 anchor / 不给 delegate」**不能依赖 admin 闸**
+#      （can_admin=True 时该闸不拦清单内的 op），而由三重结构保证：
+#        · ops_allow 白名单（ALL_OPS 的**子集**）—— 不在清单的 op 被
+#          `_cg_dispatch` 前置 `require_op` 直接拒：forget=删除、identity=动地基、
+#          protect=固化、maintain/consolidate 的 apply 类批量改写，全在清单外；
+#        · layers_allow 白名单（排除 CORE_LAYERS=anchor/self）—— 写不进地基；
+#        · `derive()` 硬编码 `delegable=False` —— 派生令牌结构上不可再派生。
+#      白名单方向 fail-closed：ALL_OPS 将来新增 op，默认不在清单内 = 不给。
+#   ③ 残余面（诚实标注，未收窄）：can_admin=True 使清单内 op 的 admin 分支仍可
+#      通过 —— `recent` 的 clear、`consistency` 的 auto_flywheel 写、`review` 的
+#      裁决（功能所求）。改本常量即改编排器权限：签发（CLI `orch`）与
+#      hive/orch.py 同引此处，防两处硬编码漂移。
+ORCH_ROLE = "designer"
+ORCH_OPS_ALLOW = ("route", "read", "write", "review", "recent", "consistency")
+ORCH_LAYERS_ALLOW = tuple(l for l in ALL_LAYERS if l not in CORE_LAYERS)
+
 
 def normalize_role(role: str) -> str:
     r = (role or "").strip().lower()
@@ -464,6 +502,22 @@ def _csv_list(v):
     return [x.strip() for x in str(v).split(",") if x.strip()] or None
 
 
+def _write_secret(path: str, text: str) -> None:
+    """把令牌明文写入文件（0600，原子替换）——供 HIVE_ORCH_TOKEN_FILE 读取。"""
+    p = os.path.abspath(path)
+    d = os.path.dirname(p)
+    if d:
+        os.makedirs(d, exist_ok=True)
+    tmp = p + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, p)
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+
+
 def main(argv=None):
     ap = argparse.ArgumentParser(
         prog="python -m md_cg.tokens",
@@ -491,6 +545,23 @@ def main(argv=None):
     p_d.add_argument("--actor", default=None)
     p_d.add_argument("--ttl", type=float, default=None)
     p_d.add_argument("--label", default="")
+    p_d.add_argument("--ops-allow", dest="ops_allow", default=None,
+                     help="收窄 op 白名单（逗号分隔；越界项被忽略，只能小于角色默认）")
+    p_d.add_argument("--layers-allow", dest="layers_allow", default=None,
+                     help="收窄可写层白名单（逗号分隔；越界项被忽略）")
+    p_d.add_argument("--clearance", default=None,
+                     help="收窄密级（默认取角色上限，且不超过父令牌）")
+
+    p_o = sub.add_parser(
+        "orch",
+        help="签发蜂巢编排器令牌（收窄面取自本模块 ORCH_* 真源，一步到位）")
+    p_o.add_argument("--token", default=None, help="父令牌明文（须为 designer 且可派生）")
+    p_o.add_argument("--token-file-in", dest="token_file_in", default=None,
+                     help="从文件读父令牌")
+    p_o.add_argument("--ttl", type=float, default=None, help="有效期（秒）")
+    p_o.add_argument("--label", default="hive-orchestrator")
+    p_o.add_argument("--out", default=None,
+                     help="把令牌明文写入该文件（0600；供 HIVE_ORCH_TOKEN_FILE 读取）")
 
     p_v = sub.add_parser("verify", help="校验令牌并打印身份")
     p_v.add_argument("--token", default=None)
@@ -516,7 +587,26 @@ def main(argv=None):
                 with open(a.token_file_in, encoding="utf-8") as f:
                     tok = f.read().strip()
             _print(derive(tok, a.role, actor=a.actor, ttl=a.ttl,
-                          label=a.label, path=a.token_file))
+                          label=a.label, path=a.token_file,
+                          clearance=a.clearance,
+                          layers_allow=_csv_list(a.layers_allow),
+                          ops_allow=_csv_list(a.ops_allow)))
+        elif a.cmd == "orch":
+            tok = a.token
+            if a.token_file_in:
+                with open(a.token_file_in, encoding="utf-8") as f:
+                    tok = f.read().strip()
+            r = derive(tok, ORCH_ROLE, actor="hive-orchestrator", ttl=a.ttl,
+                       label=a.label, path=a.token_file,
+                       layers_allow=list(ORCH_LAYERS_ALLOW),
+                       ops_allow=list(ORCH_OPS_ALLOW))
+            if a.out:
+                _write_secret(a.out, r["token"])
+                r = {k: v for k, v in r.items() if k != "token"}
+                r["token_written_to"] = os.path.abspath(a.out)
+            r["usage"] = ("把令牌明文放入 hive serve 的环境变量 HIVE_ORCH_TOKEN"
+                          "（或写文件后设 HIVE_ORCH_TOKEN_FILE）再重启 serve")
+            _print(r)
         elif a.cmd == "verify":
             tok = a.token
             if a.token_file_in: