@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/mcp_server.py

@@ -52,11 +52,13 @@ PROTOCOL_VERSION = "2024-11-05"
 # 工具定义
 # --------------------------------------------------------------------------
 
+# 生效条件：传 _desc 与任意 props 时返回 {"type":"object","properties":props,"required":[...]}，required 仅列出 props 中值含真值 "_req" 键的条目名。
 def _s(_desc, **props):
     return {"type": "object", "properties": props, "required":
             [k for k, v in props.items() if v.get("_req")]}
 
 
+# 生效条件：始终返回 {"type":t,"description":desc}，仅当 req 为真值时该字典额外含 "_req": True。
 def _p(t, desc, req=False):
     d = {"type": t, "description": desc}
     if req:
@@ -64,6 +66,7 @@ def _p(t, desc, req=False):
     return d
 
 
+# 生效条件：exp 为假值（None/空容器等）时返回 None，exp 为真值时返回 _expand 闭包——该闭包调用时先取 expand_query_terms_weighted(q)，再对 exp 每项（dict 项 term=str(it.get("term") or "").strip()、w=float(it.get("weight",0.5)) 抛 TypeError/ValueError 则 w=0.5；非 dict 项 term=str(it).strip()、w=0.5）在 term 非空时写 out[term]=max(out.get(term,0.0), max(0.0,min(1.0,w)))，最后置 out["__source__"]="llm" 并返回 out；
 def _make_query_expand(exp):
     """把调用方（LLM/多智能体）提供的扩展词包装成 query_expand 注入函数。
 
@@ -74,6 +77,7 @@ def _make_query_expand(exp):
         return None
     from .mdcg import expand_query_terms_weighted
 
+# 生效条件：在外层 _make_query_expand(exp) 的 exp 为真值前提下被调用时，先 out=expand_query_terms_weighted(q)，再对 _exp（默认绑定外层 exp）每项——dict 项取 term=str(it.get("term") or "").strip()、w=float(it.get("weight",0.5))（抛 TypeError/ValueError 则 w=0.5），非 dict 项取 term=str(it).strip()、w=0.5，term 非空时 out[term]=max(out.get(term,0.0), max(0.0,min(1.0,w)))，最后置 out["__source__"]="llm" 并返回 out。
     def _expand(q, _exp=exp):
         out = expand_query_terms_weighted(q)
         for it in _exp:
@@ -138,6 +142,11 @@ TOOLS = [
                                              "仅在查询时刻生效，索引侧仍白箱"),
                           session=_p("string", "会话归属过滤（frontmatter.session；"
                                      "多会话共用 root 时只取本会话记忆；缺省不过滤）"),
+                          validity=_p("boolean", "时效过滤（**显式启用**，缺省不过滤）："
+                                                 "仅排除**已过期**（valid_until 已过）节点；"
+                                                 "**未生效（valid_from 未到）一律保留**——"
+                                                 "「尚未开始」与「已失效」语义相反，预约/计划类"
+                                                 "记忆在生效前仍可召回"),
                           goal=_p("string", "当前目标（第 5 篇第 3 章）：启用 goal 路给召回定向；"
                                             "省略则自动取活跃目标"),
                           goal_path=_p("boolean", "启用目标定向路（默认否；给 goal 即自动启用）"),
@@ -155,7 +164,10 @@ TOOLS = [
                           layer=_p("string", "限定层"), context=_p("object", "情境"),
                           roles=_p("array", "限定角色"), include_work=_p("boolean", "含工作角色"),
                           session=_p("string", "会话归属过滤（frontmatter.session；"
-                                     "缺省不过滤）")),
+                                     "缺省不过滤）"),
+                          validity=_p("boolean", "时效过滤（显式启用，缺省不过滤）：仅排除"
+                                                 "**已过期**（valid_until 已过）节点，"
+                                                 "未生效（valid_from 未到）保留")),
     },
     {
         "name": "mdcg_get",
@@ -213,11 +225,13 @@ TOOLS = [
     },
     {
         "name": "mdcg_review_decide",
-        "description": "审核裁决：accept / reject / edit / merge（merge 需 merge_into）。"
+        "description": "审核裁决：accept / reject / edit / merge / noop（merge 需 merge_into）。"
+                       "noop=已评估、判定不改变任何现有记忆：只留痕并关闭提案，"
+                       "不落业务节点、不进负记忆（与 reject 的区别是语义而非路径）。"
                        "redteam.verdict=reject 不落库，转 needs_reapproval，"
                        "修复后须带递增 round 的 pass 再审批；判据只读不可改。",
         "inputSchema": _s("", pid=_p("string", "提案 id", True),
-                          decision=_p("string", "accept|reject|edit|merge", True),
+                          decision=_p("string", "accept|reject|edit|merge|noop", True),
                           edits=_p("object", "edit 时的覆盖字段"), merge_into=_p("string", "merge 目标节点 id"),
                           reason=_p("string", "裁决理由"),
                           redteam=_p("object", "红队裁决 {verdict:pass|reject, issues:[], round:n}"),
@@ -307,13 +321,16 @@ TOOLS = [
                        "情绪=信息差二阶变化 d²D/dt²（§十一）→ 轨迹面；"
                        "自信校准（期望正确率 vs 实际验证通过率，过度自信/过度保守）→ 校准面；"
                        "盲区地图（反复 BLINDSPOT 的查询邻域 + 未解问题，推论三）→ 盲区面；"
-                       "P_gap/P_trust + 情感 d²T/dt²（§十）→ 信任面。"
+                       "P_gap/P_trust + 情感 d²T/dt²（§十）→ 信任面；"
+                       "D_meta 边界压力向量（events_pressure / unmodeled_growth / "
+                       "boundary_violation_rate 各自 [0,1]，**不合成单值**，DEV-002a）"
+                       "→ 边界面。"
                        "action=report 完整报告（含确定性建议）/ trace / calibration / "
                        "blindspots / trust / self_check（回答前自检：该直接答还是先补条件）"
-                       " / history / catalog。只读留痕，不改事实层。",
+                       " / history / d_meta / catalog。只读留痕，不改事实层。",
         "inputSchema": _s("", action=_p("string", "report|trace|calibration|"
                                                 "blindspots|trust|self_check|"
-                                                "history|catalog"),
+                                                "history|d_meta|catalog"),
                           query=_p("string", "self_check 的待答查询"),
                           k=_p("integer", "self_check：相似历史条数"),
                           window=_p("integer", "轨迹/信任的滚动窗口"),
@@ -496,7 +513,9 @@ KERNEL_TOOLS = [
     {
         "name": "cg",
         "description": "认知图接口（唯一入口）。op=route：按情境条件路由，返回相关知识 + "
-                       "建议能力名（不执行，由调用方决定）；op=read：召回/检索/按 id 取；"
+                       "建议能力名（不执行，由调用方决定）；op=read：召回/检索/按 id 取"
+                       "（长内容自动截断 2000 行 / 50KB，返回 truncated+next_offset，"
+                       "续读传 offset=next_offset，不静默丢内容）；"
                        "op=write：写入前按 content_kind 审核（ACCEPT 落盘 / REJECT 进负记忆 / "
                        "DEFER 进审核队列）+ 节点间冲突检测（三级决策：情绪→反思→递归反思；"
                        "consistency=false 可关，on_conflict=reject|defer|record）；"
@@ -507,6 +526,12 @@ KERNEL_TOOLS = [
                        "op=forget：软删除/恢复（受保护节点需 override）；"
                        "op=goal：目标槽（第 5 篇七件套之「目标」，"
                        "action=add|list|status；目标不进召回，只给 read 定向）；"
+                       "op=task：结构层任务实体（跨会话的工程台账，与信任/自我/协议同级；"
+                       "action=open 登记或更新（同名即同卡）、status 状态迁移"
+                       "（进行中/受阻/完成/放弃，迁 完成 时结果必填）、plan_add 追加计划变更、"
+                       "get 单卡全字段、list 清单、find 同族提示（只提示不合并）、"
+                       "session 会话装配面（进行中+近期完成）；"
+                       "任务只存骨架，中间过程不入库，任务知识走 knowledge 层）；"
                        "op=recent：近期事件窗口（七件套之「近期事件」，"
                        "action=add|list|clear，滚动保留最近 N 条）；"
                        "op=identity：身份特征识别（智能论 v3.4 位置效应 + 扮演论"
@@ -562,16 +587,59 @@ KERNEL_TOOLS = [
                        "另有节点**派生溯源**（区别于对端信任）：derive 列边、"
                        "derive_dangling 悬空巡检（只读、不删边）、derive_catalog 自描述、"
                        "derive_rebuild 按 frontmatter 重建台账（默认预演）；权威声明只在"
-                       "节点写入时产生（write/remember 的 derived_from），本层不新增写入口）。",
+                       "节点写入时产生（write/remember 的 derived_from），本层不新增写入口）；"
+                       "op=session：会话三件套（action=note 写要点 / recall 续接 / "
+                       "compact 压摘要；hook 缺失时的库侧替代——载体负责「何时做」、库保证"
+                       "「一次调用就够用」；note 与 compact(note=True) 需 can_write，recall 只读）；"
+                       "op=ingest：文件摄取（action=file|dir|jsonl|stat；写链需 can_write，"
+                       "支持 dry_run 预演与 incremental 增量去重、watermark 留痕）；"
+                       "op=export：全库导出（action=graph|nodes|slice|stat；导出整库属管理"
+                       "操作，一律 require_admin）；"
+                       "op=maintain：记忆维护（action=stat|history|importance|longterm|"
+                       "prefeed|separate|rollback|backfill|cap|exempt|vision_evidence|refine|"
+                       "propagate 及其 *_history；propagate = 验证态的**多跳**失效传播巡检"
+                       "（默认预演，apply 需 admin）；权限按 action 分档：只读放行、prefeed "
+                       "写入需 can_write、批量改写与 rollback 需 admin；dry-run 只出报表不改盘）；"
+                       "op=consolidate：离线固化（action=promote 提升 | induce 归纳 | "
+                       "contextualize 语境化，及其 _rollback/_history；批量提升属管理操作，"
+                       "一律 require_admin）；"
+                       "op=insight：洞察（action=window|record|verify|list|report|"
+                       "reconstruct|learn|outlook|catalog|fork|branch_rewrite|branch_search|"
+                       "branch_merge|branch_discard|branches|tickets；权限按 action 分档：只读放行、"
+                       "条件记账与分支写需 can_write、落库 apply 与分支弃置需 admin）；"
+                       "op=ccg：CCG 六要素编译器（action=compile|review|attest|link|"
+                       "recalibrate|units|catalog；入参统一在 ccg 对象里）。"
+                       "把对话记录编译为六要素候选 → **编外复核**（裁定 A：编译者不得自证，"
+                       "E041 机械拒绝）→ 落库；复核优先走蜂巢 reflect/verify 单元，"
+                       "蜂巢不可用则提示配置，或显式 allow_degrade 降级 harness 端子代理。"
+                       "op=status：**可验证记忆单元**读面（验证态 unverified|verified|"
+                       "doubted|expired|rechecking + 依赖 depends_on + 双时间轴 valid_from/"
+                       "valid_until + 履历台账）；给 node_id 看单节点全貌、不给看全库摘要、"
+                       "action=ledger 读台账。所有读面返回体统一带 status_head 状态头"
+                       "（✓已验证 / △已修改 / !异常 / ?存疑），hint 亦升级为该格式"
+                       "（MDCG_STATUS_HEAD=0 回退旧文本）。"
+                       "op=edges：**三元组反查**读面（阶段二 4.2）：按派生边任意端 / "
+                       "谓词 / 时间反查「这条记忆从哪来、谁由它派生」——subject/predicate/"
+                       "object ≡ child/relation/parent（`derived_from` 派生的三元组）。"
+                       "支持排序（ordering=desc 按写入时刻新→旧，缺省/asc）、分页"
+                       "（offset/limit）、**分页前全集**聚合（aggregation=by_relation|"
+                       "by_parent|by_child）、端点索引摘要（expand_nodes=true）。"
+                       "时间条件缺省走**观察轴**（派生边只有写入时刻 t，无效力声明）"
+                       "——与 op=read 缺省效力轴**有意不同**，由库层单点校验。",
         "inputSchema": _s("",
             op=_p("string", "route|read|write|verify|review|protect|identity|"
                             "consistency|metacognition|self_state|evolution|sustain|"
                             "scrub|predict|causal|"
-                            "forget|goal|recent|info|index_code|index_doc|ref|whitebox|"
+                            "forget|goal|task|recent|info|index_code|index_doc|ref|whitebox|"
                             "theory|link|session|ingest|export|maintain|consolidate|"
-                            "insight", True),
+                            "insight|ccg|status|edges|help", True),
+            ccg=_p("object", "CCG 六要素编译器入参：{action, node_id, dialog, marks, "
+                             "slots, strict_spans, role, verdict, verifier, compiled_by, "
+                             "evidence, slot_corrections, model, jobs, blocking, wait_s, "
+                             "allow_degrade, channel, autostart, doctor, apply, basis}"),
             intent=_p("string", "route 的查询意图"), query=_p("string", "read 的查询"),
-            goal=_p("string", "goal op 的目标文本；read 的定向目标（缺省用活跃目标）"),
+            goal=_p("string", "goal op 的目标文本；read 的定向目标（缺省用活跃目标）；"
+                              "task op：任务目标（CCG「执行」栏）"),
             goal_status=_p("string", "goal op：active|done|dropped"),
             priority=_p("number", "goal op：优先级 0-1（兼作定向偏置依据）"),
             deadline=_p("string", "goal op：截止时间（仅排序用，不做硬约束）"),
@@ -583,10 +651,34 @@ KERNEL_TOOLS = [
             meta=_p("object", "recent op：附加元数据"),
             window=_p("integer", "recent op：滚动窗口大小（默认 200）"),
             include_recent=_p("boolean", "read：是否附近期事件窗口（默认否）"),
-            limit=_p("integer", "goal/recent 的返回条数；read 的近期事件条数"),
+            limit=_p("integer", "goal/recent 的返回条数；read 的近期事件条数；"
+                                "edges 分页条数（缺省 50、上限 500，0/负数报错不当「全部」）"),
             node_id=_p("string", "节点 id"),
+            offset=_p("integer", "read 的续读起始行（1 基；传上次返回的 next_offset）；"
+                                 "edges 的分页偏移（排序后切片，默认 0）"),
             content=_p("string", "write 的内容（建议含 CCG 5 要素注释）"),
-            content_kind=_p("string", "write 的内容类型：code|image_desc|text|permission|work_done|work_wip"),
+            content_kind=_p("string", "write 的内容类型：code|image_desc|text|permission|work_done|work_wip|ccg_marks|hyperedge"),
+            depends_on=_p("array", "write/verify：本单元**依赖**的节点 id 列表（CCG「子功能」"
+                                   "的落字段，单值/逗号串亦可）。被依赖单元被修改或被证伪时，"
+                                   "本节点**同跳**标「存疑」（一跳同步；多跳走 maintain"
+                                   " action=propagate）。**何时需要它**：正文「# 子功能：」行"
+                                   "以 @<节点 id> 显式引用其它单元时（仅自述本单元内部构成"
+                                   "不算依赖，无需本字段）——显式引用却无可解析目标 → 硬拒"
+                                   "（E050 缺 depends_on / E051 目标悬空）"),
+            valid_from=_p("string", "双时间轴**起点**（ISO8601，如 2026-01-01）：此刻起才成立"
+                                    "（未到点在 scrub 报 not_yet，仅提示不降权）"),
+            valid_until=_p("string", "双时间轴**终点**（ISO8601）：此刻后不再成立"
+                                     "（过期在 scrub 报 expired，weaken/demote）"),
+            start_time=_p("string", "时间算子：查询窗起点（ISO8601/时间戳）。启用后 "
+                                    "read 按 time_axis 轴把候选收敛到窗内；edges 按边"
+                                    "写入时刻 t 收敛（**edges 缺省轴 observed**，与 read 不同）"),
+            end_time=_p("string", "时间算子：查询窗终点（缺省该侧=无界）"),
+            start_operator=_p("string", "时间算子：起点比较 gt|gte|eq|lte|lt"
+                                        "（两端都不给算子=区间重叠语义）"),
+            end_operator=_p("string", "时间算子：终点比较 gt|gte|eq|lte|lt"),
+            time_axis=_p("string", "时间算子轴：effective（效力轴，read 缺省）|"
+                                   "observed（观察轴 temporal/time_window；"
+                                   "**edges 的缺省轴**——派生边只有记录时刻，无效力声明）"),
             layer=_p("string", "层：anchor|structural|knowledge|contextual|self"),
             tags=_p("array", "标签（cap:xxx 会作为 route 的建议能力名）"),
             importance=_p("number", "重要性 0-1"),
@@ -610,6 +702,11 @@ KERNEL_TOOLS = [
             non_applicable_conditions=_p("array", "不适用条件"),
             context=_p("object", "当前情境"),
             k=_p("integer", "返回条数（sustain pool_bench 亦用）"),
+            view=_p("string", "read/route 的角色化读取视图（第四阶段 6.1，缺省关）："
+                             "main（主代理：结论与修正历史）|"
+                             "verifier（验证端：判据面与环境陷阱）|"
+                             "receipt（回执审计：命令与预期输出）；"
+                             "非法值库层报错（fail-closed）"),
             budget_tokens=_p("integer", "read 的 token 预算"),
             evidence=_p("string", "verify 的证据"),
             verdict=_p("string", "verify 裁决：confirmed|weakened|falsified；"
@@ -620,7 +717,7 @@ KERNEL_TOOLS = [
             marker=_p("string", "whitebox verify_encoding：唯一口令标记（缺省自动生成）"),
             fact=_p("string", "whitebox verify_encoding：待编码事实"),
             questions=_p("array", "whitebox verify_existing：探针问题列表"),
-            action=_p("string", "review: list|decide|rounds；forget: forget|restore；"
+            action=_p("string", "review: list|decide|rounds|stats；forget: forget|restore；"
                                 "protect: stats|check|mark|snapshot|history|forgetting；"
                                 "identity: observe|anchor|trait|profile|positions|catalog；"
                                 "consistency: check|history|stats|catalog；"
@@ -652,7 +749,15 @@ KERNEL_TOOLS = [
                                 "promote_history|induce|contextualize|"
                                 "contextualize_rollback|contextualize_history；"
                                 "insight: window|record|verify|list|report|"
-                                "reconstruct|learn|outlook|catalog"),
+                                "reconstruct|learn|outlook|catalog|"
+                                "fork|branch_rewrite|branch_search|"
+                                "branch_merge|branch_discard|branches|"
+                                "tickets；"
+                                "分支六 act：node_ids/branch_id/note/content/"
+                                "reason 按 act 取用（rewrite 传 node_id+content）；"
+                                "tickets：盲区→四类消解票据任务卡"
+                                "（types=[research|prototype|grilling|task]，"
+                                "min_blindspot 资格线；apply=True 落库需 admin）"),
             pid=_p("string", "review decide 的提案 id"),
             decision=_p("string", "review 裁决：accept|reject|edit|merge"),
             edits=_p("object", "review edit 的覆盖字段（不可含 verify）"),
@@ -686,10 +791,15 @@ KERNEL_TOOLS = [
                                      "路径命中私有提示时保守降为 private）"),
             ref=_p("object", "ref op：直接给 code_ref/doc_ref 对象（与 node_id 二选一）"),
             root=_p("string", "ref op：覆盖 ref 里记录的 root（索引结果的跨机器搬迁）"),
-            name=_p("string", "sustain：心跳名（默认 md_cg）"),
+            name=_p("string", "sustain：心跳名（默认 md_cg）；"
+                              "task op：任务名（**身份判据**：同名即同任务，slug 归一后落 id）"),
             session=_p("string", "read（search/recall 分支）：会话归属过滤"
                                  "（frontmatter.session；缺省不过滤）；"
                                  "sustain：会话 id（resume/note 用）"),
+            validity=_p("boolean", "read（search/recall 分支）：时效过滤（显式启用，"
+                                   "缺省不过滤）——仅排除**已过期**（valid_until 已过）"
+                                   "节点；**未生效（valid_from 未到）保留**"
+                                   "（两者语义相反，预约/计划类记忆生效前仍可召回）"),
             ts=_p("number", "sustain note：事件时间戳"),
             seq=_p("integer", "sustain note：事件序号"),
             task_running=_p("boolean", "sustain：任务执行中（心跳阈值放宽）"),
@@ -729,7 +839,8 @@ KERNEL_TOOLS = [
             hit=_p("boolean", "predict feedback：是否命中（缺省按 predicted==actual）"),
             rule=_p("string", "evolution record：规律（必填，一句话认知规律）"),
             missing=_p("string", "evolution record：补的是哪一维缺失条件"),
-            change=_p("string", "evolution record：这次具体改了什么"),
+            change=_p("string", "evolution record：这次具体改了什么；"
+                                "task op：本轮计划变更/新增问题（追加进「计划变更」节，可追溯）"),
             kind=_p("string", "evolution：condition_gap|layer_shift|general"),
             entry_id=_p("string", "evolution show/rollback：条目 id"),
             source=_p("string", "evolution record：来源 consolidate|verify|manual；"
@@ -768,14 +879,22 @@ KERNEL_TOOLS = [
             verdicts=_p("array", "maintain refine apply：人工核对裁决 "
                                  "[{concept_id, faithful, added_info, note}]；"
                                  "缺省只落抽检留痕（不改节点）"),
-            batch=_p("string", "maintain/consolidate：批次号（回滚用）"),
+            batch=_p("string", "maintain/consolidate：批次号（回滚用）；"
+                               "edges：按派生边批次号过滤"),
             derived_from=_p("string", "write/remember：派生来源节点 id（G8，可用逗号/空格"
                                       "分隔多个）；声明后写入 frontmatter 并建派生边"),
-            relation=_p("string", "write/remember/link derive：派生关系名，"
+            relation=_p("string", "write/remember/link derive/edges：派生关系名（**谓词**），"
                                   "默认 derived_from（split_from|extracted_from|"
                                   "merged_from|refined_from|source）"),
-            child=_p("string", "link derive：按子节点 id 过滤派生边"),
-            parent=_p("string", "link derive：按父节点 id 过滤派生边"),
+            child=_p("string", "link derive/edges：按子节点 id 过滤派生边"
+                               "（edges 中即三元组的**主体**）"),
+            parent=_p("string", "link derive/edges：按父节点 id 过滤派生边"
+                                "（edges 中即三元组的**对象**）"),
+            ordering=_p("string", "edges：排序方向 desc（按写入时刻 新→旧，缺省）|asc"),
+            aggregation=_p("string", "edges：分页前全集分桶 by_relation|by_parent|"
+                                     "by_child（缺省不聚合）"),
+            expand_nodes=_p("boolean", "edges：是否附端点索引摘要 child_node/"
+                                       "parent_node（默认否；只读索引快照）"),
             ledger_only=_p("boolean", "link derive_dangling：只看台账、忽略索引声明"),
             pools=_p("object", "search/sustain pool_bench：召回分池表"
                                "{knowledge:{cap_ratio,weight},index:{…},"
@@ -810,21 +929,37 @@ KERNEL_TOOLS = [
             neighbors=_p("boolean", "insight reconstruct：是否并入一跳邻域（默认 true）"),
             recent_days=_p("integer", "insight outlook：近期窗口天数（默认 7）"),
             sample_limit=_p("integer", "insight outlook：抽样清单条数（默认 8）"),
-            max_events=_p("integer", "ingest：单次最多摄取事件数")),
+            max_events=_p("integer", "ingest：单次最多摄取事件数"),
+            task_status=_p("string", "task op：active|blocked|done|dropped；"
+                                     "迁 done 必须同时给 result（缺一不收）"),
+            plan=_p("string", "task op：分步计划（每轮覆盖更新，跨会话持久存在）"),
+            result=_p("string", "task op：任务结果（done 时必填；本次不传则**保留旧值**，"
+                                "不会被静默清空）"),
+            acceptance=_p("string", "task op：验收判据（怎么算完成）"),
+            boundary=_p("string", "task op：不适用条件/边界"),
+            note=_p("string", "task op：本轮备注（change 是计划变更，note 是附注）；"
+                              "self_state relate：备注"),
+            condition=_p("string", "task op：生效条件（CCG「生效条件」栏）；"
+                                   "self_state relate：关系成立条件"),
+            active_limit=_p("integer", "task action=session：进行中任务条数（默认 5）"),
+            done_limit=_p("integer", "task action=session：近期已完成条数（默认 5）")),
     },
     {
         "name": "stg",
         "description": "语义时空图接口：精确得到信息的时间/空间关系。"
                        "op=relation：两节点时空关系（Allen 时间 6 态 + RCC 空间 7 态）；"
                        "op=timeline：按时间排序；op=anchors：落在时间窗/空间范围的节点；"
-                       "op=consistency：时空字段自洽性检查。",
+                       "op=consistency：时空字段自洽性检查。"
+                       "四个 op 均可用 time_axis 切换时间轴（缺省 observed）。",
         "inputSchema": _s("",
             op=_p("string", "relation|timeline|anchors|consistency", True),
             a=_p("string", "relation 的节点 a"), b=_p("string", "relation 的节点 b"),
             time_window=_p("array", "anchors 的时间窗 [t1,t2]"),
             bbox=_p("array", "anchors 的包围盒 [x1,y1,x2,y2]"),
             layer=_p("string", "限定层"), limit=_p("integer", "返回条数"),
-            desc=_p("boolean", "timeline 是否倒序（默认是）")),
+            desc=_p("boolean", "timeline 是否倒序（默认是）"),
+            time_axis=_p("string", "时间轴：observed（观察轴 temporal/time_window，"
+                                   "缺省）| effective（效力轴 effective_from/until）")),
     },
 ]
 
@@ -832,19 +967,30 @@ ALL_TOOLS = KERNEL_TOOLS + TOOLS
 SURFACE = os.environ.get("MDCG_MCP_SURFACE", "kernel").strip().lower()
 
 
+# 生效条件：模块级 SURFACE 等于 "full" 时以 ALL_TOOLS、否则以 KERNEL_TOOLS 调 slim_tools 并返回其结果。
 def tools_for_surface():
-    """kernel：只暴露 2 个基元；full：2 个基元 + 31 个细粒度工具（兼容/调试）。"""
-    return ALL_TOOLS if SURFACE == "full" else KERNEL_TOOLS
+    """kernel：只暴露 2 个基元；full：2 个基元 + 31 个细粒度工具（兼容/调试）。
+
+    返回**投影后**的工具面（工具一行职责 + 参数短提示）：完整语义由
+    ``cg(op=help, query=…)`` 按需取回。真源 KERNEL_TOOLS/TOOLS 保持完整定义，
+    投影只是运行时视图（信息零丢失，见 md_cg/tool_face.py）。
+    关闭投影：``MDCG_TOOL_FACE=full``。
+    """
+    tools = ALL_TOOLS if SURFACE == "full" else KERNEL_TOOLS
+    from .tool_face import slim_tools
+    return slim_tools(tools)
 
 
 # --------------------------------------------------------------------------
 # 序列化
 # --------------------------------------------------------------------------
 
+# 生效条件：始终返回 json.dumps(obj, ensure_ascii=False, default=str)。
 def _j(obj) -> str:
     return json.dumps(obj, ensure_ascii=False, default=str)
 
 
+# 生效条件：path 以 ".zstd" 结尾时直接返回 DSHSessionSource(path)；否则读首个非空行做 json.loads，该 dict 满足 o.get("type")=="session" 或同时含 "type"/"seq"/"data" 时返回 DSHSessionSource(path)，能解析但不满足时返回 JsonlSource(path)，json.loads 抛 ValueError 或 open/读抛 OSError 或无非空行时落到返回 JsonlSource(path)。
 def _pick_source(path):
     """按内容嗅探源类型：DSH 会话格式 vs 通用 JSONL。"""
     from .sources import DSHSessionSource, JsonlSource
@@ -866,17 +1012,80 @@ def _pick_source(path):
     return JsonlSource(path)
 
 
-def _node_view(node):
+READ_MAX_LINES = 2000           # 单次 read 返回行数上限（Pi⑦② 截断）
+READ_MAX_BYTES = 50 * 1024      # 单次 read 返回字节上限（Pi⑦② 截断）
+
+
+# 生效条件：text 先按 text or "" 归一，start 由 offset 定（offset 为假值取 0，否则 max(0,int(offset)-1)）；start≥total_lines 时返回空 text、next_offset=None 的窗口结果；否则从 start 起按 max_lines 行收集（max_lines=0 时 got 为空），且仅当已收集非空且 used+b>max_bytes 时提前 break（首行即便超 max_bytes 也收），end<total_lines 时 truncated=True、next_offset=end+1 并写续读 note。
+def _clip_text(text: str, *, offset: int = 0, max_lines: int = READ_MAX_LINES,
+               max_bytes: int = READ_MAX_BYTES) -> dict:
+    """行窗口 + 双阈值截断（Pi⑦② 截断必带续读提示）。
+
+    offset 为 1 基起始行（续读传上次 next_offset）。不静默丢内容——截断时
+    返回 total_lines / total_bytes / next_offset / note，调用方按 offset 续读。
+    """
+    text = text or ""
+    lines = text.split("\n")
+    total_lines = len(lines)
+    total_bytes = len(text.encode("utf-8"))
+    start = max(0, int(offset) - 1) if offset else 0
+    if start >= total_lines:
+        return {"text": "", "offset": start + 1, "next_offset": None,
+                "returned_lines": 0, "total_lines": total_lines,
+                "total_bytes": total_bytes, "truncated": False,
+                "note": f"offset={start + 1} 超出总行数 {total_lines}，返回空"}
+    got, used = [], 0
+    for ln in lines[start:start + max_lines]:
+        b = len(ln.encode("utf-8")) + 1
+        if got and used + b > max_bytes:
+            break
+        got.append(ln)
+        used += b
+    end = start + len(got)
+    truncated = end < total_lines
+    out = {"text": "\n".join(got), "offset": start + 1,
+           "next_offset": end + 1 if truncated else None,
+           "returned_lines": len(got), "total_lines": total_lines,
+           "total_bytes": total_bytes, "truncated": truncated, "note": ""}
+    if truncated:
+        out["note"] = (f"内容已截断（单次上限 {max_lines} 行 / {max_bytes} 字节）："
+                       f"共 {total_lines} 行 / {total_bytes} 字节，本次返回第 "
+                       f"{start + 1}–{end} 行；续读传 offset={end + 1}。")
+    return out
+
+
+# 生效条件：node 为假值时返回 None；否则用 _clip_text(node.get("content") or "", offset=offset) 构造 {id,path,frontmatter,content}，且当 clip["truncated"] 为真或 offset 为真值时追加 truncated/content_lines/content_bytes/offset/next_offset/note。
+def _trust_state(fm):
+    """节点验证态（缺字段按 unverified；导入失败不拖垮读面）。"""
+    try:
+        from . import trust
+        return trust.state_of(fm)
+    except Exception:                                      # noqa: BLE001
+        return None
+
+
+def _node_view(node, offset: int = 0):
     if not node:
         return None
-    return {"id": node.get("id"), "path": node.get("path"),
-            "frontmatter": node.get("frontmatter"), "content": node.get("content")}
+    clip = _clip_text(node.get("content") or "", offset=offset)
+    out = {"id": node.get("id"), "path": node.get("path"),
+           "frontmatter": node.get("frontmatter"), "content": clip["text"],
+           # 可验证记忆单元：读面 additive 透出验证态（**不改排序权重**，保基准）
+           "verification_state": _trust_state(node.get("frontmatter"))}
+    if clip["truncated"] or offset:
+        out.update({"truncated": clip["truncated"],
+                    "content_lines": clip["total_lines"],
+                    "content_bytes": clip["total_bytes"],
+                    "offset": clip["offset"], "next_offset": clip["next_offset"],
+                    "note": clip["note"]})
+    return out
 
 
 # --------------------------------------------------------------------------
 # 基元实现
 # --------------------------------------------------------------------------
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'stats'（空串/None 回退 'stats'）并 strip().lower() 分派：action=stats 返回 cg.protect_stats()；action 为 forgetting 或 forgetting_history 返回 {'records': cg.forgetting_history(limit=int(a.get('limit') or 100))}（a.get('limit') 为 0/空串/None 时回落 100）；action=check 时 node_id 取 a.get('node_id') or ''（空串/None 回落 ''），返回包含 node_id、exists（nid in (cg.index.get('nodes') or {})）、protected、reason、immutable、immutable_reason 的 dict；action=history 返回 {'node_id': nid, 'versions': protect.history(cg, nid)}；action=snapshot 返回 {'node_id': nid, 'snapshot': protect.snapshot(cg, nid)}；action 为 mark 或 protect 时若 cg.principal 非 None 则先调用 cg.principal.require_admin('protect_mark')，再返回 protect.mark(cg, nid, a.get('reason') or '显式保护标记')（reason 空串/None 回落 '显式保护标记'）；其他 action 抛 ValueError；
 def _protect_call(cg, a):
     """写保护 / 遗忘留痕的统一入口（cg op=protect 与 mdcg_protect 共用）。"""
     from . import protect
@@ -904,6 +1113,7 @@ def _protect_call(cg, a):
     raise ValueError(f"protect 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'profile'（空串/None 回退 'profile'）并 strip().lower() 分派，subject_id 取 a.get('subject_id') or ''（空串/None 回落 ''）：action=catalog 返回 identity.catalog()；action=positions 返回 {'positions': cg.identity_positions(limit=int(a.get('limit') or 0))}（a.get('limit') 假值回落 0）；action=profile 时若 sid 为假值返回 {'subjects': cg.identity_positions(limit=0), 'hint': '指定 subject_id 可获取完整画像（锚点+位置+特征）'}，否则返回 cg.identity_profile(sid)；action=observe 时以 sid 和 a.get('content') or a.get('text') or '' 调用 cg.identity_observe（含 kind=a.get('subject_kind')、role=a.get('role')、layer=a.get('layer')、tags=a.get('tags')、condition_space=a.get('condition_space')、importance=float(a.get('importance', 0.5))、verification_basis=a.get('verification_basis')、evidence=a.get('evidence')、override=bool(a.get('override'))）；action=trait 时以 sid 和 a.get('trait') or a.get('content') or '' 调用 cg.identity_trait（含 condition_space=a.get('condition_space')、importance=float(a.get('importance', 0.6))、position=a.get('position')、kind=a.get('subject_kind')、verification_basis=a.get('verification_basis') or 'data'、override=bool(a.get('override'))）；action=anchor 时若 cg.principal 非 None 先调用 cg.principal.require_admin('identity_anchor')，再以 sid 和 a.get('content') or a.get('text') or '' 调用 cg.identity_anchor（含 kind=a.get('subject_kind')、condition_space=a.get('condition_space')、importance=float(a.get('importance', 0.9))、override=bool(a.get('override'))、requested_layer=a.get('requested_layer')）；action=history 返回 {'records': cg.identity_history(limit=int(a.get('limit') or 100))}（a.get('limit') 假值回落 100）；其他 action 抛 ValueError；
 def _identity_call(cg, a):
     """身份特征识别统一入口（cg op=identity 与 mdcg_identity 共用）。
 
@@ -954,6 +1164,7 @@ def _identity_call(cg, a):
     raise ValueError(f"identity 未知 action：{act}")
 
 
+# 生效条件：act=(a.get("action") or "check").strip().lower()；"check" 时以 content/text、layer、condition_space、non_applicable_conditions、tags、exclude、limit=int(a.get("limit") or consistency.MAX_SCAN)、depth（非 None 时 int(depth)，否则 consistency.MAX_DEPTH）、auto_flywheel 调 cg.check_consistency；"history" 返回 {"records": cg.consistency_history(limit=int(a.get("limit") or 100))}；"stats" 返回 cg.consistency_stats()；"catalog" 返回 consistency.catalog()；其余 act 抛 ValueError。
 def _consistency_call(cg, a):
     """节点间自动冲突检测统一入口（cg op=consistency 与 mdcg_consistency 共用）。
 
@@ -982,6 +1193,7 @@ def _consistency_call(cg, a):
     raise ValueError(f"consistency 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'report'（空串/None 回退 'report'）分派，window=int(a.get('window') or 50)（a.get('window') 假值回落 50）：action=report 返回 cg.metacognition_report(window=window)；action=trace 返回 cg.metacognition_trace(window=window)；action=calibration 返回 cg.metacognition_calibration(max_scan=int(a.get('limit') or 2000))（a.get('limit') 假值回落 2000）；action=blindspots 返回 cg.metacognition_blindspots(limit=int(a.get('limit') or 20), window=window)（a.get('limit') 假值回落 20）；action=trust 返回 cg.metacognition_trust(window=window)；action=self_check 返回 cg.self_check(a.get('query') or a.get('text') or '', k=int(a.get('k') or 5))（query/text 假值回落 ''，k 假值回落 5）；action=history 返回 cg.metacognition_history(limit=int(a.get('limit') or 100))（a.get('limit') 假值回落 100）；action=catalog 返回 metacognition.catalog()；action=d_meta 返回 cg.metacognition_d_meta(window=window)（边界压力向量，三代理各自 [0,1]、不合成单值）；其他 action 抛 ValueError；
 def _metacognition_call(cg, a):
     """独立元认知统一入口（cg op=metacognition 与 mdcg_metacognition 共用）。
 
@@ -1011,9 +1223,12 @@ def _metacognition_call(cg, a):
     if act == "catalog":
         from . import metacognition
         return metacognition.catalog()
+    if act == "d_meta":                    # D_meta 观测面（只读，不合成单值）
+        return cg.metacognition_d_meta(window=window)
     raise ValueError(f"metacognition 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'snapshot'（空串/None 回退 'snapshot'）分派，subject=a.get('subject') or self_state.DEFAULT_SUBJECT（subject 假值回落常量），session=a.get('session') or getattr(getattr(cg, 'principal', None), 'session', None)（session 假值回落 principal.session）：action 为 snapshot/read/get 返回 {'state': self_state.snapshot(cg, subject)}；action=refresh 返回 self_state.refresh(cg, subject, window=int(a.get('window') or self_state.RECENT_WINDOW), importance=a.get('importance'), important_refs=a.get('important_refs'), dimensions=a.get('dimensions'), links=a.get('links'), actor=a.get('actor') or getattr(cg, 'actor', 'self_state'), force=bool(a.get('force')), strict=bool(a.get('strict')), session=session)（window 假值回落 self_state.RECENT_WINDOW）；action=bootstrap 返回 self_state.bootstrap(cg, subject, window=int(a.get('window') or self_state.RECENT_WINDOW), actor=a.get('actor') or 'bootstrap')；action=relate 返回 self_state.relate(cg, a.get('frm') or subject, a.get('to') or '', relation_type=a.get('relation_type') or 'collaborator', strength=a.get('strength', 0.5), condition=a.get('condition') or '', note=a.get('note') or '', reciprocal=bool(a.get('reciprocal')), actor=a.get('actor') or getattr(cg, 'actor', 'self_state'))；action=relations 返回 {'relations': self_state.relations(cg, subject=a.get('subject'), direction=(a.get('direction') or 'both'))}；action=index 时 dim,value=a.get('dim'),a.get('value')，若 dim 假值且 session 真值则 dim='session' 且 value=value or session，返回 self_state.index(cg, dim, value, limit=int(a.get('limit') or 50), with_content=bool(a.get('with_content')))（limit 假值回落 50）；action=dimensions 返回 self_state.dimensions(cg, subject)；action=audit 返回 self_state.audit(cg, subject, window=int(a.get('window') or self_state.RECENT_WINDOW))；action=history 返回 {'records': self_state.history(cg, limit=int(a.get('limit') or 100), subject=a.get('subject'))}（limit 假值回落 100）；action=summary 返回 self_state.summary(cg, subject, session=session)；action=catalog 返回 self_state.catalog()；其他 action 抛 ValueError；
 def _self_state_call(cg, a):
     """自我状态层统一入口（cg op=self_state 与 mdcg_self_state 共用）。
 
@@ -1075,6 +1290,7 @@ def _self_state_call(cg, a):
     raise ValueError(f"self_state 未知 action：{act}")
 
 
+# 生效条件：act=(a.get("action") or "routes").strip().lower()；act 属 routes/route/predict 时以 start_id=a.get("start_id") or a.get("node_id")、blindspot_id、horizon=int(a.get("horizon") or predict.HORIZON_DEFAULT)、max_branches=int(a.get("max_branches") or predict.MAX_BRANCHES_DEFAULT)、sort=a.get("sort") or "composite"、limit=int(a.get("limit") or 0)、semantic=bool(a.get("semantic", True)) 调 cg.predict_routes；act 属 feedback/rate 时调 cg.predict_feedback；act=="stats" 时调 cg.predict_stats(limit=int(a.get("limit") or 20))；act=="catalog" 时返回 predict.catalog()；其余 act 抛 ValueError。
 def _predict_call(cg, a):
     """生成式预测统一入口（cg op=predict 与 mdcg_predict 共用）。
 
@@ -1108,6 +1324,7 @@ def _predict_call(cg, a):
     raise ValueError(f"predict 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'path'（空串/None 回退 'path'）分派，a_id=a.get('a') or a.get('a_id') or a.get('from') or ''（假值链回落 ''），b_id=a.get('b') or a.get('b_id') or a.get('to') or ''：action 为 path/reach/reachable 返回 predict.causal_path(cg, a_id, b_id, max_depth=int(a.get('max_depth') or 5))（a.get('max_depth') 假值回落 5）；action 为 gate/filter 返回 {'ok': True, 'admitted': predict.causal_gate(cg, a_id, b_id) 的 ok, 'reason': why, 'a': a_id, 'b': b_id, 'note': '语义邻近须能说清关系（因果链/共同父节点/偏好权重>0.5）'}；action=chain 返回 cg.causal_chain(a.get('node_id') or a_id, relation_types=a.get('relation_types'), max_depth=int(a.get('max_depth') or chain.MAX_DEPTH_DEFAULT), direction=a.get('direction') or 'out', sort=a.get('sort') or 'strength')；action=explain 返回 cg.explain_chain(a.get('node_id') or a_id)；action=catalog 返回包含 module/types/chain_types_default/edge_weights/max_depth_default/note/gate/actions 的 dict（gate 取 predict.catalog()['decisions']['D-002']）；其他 action 抛 ValueError；
 def _causal_call(cg, a):
     """因果推理统一入口（cg op=causal 与 mdcg_causal 共用）。
 
@@ -1146,6 +1363,7 @@ def _causal_call(cg, a):
     raise ValueError(f"causal 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'summary'（空串/None 回退 'summary'）分派：action 为 record/add/log 返回 {'entry': cg.evolution_record(node_id=a.get('node_id'), pattern=a.get('rule') or a.get('pattern') or '', missing=a.get('missing') or '', action=a.get('change') or a.get('note') or '', evidence=a.get('evidence') or '', source=a.get('source') or '', kind=a.get('kind') or evolution.KIND_CONDITION_GAP)}（各字段假值回落）；action 为 entries/list 返回 cg.evolution_entries(limit=int(a.get('limit') or 50), node_id=a.get('node_id'), kind=a.get('kind'))（a.get('limit') 假值回落 50）；action 为 show/get 返回 cg.evolution_show(a.get('entry_id') or '')；action=history 返回 cg.evolution_history(a.get('node_id') or '', limit=int(a.get('limit') or 50))（a.get('limit') 假值回落 50）；action 为 patterns/regularities 返回 cg.evolution_patterns(limit=int(a.get('limit') or 10))（a.get('limit') 假值回落 10）；action=summary 返回 cg.evolution_summary()；action 为 rollback/revert/undo 时若 cg.principal 非 None 先调用 cg.principal.require_admin('evolution_rollback')，再返回 cg.evolution_rollback(a.get('entry_id') or '', dry_run=bool(a.get('dry_run')), note=a.get('note') or '')；action=catalog 返回 evolution.catalog()；其他 action 抛 ValueError；
 def _evolution_call(cg, a):
     """演化账本统一入口（cg op=evolution 与 mdcg_evolution 共用）。
 
@@ -1188,6 +1406,7 @@ def _evolution_call(cg, a):
     raise ValueError(f"evolution 未知 action：{act}")
 
 
+# 生效条件：value 为 None 时返回 []，value 为 list/tuple/set 时按其元素、其它类型按 str(value).replace(",", " ").split() 取项，再对每项 str(x).strip()，非空且未出现过才按序追加并返回去重列表。
 def _split_ids(value):
     """把 'a,b c' / ['a','b'] / 'a' 统一成去空白的 id 列表（None → []）。
 
@@ -1208,6 +1427,7 @@ def _split_ids(value):
     return out
 
 
+# 生效条件：始终构造 ex（verify=a.get("verify")、importance=float(a["importance"]) 当 a.get("importance") is not None 否则 None、verification_basis=a.get("verification_basis") or (verdict or {}).get("basis")、non_applicable_conditions、role、derived_from=_split_ids(a.get("derived_from")) or None、relation），返回其中值不属于 (None, [], '', {}) 的键值对。
 def _proposal_extras(a, verdict=None):
     """入队时保全 write 的落盘要素，避免裁决 accept 后退化成默认值。
 
@@ -1235,6 +1455,7 @@ def _proposal_extras(a, verdict=None):
     return {k: v for k, v in ex.items() if v not in (None, [], "", {})}
 
 
+# 生效条件：act 取 a.get("action") 转 str 去空白并 lower 后缺省 "status"，name 取 a.get("name") 或环境变量 MDCG_SUSTAIN_NAME 或 "md_cg"；status/info 只读诊断，自愈类 act 只回收派生物（索引重扫、临时分片、日志轮转、心跳戳），永不删除节点、不代签密钥；
 def _sustain_call(cg, a):
     """持续性自维持统一入口（常驻 / 心跳 / 自愈 / 会话续接）。
 
@@ -1343,6 +1564,7 @@ def _sustain_call(cg, a):
     raise ValueError(f"sustain 未知 action：{act}")
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'sweep'（空串/None 回退 'sweep'）分派，ids/kinds 若为字符串则按逗号或空白拆成列表，node_id=a.get('node_id') or a.get('node')，target=ids or ([node_id] if node_id else None)（ids 假值回落 node_id 列表或 None）：action 为 sample/spot_check 返回 scrub.sample(cg, int(a.get('k') or a.get('n') or scrub.DEFAULT_SAMPLE), strategy=a.get('strategy') or 'stratified', seed=a.get('seed'))（k/n 假值链回落 scrub.DEFAULT_SAMPLE）；action 为 associate/related 时若 node_id 假值抛 ValueError，否则返回 scrub.associate(cg, node_id, hops=int(a.get('hops') or scrub.DEFAULT_HOPS), limit=int(a.get('k') or 30), lexical=bool(a.get('lexical', True)))（hops 假值回落常量，k 假值回落 30，lexical 缺键为 True）；action 为 audit/check 返回 scrub.audit(cg, target, hops=int(a.get('hops') or 1), min_severity=a.get('min_severity') or 'info')；action 为 decontaminate/repair 返回 scrub.decontaminate(cg, target, kinds=kinds, dry_run=bool(a.get('dry_run', True)), min_severity=a.get('min_severity') or 'medium', hops=int(a.get('hops') or 1), actor=a.get('actor'), override=bool(a.get('override')))；action 为 calibrate/calibration 返回 scrub.calibrate(cg, apply=bool(a.get('apply')), override=bool(a.get('override')), actor=a.get('actor'))；action 为 sweep/run 返回 scrub.sweep(cg, n=int(a.get('k') or a.get('n') or scrub.DEFAULT_SAMPLE), seed=a.get('seed'), dry_run=bool(a.get('dry_run', True)), hops=int(a.get('hops') or scrub.DEFAULT_HOPS), strategy=a.get('strategy') or 'stratified', apply_calibration=bool(a.get('apply')), actor=a.get('actor'))；action 为 history/log 返回 scrub.history(cg, limit=int(a.get('k') or 100))（k 假值回落 100）；action=summary 返回 scrub.summary(cg)；action=catalog 返回 scrub.catalog()；其他 action 抛 ValueError；
 def _scrub_call(cg, a):
     """记忆自净统一入口（抽查 / 联想 / 去污染 / 校准偏差）。
 
@@ -1400,8 +1622,77 @@ def _scrub_call(cg, a):
     raise ValueError(f"scrub 未知 action：{act}")
 
 
+# ---- action 缺省防呆（2026-09-16）------------------------------------------
+# 与「op 缺省静默降级」同构的第二类静默失败：op 传了、action 漏了 → 各分支按
+# 字面量默认 action 执行。若默认恰是**读类**，写意图会被静默吞掉且返回形似正常
+# 的结果——最典型是文档化契约 `cg(op=review, pid, decision, reason)`（不带
+# action）实际静默走 review_list，裁决从未落盘（契约与实现漂移）。
+# 处置：签名明确指向非默认 action → 按签名推导并透出 action_derived/hint_action；
+# 无签名可依 → 维持默认执行但同样透出标记，让「按默认走」可见而非静默。
+# 判据用「键存在且非 None」（False / 0 / "" 属显式传入），避免真值判断误吞。
+_ACTION_SIGS = {
+    "review":  (("decision", "decide"), ("node_id", "verify_record")),
+    "recent":  (("text", "add"), ("content", "add")),
+    "goal":    (("goal", "add"), ("action_hint", "add")),
+    # task：**写意图优先、读意图最后**。name→open 先命中——open（upsert）本身
+    # 兼容 plan/result/change 全字段，故「name+change」同传也不会丢信息；把
+    # change→plan_add 放其后，只在「只给 change」时才是纯追加变更。node_id→get
+    # 置于末位：否则「node_id+change」会被静默当成只读（写意图被吞，
+    # 与 review 的 `pid+decision` 静默走 list 同构）。
+    "task":    (("name", "open"), ("task_status", "status"),
+                ("result", "status"), ("change", "plan_add"),
+                ("node_id", "get")),
+    "predict": (("hit", "feedback"), ("predicted_node_id", "feedback"),
+                ("actual_node_id", "feedback")),
+    "session": (("summary", "note"), ("text", "note"), ("content", "note")),
+    "insight": (("statement", "record"),),
+    "whitebox": (("questions", "verify_existing"), ("question", "ask"),
+                 ("message", "ask"), ("query", "ask"),
+                 ("marker", "verify_encoding"),
+                 ("content", "remember"), ("text", "remember")),
+}
+
+# op → 分支内缺省 action 字面量。**仅供缺省透出提示，不参与执行**；与各
+# _xxx_call / 分支里的 `a.get("action") or "<默认>"` 保持同步（同源守卫见
+# test_action_derive.py）。
+_ACTION_DEFAULT = {
+    "theory": "check", "link": "ls", "scrub": "sweep", "forget": "forget",
+    "protect": "stats", "identity": "profile", "consistency": "check",
+    "metacognition": "report", "self_state": "snapshot", "predict": "routes",
+    "causal": "path", "evolution": "summary", "sustain": "status",
+    "goal": "list", "task": "list", "recent": "list", "review": "list", "session": "recall",
+    "ingest": "stat", "export": "stat", "maintain": "stat",
+    "consolidate": "promote", "insight": "outlook",
+    "ccg": "compile", "ref": "read", "whitebox": "ping",
+}
+
+
+# 生效条件：op == "ingest" 时若 str(a.get("path") or "").strip() 非空，则按 a.get("patterns") 为真值→("dir","patterns")、该 path 小写以 ".jsonl" 结尾→("jsonl","path(*.jsonl)")、否则→("file","path")；其他 op 按常量 _ACTION_SIGS.get(op, ()) 的顺序取第一个 key 存在于 a 且 a.get(key) is not None 的项返回 (act, key)，无匹配则返回 (None, None)；
+def _action_sig(a, op):
+    """action 缺省时的签名推导 → (action, 依据键)；无签名可依 → (None, None)。
+
+    `ingest` 单独处理：其 op 语义是**写**（摄入），缺省 action 却是**读**（stat）
+    ——「传了 path 却静默 stat」会把摄入整件事吞掉。类型按**保守优先**推导：
+    patterns→dir、`*.jsonl`→jsonl、其余 path→file（file 最保守：若实为目录会
+    报错可见，而不会误把整棵目录树摄进来）。
+    """
+    if op == "ingest":
+        path = str(a.get("path") or "").strip()
+        if path:
+            if a.get("patterns"):
+                return "dir", "patterns"
+            if path.lower().endswith(".jsonl"):
+                return "jsonl", "path(*.jsonl)"
+            return "file", "path"
+    for key, act in _ACTION_SIGS.get(op, ()):
+        if key in a and a.get(key) is not None:
+            return act, key
+    return None, None
+
+
+# 生效条件：op0=(a.get("op") or "").strip().lower()，op0 为空时按 a.get("content")→"write"、a.get("query") 或 a.get("node_id")→"read"、a.get("intent")→"route"、都无→"read" 推导 op；act0=(args.get("action") or "").strip().lower()，act0 为空时用 _action_sig(args, op) 推导且推导出时写回 args["action"]；args["op"]=op 后调 _cg_dispatch，返回 dict 且 op0 为空时补 out["op"]、out["op_derived"]=True 与 hint，act0 为空且 (act_derived 或 op in _ACTION_DEFAULT) 时 setdefault("action", eff)、out["action_derived"]=True 并按是否有 act_derived 写 hint_action。
 def _cg_call(cg, a):
-    """认知图唯一入口（外层：op 缺省推导兜底 + 推导透出；分发主体见 _cg_dispatch）。"""
+    """认知图唯一入口（外层：op/action 缺省推导兜底 + 推导透出；主体见 _cg_dispatch）。"""
     op0 = (a.get("op") or "").strip().lower()
     op = op0
     if not op:
@@ -1416,23 +1707,222 @@ def _cg_call(cg, a):
         else:
             op = "read"        # 无任何签名可依：维持旧缺省 read
     args = dict(a)
+    act0 = (args.get("action") or "").strip().lower()
+    act_sig = act_derived = None
+    if not act0:
+        act_derived, act_sig = _action_sig(args, op)
+        if act_derived:
+            args["action"] = act_derived     # 按签名补 action：避免写意图被默认吞掉
     args["op"] = op
     out = _cg_dispatch(cg, args)
-    if isinstance(out, dict) and not op0:
-        out["op"] = op
-        out["op_derived"] = True
-        out["hint"] = ("op 未显式传入，已按参数签名推导（本次按 %s 执行）；op 为必填参数，"
-                       "复杂任务中也请始终显式传 op，避免静默执行错误意图" % op)
+    if isinstance(out, dict):
+        if not op0:
+            out["op"] = op
+            out["op_derived"] = True
+            out["hint"] = ("op 未显式传入，已按参数签名推导（本次按 %s 执行）；op 为必填参数，"
+                           "复杂任务中也请始终显式传 op，避免静默执行错误意图" % op)
+        if not act0 and (act_derived or op in _ACTION_DEFAULT):
+            eff = act_derived or _ACTION_DEFAULT[op]
+            out.setdefault("action", eff)
+            out["action_derived"] = True
+            if act_derived:
+                out["hint_action"] = (
+                    "action 未显式传入，已按参数 %s 推导为 action=%s（旧行为会静默走默认 %s，"
+                    "意图被吞）；建议显式传 action" % (act_sig, act_derived,
+                                                     _ACTION_DEFAULT.get(op, "?")))
+            else:
+                out["hint_action"] = (
+                    "action 未显式传入，本次按 %s 的默认 action=%s 执行；"
+                    "若意图是其它 action 请显式传 action" % (op, eff))
+        # 状态摘要协议（**单出口挂载**，控制爆炸半径——不逐 op 改造）：
+        # 把「它还成不成立」（验证态/存疑/异常/时效）以状态头透出，并把既有
+        # hint 升级为状态头格式（MDCG_STATUS_HEAD=0 回退旧文本）。挂载失败不阻断读面。
+        try:
+            from . import statushdr
+            statushdr.annotate(cg, out)
+        except Exception as exc:                           # noqa: BLE001
+            out.setdefault("status_head_error", type(exc).__name__)
     return out
 
 
+def _status_call(cg, a):
+    """验证态 / 依赖 / 双时间轴 / 履历查询（op=status，**只读**）。
+
+    真源 `md_cg/trust.py`。三形态（`cg(op="status")` 取摘要，`node_id=` 取单节点）：
+      · 给 `node_id`     → 单节点全貌（describe + 履历 + 状态头渲染）；
+      · 不给 / patrol    → 全库摘要（存疑 / 过期 / 未生效 / 悬空四类计数）；
+      · `action=ledger`  → 读验证态台账（`_trust.jsonl`，可按节点过滤）。
+    """
+    from . import statushdr, trust
+    nid = str(a.get("node_id") or a.get("id") or "").strip()
+    act = str(a.get("action") or "").strip().lower()
+    limit = int(a.get("limit") or 20)
+    if act in ("ledger", "log"):
+        rows = trust.load_ledger(cg, node_id=nid or None, limit=limit)
+        return {"op": "status", "action": "ledger", "node_id": nid or None,
+                "count": len(rows), "rows": rows, "readonly": True}
+    if nid and act not in ("patrol", "summary"):
+        de = trust.describe(cg, nid)
+        de.update({"op": "status", "action": "describe", "readonly": True,
+                   "status_head": statushdr.render(cg, nid),
+                   "ledger": trust.load_ledger(cg, node_id=nid, limit=limit)})
+        return de
+    rep = trust.patrol(cg, limit=limit)
+    rep.update({"op": "status", "action": act or "summary",
+                "summary": trust.summary(cg), "catalog": trust.catalog(cg.root)})
+    # 摘要形态主动挂全库级状态头（annotate 的 _collect_ids 找不到 node_id 不会自动注入）
+    s = rep.get("summary") or {}
+    bits = []
+    dc = s.get("doubted", 0)
+    ec = s.get("expired", 0)
+    nc = s.get("not_yet", 0)
+    uc = s.get("unverified", 0)
+    vc = s.get("verified", 0)
+    if ec:
+        bits.append(f"{statushdr.MARK_ABNORMAL} 异常({ec})")
+    if dc:
+        bits.append(f"{statushdr.MARK_DOUBTED} 存疑({dc})")
+    if nc:
+        bits.append(f"{statushdr.MARK_MODIFIED} 未生效({nc})")
+    if vc:
+        bits.append(f"{statushdr.MARK_VERIFIED} 已验证({vc})")
+    if uc:
+        bits.append(f"{statushdr.MARK_UNVERIFIED} 未验证({uc})")
+    rep["status_head"] = " · ".join(bits) if bits else statushdr.MARK_UNVERIFIED + " 空"
+    # 冷路径队列状态（2026-09-19 热温冷分层）
+    try:
+        from . import coldverify as _cv
+        q = _cv.get(cg)
+        if q is not None:
+            rep["coldverify"] = q.status()
+    except Exception:                                  # noqa: BLE001
+        pass
+    return rep
+
+
+# 生效条件：a 的 child/parent/relation/batch/时间五参/ordering/aggregation/offset/limit/expand_nodes 原样透传给 provenance.find_edges（本层不校验、不填默认，合法性单点在库层）；始终返回该只读结果字典（含 edges/total/matched/returned/aggregates/time_filter 审计块）。
+def _edges_call(cg, a):
+    """三元组反查（op=edges，**只读**）：按任意端 / 谓词 / 时间反查派生边。
+
+    三元组术语 `subject / predicate / object` 在本层就是 `child / rel / parent`
+    （即 `derived_from` 派生边）——**不新造第二套参数**：`cg` 工具面是扁平
+    schema，`subject` 已被 `identity`（主体语义）占用，同名异义会把两处口径搅在
+    一起；且 `relation`/`child`/`parent`/`batch` 已是 `link derive` 的既有谓词面。
+
+    参数**原样透传、不填默认、不做二次校验**，与 `_read_call` 同一策略：
+    合法性判定单点在库层（`provenance._ordering_of/_aggregation_of` 与
+    `trust.check_time_args`）。本层若自补默认，缺省轴（边 = `observed`，检索 =
+    `effective`）与枚举集就会两处分叉，日后必然漂移。
+
+    不暴露 `path`（库层测试用注入点）：MCP 面不接受文件系统路径。
+    """
+    from . import provenance as _pv
+    return _pv.find_edges(
+        cg,
+        child=a.get("child"), parent=a.get("parent"),
+        relation=a.get("relation"), batch=a.get("batch"),
+        start_time=a.get("start_time"), end_time=a.get("end_time"),
+        start_operator=a.get("start_operator"), end_operator=a.get("end_operator"),
+        time_axis=a.get("time_axis"),
+        ordering=a.get("ordering"), offset=a.get("offset") or 0,
+        limit=a.get("limit"), aggregation=a.get("aggregation"),
+        expand_nodes=bool(a.get("expand_nodes")))
+
+
+# 生效条件：始终调 help_text(ALL_TOOLS, query=a.get("query") or a.get("intent"), limit=int(a.get("limit") or a.get("k") or 40)) 并返回其结果。
+def _help_call(cg, a):
+    """按需披露入口（工具面渐进披露的读取面，见 md_cg/tool_face.py）。
+
+    常驻上下文只留「一行职责 + 参数短提示」；被投影掉的完整 op/参数语义
+    在此从真源无损取回——所以瘦身不损失能力，只把「随时付费」换成「按需取」。
+    只读元信息（工具 schema 本身对客户端可见），故不过角色权限闸。
+    """
+    from .tool_face import help_text
+    return help_text(ALL_TOOLS, query=a.get("query") or a.get("intent"),
+                     limit=int(a.get("limit") or a.get("k") or 40))
+
+
+# 生效条件：当 cg、a 传入时，act=(a.get('action') or '').strip().lower()（空串/None 得空串），若 act 空则 act=_action_sig(a, 'task')[0] or 'list'，name=a.get('name') or a.get('task_name') or a.get('task') or ''，nid=a.get('node_id') or a.get('task_id') or ''，tstat=a.get('task_status') or a.get('new_status') or ''（各假值链回落 ''）：act 为 open/add/upsert 时 importance 取 a.get('importance')，非 None 则 float、转换失败置 None，返回 _t.upsert(cg, name or nid, plan=a.get('plan'), status=tstat or None, result=a.get('result'), condition=a.get('condition'), goal=a.get('goal_text') or a.get('goal'), acceptance=a.get('acceptance'), boundary=a.get('boundary'), change=a.get('change'), note=a.get('note'), tags=a.get('tags'), importance=imp, actor=a.get('actor'))；act 为 status/set_status 时若 tstat 假值返回 {'ok': False, 'error': '缺 task_status', 'hint': '可选 active|blocked|done|dropped；迁 done 必须同时给 result'}，否则返回 _t.set_status(cg, nid or name, tstat, result=a.get('result'), note=a.get('note'), actor=a.get('actor'))；act=plan_add 返回 _t.plan_add(cg, nid or name, a.get('change') or a.get('text'), actor=a.get('actor'))；act=get 返回 _t.get_task(cg, nid or name)；act=find 返回 _t.find_similar(cg, name, k=int(a.get('k') or a.get('limit') or 5))（k/limit 假值链回落 5）；act=session 返回 _t.session_tasks(cg, active_limit=int(a.get('active_limit') or 5), done_limit=int(a.get('done_limit') or 5))（各假值回落 5）；act 非 list 时返回 {'ok': False, 'error': '未知 task action：%r' % act, 'hint': '可选 open|status|plan_add|get|list|find|session'}；act=list 返回 _t.list_tasks(cg, status=tstat or None, limit=a.get('limit'))；
+def _task_call(cg, a):
+    """结构层任务实体（op=task）——跨会话的工程台账。
+
+    action:
+      open / add   登记或更新任务卡（**同名即同卡**；未给字段沿用旧值，不静默清空）
+      status       状态迁移（active|blocked|done|dropped；迁 done 时「结果」必填）
+      plan_add     追加计划变更（执行中发现的偏差与新问题）
+      get          单卡全字段读回
+      list         任务清单（默认；可按 task_status 过滤）
+      find         同族任务提示（**只提示，不自动合并**）
+      session      会话装配面（进行中 + 近期完成）——供上下文召回
+
+    :param name: 任务名（身份判据：同名即同任务，slug 归一后落节点 id）
+    """
+    from . import tasks as _t
+    act = (a.get("action") or "").strip().lower()
+    if not act:
+        act = _action_sig(a, "task")[0] or "list"
+    name = a.get("name") or a.get("task_name") or a.get("task") or ""
+    nid = a.get("node_id") or a.get("task_id") or ""
+    tstat = a.get("task_status") or a.get("new_status") or ""
+
+    if act in ("open", "add", "upsert"):
+        imp = a.get("importance")
+        try:
+            imp = float(imp) if imp is not None else None
+        except (TypeError, ValueError):
+            imp = None
+        return _t.upsert(cg, name or nid,
+                         plan=a.get("plan"), status=tstat or None,
+                         result=a.get("result"), condition=a.get("condition"),
+                         goal=a.get("goal_text") or a.get("goal"),
+                         acceptance=a.get("acceptance"), boundary=a.get("boundary"),
+                         change=a.get("change"), note=a.get("note"),
+                         tags=a.get("tags"), importance=imp, actor=a.get("actor"))
+
+    if act in ("status", "set_status"):
+        if not tstat:
+            return {"ok": False, "error": "缺 task_status",
+                    "hint": "可选 active|blocked|done|dropped；迁 done 必须同时给 result"}
+        return _t.set_status(cg, nid or name, tstat, result=a.get("result"),
+                             note=a.get("note"), actor=a.get("actor"))
+
+    if act == "plan_add":
+        return _t.plan_add(cg, nid or name, a.get("change") or a.get("text"),
+                           actor=a.get("actor"))
+
+    if act == "get":
+        return _t.get_task(cg, nid or name)
+
+    if act == "find":
+        return _t.find_similar(cg, name, k=int(a.get("k") or a.get("limit") or 5))
+
+    if act == "session":
+        return _t.session_tasks(cg, active_limit=int(a.get("active_limit") or 5),
+                                done_limit=int(a.get("done_limit") or 5))
+
+    if act != "list":
+        return {"ok": False, "error": "未知 task action：%r" % act,
+                "hint": "可选 open|status|plan_add|get|list|find|session"}
+
+    return _t.list_tasks(cg, status=tstat or None, limit=a.get("limit"))
+
+
+# 生效条件：op 取 a.get("op") 转 str 去空白并 lower；缺失时按参数签名回推（含 content→write / query|node_id→read / intent→route；无签名可推时维持 read），op=="help" 在角色闸门之前直通 _help_call；其余 op 先经 cg.principal.require_op(op)（越权即 AccessDenied）再按 alias→内联名→cli 表分派；未识别 op 抛 ValueError；
 def _cg_dispatch(cg, a):
     """认知图唯一入口的 op 分发主体。"""
     op = (a.get("op") or "read").strip().lower()
+    if op == "help":
+        return _help_call(cg, a)
     _p = getattr(cg, "principal", None)
     if _p is not None and hasattr(_p, "require_op"):
         _p.require_op(op)          # 角色作用域闸门：越权即 AccessDenied
 
+    if op == "status":
+        return _status_call(cg, a)
+
+    if op == "edges":
+        return _edges_call(cg, a)
+
     if op == "theory":
         from . import theory as _th
         act = (a.get("action") or "check").strip().lower()
@@ -1561,12 +2051,15 @@ def _cg_dispatch(cg, a):
 
     if op == "info":
         from . import audit
+        from . import nodefile
         from . import theory as _th
         from . import links as _lk
         h = cg.health_os()
         h.update({"surface": SURFACE,
                   "tools": [t["name"] for t in tools_for_surface()],
-                  "audit_kinds": audit.kinds(), "whoami": cg.whoami()})
+                  "audit_kinds": audit.kinds(), "whoami": cg.whoami(),
+                  # 裁定 B：CCG 六要素的契约角色（术语真源在 nodefile，此处只透出）
+                  "ccg_contract": dict(nodefile.CCG_CONTRACT_ROLES)})
         # 能力外置可观测：本进程实际注入了哪些外部验证器（含失败原因）
         h["external_verifiers"] = audit.load_external_verifiers()
         h["theory"] = _th.check()
@@ -1576,7 +2069,8 @@ def _cg_dispatch(cg, a):
     if op == "route":
         intent = a.get("intent") or a.get("query") or ""
         res, meta = cg.search(intent, k=int(a.get("k") or 10),
-                              context=a.get("context"), record=False)
+                              context=a.get("context"), record=False,
+                              view=a.get("view"))
         knowledge, caps = [], []
         for n, s, q in res:
             fm = n.get("frontmatter") or {}
@@ -1594,8 +2088,20 @@ def _cg_dispatch(cg, a):
                 "note": "认知图只给知识与建议能力名，不执行；由调用方决定"}
 
     if op == "read":
+        # 时间算子（阶段二 4.1）：**原样透传**五个时间入参——本层不做校验也不填
+        # 默认值，合法性判定单点在库层 `trust.check_time_args`（默认轴 effective
+        # 亦由库层 `time_axis_of` 决定）。本层若自填默认值，两处口径就会分叉。
+        _tkw = {"start_time": a.get("start_time"), "end_time": a.get("end_time"),
+                "start_operator": a.get("start_operator"),
+                "end_operator": a.get("end_operator"),
+                "time_axis": a.get("time_axis"),
+                # 角色化读取视图（第四阶段 6.1）：原样透传，合法性判定单点在
+                # roleviews.ROLE_VIEWS（非法 view 库层 ValueError），与时间算子
+                # 同一透传纪律——本层不做校验也不填默认值。
+                "view": a.get("view")}
         if a.get("node_id"):
-            return _node_view(cg.get(a["node_id"]))
+            return _node_view(cg.get(a["node_id"]),
+                              offset=int(a.get("offset") or 0))
         q = a.get("query") or a.get("intent") or ""
         if a.get("budget_tokens"):
             return cg.recall(q, budget_tokens=int(a["budget_tokens"]),
@@ -1603,121 +2109,25 @@ def _cg_dispatch(cg, a):
                              goal_text=a.get("goal"),
                              include_recent=bool(a.get("include_recent")),
                              recent_limit=int(a.get("limit") or 10),
-                             session=a.get("session"))
+                             session=a.get("session"),
+                             validity=a.get("validity"), **_tkw)
         from . import refindex
         res, meta = cg.search(q, layer=a.get("layer"), k=int(a.get("k") or 20),
                               context=a.get("context"),
-                              session=a.get("session"))
+                              session=a.get("session"),
+                              validity=a.get("validity"), **_tkw)
         return {"meta": meta, "results": [
             {"node": _node_view(n), "score": s, "state": q2.get("state"),
              "reason": q2.get("reason"), **refindex.ref_fields(n)}
             for n, s, q2 in res]}
 
     if op == "write":
-        from . import audit
-        verdict = audit.audit(
-            (a.get("content_kind") or "").strip(),
-            {"content": a.get("content", ""), "action": a.get("action"),
-             "sensitivity": a.get("sensitivity"),
-             "topic": a.get("query") or a.get("intent")},
-            {"cg": cg, "principal": getattr(cg, "principal", None)})
-        nid = a.get("node_id") or ("mem_" + str(int(__import__("time").time() * 1000)))
-        st = verdict["state"]
-        if st == audit.ACCEPT:
-            # 节点间自动冲突检测（三级决策：情绪→反思→递归反思）：
-            # 写入前与既有条件/纪律校验；不通过则不落盘（可进审核队列）。
-            # 与 mdcg_remember 同源、默认开启——「信息的修改必须先通过校验」。
-            cvd = None
-            if bool(a.get("consistency", True)):
-                oc = (a.get("on_conflict") or "defer").strip().lower()
-                cvd = cg.check_consistency(
-                    a.get("content", ""),
-                    layer=a.get("layer") or ("contextual" if a.get("gated")
-                                             else "knowledge"),
-                    condition_space=a.get("condition_space"),
-                    non_applicable_conditions=a.get("non_applicable_conditions"),
-                    tags=a.get("tags"), exclude=nid, auto_flywheel=True)
-                v = cvd.get("verdict")
-                blocked = ((v == "REJECT" and oc == "reject")
-                           or (v in ("REJECT", "BLINDSPOT") and oc == "defer"))
-                if blocked:
-                    if oc == "reject":
-                        return {"ok": False, "id": nid, "committed": False,
-                                "moved_to": "conflict_rejected",
-                                "consistency": cvd, "verdict": verdict}
-                    pid = cg.propose(nid, a.get("content", ""),
-                                     layer=a.get("layer") or "knowledge",
-                                     tags=a.get("tags"),
-                                     condition_space=a.get("condition_space"),
-                                     **_proposal_extras(a, verdict))
-                    return {"ok": False, "id": nid, "pid": pid, "committed": False,
-                            "moved_to": "review_queue", "consistency": cvd,
-                            "verdict": verdict,
-                            "hint": "这是冲突闸门的正常行为：本次写入与既有条件/纪律冲突"
-                                    "（on_conflict=defer），已转入审核队列待裁决——"
-                                    "不是工具故障，重试同样结果；"
-                                    "落盘须由设计者权限（can_admin）裁决，转告使用者："
-                                    "python scripts/review_cli.py list 后 accept/reject，"
-                                    "或 cg(op=review, pid=<pid>, decision=accept|reject|"
-                                    "edit|merge, reason=<理由>)"}
-            if a.get("gated"):
-                hint = a.get("importance_hint")
-                if hint is None and a.get("importance") is not None:
-                    hint = float(a["importance"])
-                res = cg.remember_gated(
-                    nid, a.get("content", ""), layer=a.get("layer") or "contextual",
-                    role=a.get("role"), tags=a.get("tags"),
-                    condition_space=a.get("condition_space"),
-                    verification_basis=(a.get("verification_basis")
-                                        or verdict.get("basis")),
-                    non_applicable_conditions=a.get("non_applicable_conditions"),
-                    importance_hint=hint, override=bool(a.get("override")),
-                    consistency=False,
-                    derived_from=_split_ids(a.get("derived_from")),
-                    relation=a.get("relation"))
-                v = res.get("verdict")
-                committed = v == "ACCEPT"
-                out = {"ok": committed, "id": nid, "committed": committed,
-                       "gate": res, "verdict": verdict}
-                if cvd is not None:
-                    out["consistency"] = cvd
-                if v == "MERGE":
-                    out["moved_to"] = "merged_into:" + str(res.get("merged_into"))
-                elif v in ("DROP", "DEFER"):
-                    out["moved_to"] = v.lower()
-                return out
-            cg.add(nid, a.get("content", ""), layer=a.get("layer") or "knowledge",
-                   tags=a.get("tags"), condition_space=a.get("condition_space"),
-                   importance=float(a.get("importance", 0.5)),
-                   verification_basis=a.get("verification_basis") or verdict.get("basis"),
-                   non_applicable_conditions=a.get("non_applicable_conditions"),
-                   override=bool(a.get("override")), consistency=False,
-                   derived_from=_split_ids(a.get("derived_from")),
-                   relation=a.get("relation"))
-            out = {"ok": True, "id": nid, "committed": True, "verdict": verdict}
-            if cvd is not None:
-                out["consistency"] = cvd
-            return out
-        if st == audit.REJECT:
-            rid = cg.add_rejected((a.get("content") or "")[:200], verdict["evidence"],
-                                  verification_basis=verdict.get("basis") or "test",
-                                  tags=a.get("tags"))
-            return {"ok": False, "id": rid, "committed": False,
-                    "moved_to": "rejected", "verdict": verdict,
-                    "hint": "这是审核闸门的正常行为：内容未过内容政策审核（REJECT），"
-                            "已记入负记忆——不是工具故障，重试同样结果；"
-                            "拒绝依据见 verdict.evidence"}
-        pid = cg.propose(nid, a.get("content", ""), layer=a.get("layer") or "knowledge",
-                         tags=a.get("tags"), condition_space=a.get("condition_space"),
-                         **_proposal_extras(a, verdict))
-        return {"ok": True, "id": nid, "pid": pid, "committed": False,
-                "moved_to": "review_queue", "verdict": verdict,
-                "hint": "这是校验闸门的正常行为（verdict=%s）：内容未达 ACCEPT，"
-                        "已入审核队列——不需要重试；落盘须由设计者权限（can_admin）"
-                        "对提案 pid 裁决（agent 端无裁决权是设计），转告使用者："
-                        "python scripts/review_cli.py list 后 accept/reject，"
-                        "或 cg(op=review, pid=<pid>, decision=accept|reject|"
-                        "edit|merge, reason=<理由>)" % verdict.get("state")}
+        # 写入路径拦截器链（Pi 钩子化移植，writepipe.py）：六道闸以扩展
+        # 形态注册于 writepipe.default_pipeline()，次序/启停不再硬编码于
+        # 本文件；新增闸门 = register_before 一行，即插即拔。
+        # 角色/层权限校验在 MdCGSecure.add 库层，结构上不可被拦截器绕过。
+        from .writepipe import default_pipeline
+        return default_pipeline().execute(cg, a)
 
     if op == "goal":
         act = (a.get("action") or "list").strip().lower()
@@ -1738,6 +2148,9 @@ def _cg_dispatch(cg, a):
                                        limit=int(a.get("limit") or 20)),
                 "active": cg.active_goals(limit=int(a.get("limit") or 5))}
 
+    if op == "task":
+        return _task_call(cg, a)
+
     if op == "recent":
         act = (a.get("action") or "list").strip().lower()
         if act in ("add", "append", "remember"):
@@ -1758,6 +2171,10 @@ def _cg_dispatch(cg, a):
         act = (a.get("action") or "list").strip().lower()
         if act == "list":
             return {"pending": cg.review_list()}
+        if act == "stats":
+            # 裁决动作分布（含 noop）：无此出口则「已评估、判定无需改动」这类
+            # 裁决只在 jsonl 里躺着，治理面看不到——与「静默忽略」等价。
+            return cg.review_stats()
         if act == "rounds":
             pid = a.get("pid", "")
             return {"pid": pid, "rounds": cg.review_rounds(pid)}
@@ -1898,9 +2315,184 @@ def _cg_dispatch(cg, a):
     if op == "insight":
         return _insight_call(cg, a)
 
+    if op == "ccg":
+        return _ccg_call(cg, a)
+
     raise ValueError(f"cg 未知 op：{op}")
 
 
+# 生效条件：由 _cg_dispatch 在 op=="ccg" 时进入；action 取 a.get("action") 缺省 "compile"；compile 只产出候选（落 _ccgc_pending/ 待复核、不当场写库），link 才准入落库，attest/recalibrate 须编外验证方且 verifier != compiled_by（E041/E042/E043 机械把关）；
+def _ccg_call(cg, a):
+    """CCG 六要素编译器（op=ccg）：对话记录 → 六要素候选 → **编外复核** → 落库。
+
+    定位：**记忆可靠性闸**——不是又一个写入通道，而是写入前「条件是否成立」的检查。
+    裁定 A（LLM 不得自己验证自己）由 ccgc 的 E041 **机械执行**，不依赖 prompt 自觉。
+
+    action（缺省 compile）：
+        compile      对话记录 → 六要素候选（五环编译）；候选+签章槽落
+                    `_ccgc_pending/<node_id>.json`（**不当场写库**）
+        review       派发编外复核单元：**蜂巢 reflect/verify 优先** → 不可用则提示配置
+                    → 显式 allow_degrade 才降级 harness 端子代理；拿到裁决即自动签章
+        attest       外部裁决签章（verifier 须 != compiled_by；E041/E042 机械把关）
+        link         读回候选+签章 → 准入校验 → apply=True 落库（成功后清 pending）
+        recalibrate  四槽修正（须编外验证方；E043 只放开 condition_space 四槽）
+        units        复核通道体检/计划（hive → 提示配置 → 子代理 三级链）
+        catalog      引擎自描述（错误码/契约角色/动作清单）
+
+    入参集中在 `ccg` 对象里（与 `redteam`/`verify` 同风格）——避免与既有扁平参数
+    重名（如 `verdict` 在 verify 面是 confirmed|weakened|falsified，语义不同）。
+
+    返回语义：`ok` 表示**本次请求本身**是否成立；`verdict` 是单元给出的裁决
+    （未复核为 None）；`passed` = 裁决为 ACCEPT。三者分开，避免「派发成功」
+    被误读成「复核通过」。
+
+    权限：编译器属写路径 → 记录/设计者角色可用（见 tokens.ALL_OPS 的 ccg 条目）。
+    attest/link 的准入**不靠 admin 闸**，而靠签章机械闸（E040/E041/E042）——理由：
+    默认部署（未设 MDCG_CAN_ADMIN）下再加 admin 会让编译器对使用者不可见
+    （「权限到位但通路不可见」是既有教训），而裁定 A 的保证本就在机械闸里。
+    """
+    from . import ccgc
+    from . import units as _units
+
+    o = a.get("ccg") or {}
+    if not isinstance(o, dict):
+        return {"ok": False, "op": "ccg",
+                "error": "ccg 参数须为对象：{action, node_id, dialog, ...}"}
+    act = str(o.get("action") or a.get("action") or "compile").strip().lower()
+    node_id = str(o.get("node_id") or a.get("node_id") or "").strip()
+    actor = str(getattr(getattr(cg, "principal", None), "actor", "") or o.get("actor") or "agent")
+    jobs = str(o.get("jobs") or "")
+
+    if act == "catalog":
+        return {"ok": True, "op": "ccg", "action": "catalog",
+                "actions": ["compile", "review", "attest", "link", "recalibrate",
+                            "units", "catalog"],
+                "states": list(ccgc.STATES), "contract_roles": list(ccgc.CONTRACT_ROLES),
+                "errors": dict(ccgc.E_CODES),
+                "rule": "裁定 A：验证方标识不得等于编译执行者（E041）；缺签章不写库（E040）；"
+                        "未通过不写库（E042）"}
+
+    if act == "units":
+        if o.get("doctor"):
+            return {"ok": True, "op": "ccg", "action": "units", **_units.doctor(jobs)}
+        p = _units.plan(jobs=jobs, model=o.get("model") or "",
+                        allow_degrade=bool(o.get("allow_degrade")),
+                        channel=o.get("channel") or "")
+        return {"ok": True, "op": "ccg", "action": "units", **p}
+
+    if act == "compile":
+        dialog = str(o.get("dialog") or o.get("content") or a.get("content") or "")
+        if not dialog.strip():
+            return {"ok": False, "op": "ccg", "action": "compile",
+                    "error": "缺对话记录：传 ccg.dialog（或顶层 content）"}
+        if not node_id:
+            return {"ok": False, "op": "ccg", "action": "compile",
+                    "error": "缺 node_id：六要素候选须指明目标节点"}
+        res = ccgc.compile_dialog(dialog, node_id, actor,
+                                  marks=o.get("marks"), slots=o.get("slots"),
+                                  strict_spans=bool(o.get("strict_spans", True)), cg=cg)
+        saved = ccgc.save_pending(cg, res)
+        return {"ok": bool(res.success), "op": "ccg", "action": "compile",
+                "compiled": ccgc.asdict(res), "pending": saved,
+                "actor": actor, "compiled_by": actor,
+                "hint": ("候选已落 pending；下一步 cg(op=ccg, action=review, "
+                         "ccg={node_id, blocking:true}) 交编外单元复核"
+                         "——编译者不得自证（E041）" if res.success else
+                         "编译未通过：" + (res.errors[0] if res.errors else "未知错误"))}
+
+    if act == "review":
+        got = ccgc.load_pending(cg, node_id)
+        if not got.get("ok") or not got.get("hash_ok"):
+            return {"ok": False, "op": "ccg", "action": "review",
+                    "error": got.get("error") or "pending 产物与编译时不一致（hash 不符）",
+                    "hint": "先 cg(op=ccg, action=compile, ccg={node_id, dialog}) 生成候选"}
+        compiled = got["compiled"]
+        role = str(o.get("role") or _units.REFLECT).strip().lower()
+        prompt = _units.prompt_for(role, compiled, dialog=str(o.get("dialog") or ""))
+        r = _units.review(prompt=prompt, role=role, node_id=node_id, jobs=jobs,
+                          model=o.get("model") or "",
+                          timeout_s=int(o.get("timeout_s") or _units.DEFAULT_TIMEOUT_S),
+                          allow_degrade=bool(o.get("allow_degrade")),
+                          channel=o.get("channel") or "",
+                          wait_s=float(o.get("wait_s") or _units.DEFAULT_TIMEOUT_S),
+                          blocking=bool(o.get("blocking")), cg=cg, actor=actor,
+                          autostart=bool(o.get("autostart")))
+        unit = r.get("unit")
+        out = {"ok": True, "op": "ccg", "action": "review", "state": r["state"],
+               "role": role, "node_id": node_id, "job_id": r.get("job_id"),
+               "transport": r.get("transport"), "verdict": (unit or {}).get("verdict"),
+               "passed": bool((unit or {}).get("verdict") == ccgc.ACCEPT),
+               "unit": unit, "channel": r.get("channel") or "",
+               "blocking": bool(o.get("blocking")), "hint": r.get("hint") or ""}
+        if r["state"] != _units.HIVE:
+            out["ok"] = False
+            out["prompt"] = r.get("prompt")      # 降级/配置路径：把复核请求包交回调用方
+            return out
+        if unit:                                  # 已获编外裁决 → 自动签章
+            args = r.get("attest") or {}
+            at = ccgc.attest(node_id, args.get("verdict") or ccgc.DEFER,
+                             args.get("verifier") or "", compiled.actor or actor,
+                             slot_corrections=args.get("slot_corrections"),
+                             evidence=args.get("evidence") or "", cg=cg)
+            out["attest"] = ccgc.asdict(at)
+            out["pending"] = ccgc.save_pending(cg, compiled, at)
+            out["hint"] = ("已签章（%s）；下一步 cg(op=ccg, action=link, "
+                           "ccg={node_id, apply:true}) 落库"
+                           % (args.get("verifier") or "-") if at.ok else
+                           "签章未通过：" + (at.error or "DEFER/REJECT 不构成准入"))
+        return out
+
+    if act == "attest":
+        got = ccgc.load_pending(cg, node_id)
+        if not got.get("ok") or not got.get("hash_ok"):
+            return {"ok": False, "op": "ccg", "action": "attest",
+                    "error": got.get("error") or "pending 产物与编译时不一致（hash 不符）",
+                    "hint": "先 cg(op=ccg, action=compile, ...) 生成候选"}
+        compiled = got["compiled"]
+        at = ccgc.attest(node_id, str(o.get("verdict") or ""),
+                         str(o.get("verifier") or ""),
+                         str(o.get("compiled_by") or compiled.actor or actor),
+                         slot_corrections=o.get("slot_corrections"),
+                         evidence=str(o.get("evidence") or ""), cg=cg)
+        return {"ok": bool(at.ok), "op": "ccg", "action": "attest",
+                "attest": ccgc.asdict(at),
+                "pending": ccgc.save_pending(cg, compiled, at),
+                "hint": ("签章通过；下一步 cg(op=ccg, action=link, ccg={node_id, apply:true})"
+                         if at.ok else "签章未通过：" + (at.error or "DEFER/REJECT 不构成准入"))}
+
+    if act == "link":
+        apply = bool(o.get("apply"))
+        res = ccgc.link_pending(cg, node_id, apply=apply, actor=actor,
+                                basis=str(o.get("basis") or "ccgc link"))
+        return {"ok": bool(res.ok), "op": "ccg", "action": "link", "apply": apply,
+                "link": ccgc.asdict(res),
+                "hint": ("已落库（entry_id=%s，written=%s）" % (res.entry_id, res.written)
+                         if res.ok and apply else
+                         ("准入通过（dry_run 未写库）；apply=true 才落库" if res.ok else
+                          "；".join(res.errors or []) or "准入未通过"))}
+
+    if act == "recalibrate":
+        corr = o.get("slot_corrections") or o.get("corrections") or {}
+        verifier = str(o.get("verifier") or "").strip()
+        compiled_by = str(o.get("compiled_by") or "").strip()
+        if not verifier or verifier == compiled_by:
+            return {"ok": False, "op": "ccg", "action": "recalibrate",
+                    "error": "E041 自证拒绝：recalibrate 须由编外验证方给出"
+                             "（verifier 必填且 != compiled_by）"}
+        res = ccgc.recalibrate(node_id, corr, verifier, compiled_by,
+                               evidence=str(o.get("evidence") or ""), cg=cg,
+                               apply=bool(o.get("apply")))
+        return {"ok": bool(res.ok), "op": "ccg", "action": "recalibrate",
+                "recalibrate": ccgc.asdict(res),
+                "hint": ("；".join(res.errors or []) or "修正已应用（apply=true）" if res.ok
+                         else "；".join(res.errors or []) or "修正未通过")}
+
+    return {"ok": False, "op": "ccg", "action": act,
+            "error": "ccg 未知 action：%s（可选 compile|review|attest|link|recalibrate|"
+                     "units|catalog）" % act}
+
+
+# 生效条件：act=(a.get("action") or "recall").strip().lower()；act=="note" 时若 principal 非 None 且其 can_write 为假先 require_admin("session_note")，再调 cg.session_note(summary/text/content 之一或 ""，importance=float(0.6 if a.get("importance") is None else a.get("importance")) 等)；act=="recall" 时调 cg.session_recall(...)；act=="compact" 时若 a.get("note") 为真且 principal 非 None 且无写权先 require_admin("session_compact")，再调 cg.session_compact(...)；其余 act 抛 ValueError。
 def _session_call(cg, a):
     """会话三件套（P0）：note 写要点 / recall 续接 / compact 压摘要。
 
@@ -1939,6 +2531,7 @@ def _session_call(cg, a):
     raise ValueError(f"session 未知 action：{act}（允许 note/recall/compact）")
 
 
+# 生效条件：flag=a.get("prune", True)，flag 为字符串时重算为 flag.strip().lower() not in ("false","0","no","off","")；若 not flag 或 stats.get("truncated") 为真则返回 None；否则返回 refindex.prune_orphans(cg, kind=kind, root=root, items=items, dry_run=bool(a.get("prune_dry_run"))).
 def _prune_after_index(cg, a, *, kind, root, items, stats):
     """索引后的**节点级对账**：清退「同 root + 同 path 的过期代」。
 
@@ -1961,6 +2554,7 @@ def _prune_after_index(cg, a, *, kind, root, items, stats):
         dry_run=bool(a.get("prune_dry_run")))
 
 
+# 生效条件：sd=list(stats.get("skipped_dirs") or [])，返回 {"skipped_dirs": sd[:limit], "skipped_dirs_count": len(sd), "skip_dirs": list(stats.get("skip_dirs") or [])}，且仅当 len(sd)>limit 时追加 skipped_dirs_note。
 def _skip_dirs_report(stats, limit=20):
     """把「本次被 skip_dirs 排掉的目录」压成可审计字段。
 
@@ -1975,6 +2569,7 @@ def _skip_dirs_report(stats, limit=20):
     return out
 
 
+# 生效条件：act=(a.get("action") or "stat").strip().lower()；act 属 ("file","dir","jsonl") 且 principal 非 None 且其 can_write 为假时先 require_admin(f"ingest_{act}")，随后以 action=act 及各透传参数调 sources.run 并返回。
 def _ingest_call(cg, a):
     """文件摄取分派（P0）：file / dir / jsonl / stat。
 
@@ -1995,6 +2590,7 @@ def _ingest_call(cg, a):
         max_events=a.get("max_events"))
 
 
+# 生效条件：act=(a.get("action") or "stat").strip().lower()；principal 非 None 时一律先 require_admin(f"export_{act}")，随后以 include_content=True if a.get("include_content") is None else bool(a.get("include_content")) 等参数调 _ex.run 并返回。
 def _export_call(cg, a):
     """全库导出（P0）：graph / nodes / slice / stat。
 
@@ -2013,8 +2609,9 @@ def _export_call(cg, a):
         include_content=True if inc is None else bool(inc))
 
 
+# 生效条件：act=(a.get("action") or "stat").strip().lower()，apply=bool(a.get("apply"))，mode=str(a.get("mode") or "").strip().lower()；principal 非 None 时对 act=="rollback"、act in ("importance","separate") 且 apply、act=="longterm" 且 apply、act=="prefeed" 且 a.get("write") 真且无写权、act in ("backfill","cap","exempt") 且 apply、act in ("backfill_rollback","cap_rollback","exempt_rollback")、act=="vision_evidence" 且 apply、act=="vision_evidence_rollback"、act=="refine" 且 apply 分别 require_admin；随后 act=="longterm" 且 mode in ("list","ls","show","read") 时仅以 action/mode/limit/snapshot_id 调 cg.maintain，否则以全部参数调 cg.maintain。
 def _maintain_call(cg, a):
-    """记忆维护（P1）：importance / longterm / prefeed / separate / rollback / stat。
+    """记忆维护（P1）：importance / longterm / prefeed / separate / rollback / stat / propagate。
 
     权限**按 action 分档**（比整 op 收窄更贴合语义）：
       · 只读（stat / history / longterm mode=list|show）→ 不额外拦截；
@@ -2029,6 +2626,19 @@ def _maintain_call(cg, a):
     apply = bool(a.get("apply"))
     mode = str(a.get("mode") or "").strip().lower()
     actor = getattr(principal, "actor", None) if principal is not None else None
+    # P4 可验证记忆单元（2026-09-19）：**多跳**失效传播巡检（写路径只做一跳同步，
+    # 保写入延迟恒定——多跳的重算成本交给巡检面）。
+    #   · 预演（默认 apply=False）→ 只出可达集报表，放行写层角色先看影响面；
+    #   · apply=True → 直接改写下游验证态（同步写盘）→ 管理操作。
+    if act == "propagate":
+        from . import trust as _trust
+        if apply and principal is not None:
+            principal.require_admin("maintain_propagate")
+        rep = _trust.propagate(cg, apply=apply,
+                               max_nodes=int(a.get("max_nodes") or 500),
+                               actor=actor or "patrol")
+        rep.update({"op": "maintain", "action": "propagate"})
+        return rep
     if principal is not None and act == "rollback":
         principal.require_admin("maintain_rollback")
     if principal is not None and act in ("importance", "separate") and apply:
@@ -2077,6 +2687,7 @@ def _maintain_call(cg, a):
         verdicts=a.get("verdicts"), reason=a.get("reason"))
 
 
+# 生效条件：act=(a.get("action") or "promote").strip().lower()；principal 非 None 时一律先 require_admin(f"consolidate_{act}")；imp=a.get("min_importance")，为 None 时回落为 a.get("importance")，随后以 imp 等参数调 cg.consolidate_run 并返回。
 def _consolidate_call(cg, a):
     """离线固化（P1）：promote / promote_rollback / promote_history。
 
@@ -2101,15 +2712,20 @@ def _consolidate_call(cg, a):
         actor=getattr(principal, "actor", None) if principal is not None else None)
 
 
+# 生效条件：act=(a.get("action") or "outlook").strip().lower()，apply=bool(a.get("apply"))；principal 非 None 时 can_write=bool(principal.can_write)，对 act in ("record","verify") 且无写权、act in ("fork","branch_rewrite","branch_merge") 且无写权、act in ("reconstruct","learn") 且 apply、act=="branch_discard" 分别 require_admin；随后以 action=act 等参数调 cg.insight 并返回。
 def _insight_call(cg, a):
     """洞察（P2）：window / record / verify / list / report / reconstruct / learn /
-    outlook / catalog。
+    outlook / catalog / fork / branch_rewrite / branch_search / branch_merge /
+    branch_discard / branches / tickets。
 
     权限**按 action 分档**（与 maintain 同构，比整 op 收窄更贴合语义）：
-      · 只读（window / list / report / reconstruct 预演 / outlook / catalog）
-        → 不额外拦截；
-      · 条件层记账（record / verify）→ 需 can_write；
-      · 落库（reconstruct apply / learn apply）→ 批量改写，require_admin。
+      · 只读（window / list / report / reconstruct 预演 / outlook / catalog /
+        branch_search / branches / fork 预演 / tickets 预演）→ 不额外拦截；
+      · 条件层记账（record / verify）与分支写操作（fork / branch_rewrite /
+        branch_merge）→ 需 can_write；
+      · 落库（reconstruct apply / learn apply / tickets apply 批量建卡）与
+        分支弃置（branch_discard，改变库可见性）→ require_admin
+        （discard 库层还有第二道闸）。
     这样 output 角色能读洞察但不能记；reflect 能重构与学习预演；批量落库须请示。
     """
     act = (a.get("action") or "outlook").strip().lower()
@@ -2119,23 +2735,34 @@ def _insight_call(cg, a):
     actor = getattr(principal, "actor", None) if principal is not None else None
     if principal is not None and act in ("record", "verify") and not can_write:
         principal.require_admin(f"insight_{act}")     # 无写权 → 抛 AccessDenied
-    if principal is not None and act in ("reconstruct", "learn") and apply:
-        principal.require_admin(f"insight_{act}")
+    if principal is not None and act in ("fork", "branch_rewrite",
+                                         "branch_merge") and not can_write:
+        principal.require_admin(f"insight_{act}")     # 分支写 → 需写权
+    if principal is not None and act in ("reconstruct", "learn",
+                                         "tickets") and apply:
+        principal.require_admin(f"insight_{act}")     # 批量落库 → 需 admin
+    if principal is not None and act == "branch_discard":
+        principal.require_admin("branch_discard")     # 弃置：分发层+库层双闸
     return cg.insight(
         action=act, layer=a.get("layer"), limit=a.get("limit"),
         conditions=a.get("conditions"), apply=apply, actor=actor,
         statement=a.get("statement"), category=a.get("category"),
         source=a.get("source"), tags=a.get("tags"),
         importance=a.get("importance"), node_id=a.get("node_id"),
+        content=a.get("content"),
         evidence=a.get("evidence"), v_types=a.get("v_types"),
         verdict=a.get("verdict"), state=a.get("state"),
         window_days=a.get("window_days"), clues=a.get("clues"),
         ids=a.get("ids"), neighbors=a.get("neighbors"),
+        branch_id=a.get("branch_id"), note=a.get("note"),
+        reason=a.get("reason"),
         blindspot_id=a.get("blindspot_id"), horizon=a.get("horizon"),
         max_branches=a.get("max_branches"), recent_days=a.get("recent_days"),
-        sample_limit=a.get("sample_limit"), max_nodes=a.get("max_nodes"))
+        sample_limit=a.get("sample_limit"), max_nodes=a.get("max_nodes"),
+        types=a.get("types"), min_blindspot=a.get("min_blindspot"))
 
 
+# 生效条件：当 cg、a 传入时，按 a.get('action') or 'read'（空串/None 回退 'read'）分派：action=stat 返回 {'ok': True, 'action': 'stat', 'ledger': refindex.Ledger(cg.root).summary(), 'note': 'ref 索引水位（_refindex.json）：files/nodes 是已登记量；last_index.truncated=true 表示最近一次索引被截断。'}；action=check 返回 refindex.check_refs(cg, ledger=refindex.Ledger(cg.root), max_nodes=int(a.get('max_nodes') or refindex.MAX_CHECK)) 的结果并补 action='check' 与 note（max_nodes 假值回落 refindex.MAX_CHECK）；action 为 prune/prune_dangling 返回 refindex.prune_dangling(cg, only_roots=a.get('roots'), dry_run=bool(a.get('dry_run')), max_nodes=int(a.get('max_nodes') or refindex.MAX_CHECK)) 的结果并补 action='prune' 与 note（max_nodes 假值回落常量，dry_run 缺键为 False）；action 为 read/get 时 nid=(a.get('node_id') or '').strip()，若 nid 非空但 cg.get(nid) 为假返回 {'ok': False, 'error': '节点不存在：nid'}，ref 取 a.get('ref') 当且仅当它是 dict，否则若 node 非 None 用 refindex.ref_of(node)，若 ref 仍为假返回 {'ok': False, 'error': '该节点没有 code_ref/doc_ref（不是索引节点）'}，否则返回 refindex.read_ref(ref, root=a.get('root'), ref_kind=ref_kind) 的结果并设 out['node_id']=nid or None；其他 action 抛 ValueError；
 def _ref_call(cg, a):
     """按 ref 回读被索引的源位置（认知图只存注释/接口，正文在这里取回）。
 
@@ -2204,39 +2831,57 @@ def _ref_call(cg, a):
     return out
 
 
+# 生效条件：始终 import 白箱模块并返回 whitebox.dispatch(cg, a)。
 def _whitebox_call(cg, a):
     """显式调用白箱能力库（AEIS 降为本地库后的唯一入口）。
 
     显式调用映射：md_cg.whitebox.dispatch
-    见 docs/功能调用映射表_v0.1.md。
+    见 docs/mdcg/功能调用映射表_v0.1.md。
     """
     from . import whitebox
     return whitebox.dispatch(cg, a)
 
 
+# 生效条件：op=(a.get("op") or "").strip().lower()；op=="relation" 时返回 stg.relation(cg, a.get("a",""), a.get("b",""))；op=="timeline" 时返回 stg.timeline(cg, layer=a.get("layer"), limit=int(a.get("limit") or 50), desc=bool(a.get("desc", True)))；op=="anchors" 时返回 stg.anchors(cg, time_window=a.get("time_window"), bbox=a.get("bbox"), layer=a.get("layer"), limit=int(a.get("limit") or 50))；op=="consistency" 时返回 stg.consistency(cg, layer=a.get("layer"), limit=int(a.get("limit") or 50))；op 为空或其它的值抛 ValueError。
 def _stg_call(cg, a):
-    """语义时空图唯一入口。"""
+    """语义时空图唯一入口。
+
+    四个 op 均支持 `time_axis`：**缺省 `observed`**（与旧行为逐位一致；stg 的
+    时间语义历来是观察轴），`effective` 走效力轴端点比较。此处与 `cg(op=read)`
+    的透传策略**相反**——`cg` 侧缺省由库层定（不启用的时间算子），`stg` 侧轴
+    决定「排序/关系依据」必须**恒有值**，故在此填默认；非法轴仍由
+    `trust.time_axis_of` fail-closed 抛错（本层不预先白名单，避免两套枚举）。
+    """
     from . import stg
     op = (a.get("op") or "").strip().lower()
+    axis = a.get("time_axis") or "observed"
     if op == "relation":
-        return stg.relation(cg, a.get("a", ""), a.get("b", ""))
+        return stg.relation(cg, a.get("a", ""), a.get("b", ""), time_axis=axis)
     if op == "timeline":
         return stg.timeline(cg, layer=a.get("layer"),
                             limit=int(a.get("limit") or 50),
-                            desc=bool(a.get("desc", True)))
+                            desc=bool(a.get("desc", True)), time_axis=axis)
     if op == "anchors":
         return stg.anchors(cg, time_window=a.get("time_window"), bbox=a.get("bbox"),
-                           layer=a.get("layer"), limit=int(a.get("limit") or 50))
+                           layer=a.get("layer"), limit=int(a.get("limit") or 50),
+                           time_axis=axis)
     if op == "consistency":
         return stg.consistency(cg, layer=a.get("layer"),
-                               limit=int(a.get("limit") or 50))
-    raise ValueError(f"stg 未知 op：{op}")
+                               limit=int(a.get("limit") or 50), time_axis=axis)
+    if not op:
+        # fail-closed 且给出可操作提示：stg 的 op 四值签名区分度低于 cg（relation 需
+        # a+b、timeline/anchors/consistency 皆以 layer+limit 为主），**不做签名推导**
+        # ——猜错会静默返回错误视图，比报错更贵。
+        raise ValueError("stg 的 op 为必填参数（缺失即报错，不静默降级）；"
+                         "允许 op：relation | timeline | anchors | consistency")
+    raise ValueError(f"stg 未知 op：{op}（允许 relation | timeline | anchors | consistency）")
 
 
 # --------------------------------------------------------------------------
 # 工具实现
 # --------------------------------------------------------------------------
 
+# 生效条件：a=args or {}，unit=(a.get("as_unit") or "").strip()；unit 为空或 cg.principal 为 None 时直接返回 _dispatch(cg,name,a)；否则先 narrowed_principal(cg.principal, unit)，TokenError 时返回 {"ok":False,"error":f"as_unit 非法：{e}"}，成功则暂存 cg.principal、置为 narrowed、try 返回 _dispatch、finally 还原。
 def call_tool(cg, name, args):
     """MCP tools/call 入口：按 `as_unit` 做**请求级身份收窄**（单进程多身份）。
 
@@ -2269,6 +2914,7 @@ def call_tool(cg, name, args):
         cg.principal = saved
 
 
+# 生效条件：name 为已注册工具名之一（cg / stg / mdcg_whitebox / mdcg_service_info / mdcg_remember 等）；未识别的 name 返回含 error 的响应字典而不抛异常，进程不因此中断；
 def _dispatch(cg, name, args):
     a = args or {}
     if name == "cg":
@@ -2355,7 +3001,8 @@ def _dispatch(cg, name, args):
                          include_recent=bool(a.get("include_recent")),
                          recent_limit=int(a.get("recent_limit") or 10),
                          query_expand=_make_query_expand(a.get("expand")),
-                         session=a.get("session"))
+                         session=a.get("session"),
+                         validity=a.get("validity"))
 
     if name == "mdcg_search":
         from . import refindex
@@ -2364,14 +3011,16 @@ def _dispatch(cg, name, args):
                               roles=tuple(a["roles"]) if a.get("roles") else None,
                               include_work=bool(a.get("include_work")),
                               pools=a.get("pools"),
-                              session=a.get("session"))
+                              session=a.get("session"),
+                              validity=a.get("validity"))
         return {"meta": meta,
                 "results": [{"node": _node_view(n), "score": s, "state": q.get("state"),
                              "reason": q.get("reason"), **refindex.ref_fields(n)}
                             for n, s, q in res]}
 
     if name == "mdcg_get":
-        return _node_view(cg.get(a.get("node_id", "")))
+        return _node_view(cg.get(a.get("node_id", "")),
+                          offset=int(a.get("offset") or 0))
 
     if name == "mdcg_reflect":
         res, _ = cg.search(a.get("query", ""), k=int(a.get("k") or 10), record=False)
@@ -2396,10 +3045,18 @@ def _dispatch(cg, name, args):
                                         a.get("goal", ""))}
 
     if name == "mdcg_propose":
-        return {"pid": cg.propose(a.get("node_id", ""), a.get("content", ""),
-                                  layer=a.get("layer") or "knowledge",
-                                  tags=a.get("tags"), condition_space=a.get("condition_space"),
-                                  **_proposal_extras(a))}
+        pr = cg.propose(a.get("node_id", ""), a.get("content", ""), info=True,
+                        layer=a.get("layer") or "knowledge",
+                        tags=a.get("tags"), condition_space=a.get("condition_space"),
+                        **_proposal_extras(a))
+        out = {"pid": pr["pid"], "dedup": bool(pr.get("dedup"))}
+        if pr.get("dedup"):
+            out["dup_of"] = pr["pid"]
+            out["dup_status"] = pr.get("dup_status")
+            out["hint"] = ("同内容提案已存在（pid=%s，状态=%s），幂等返回既有提案、"
+                           "未重复入队，无需重试"
+                           % (pr["pid"], pr.get("dup_status") or "pending"))
+        return out
 
     if name == "mdcg_review_list":
         return {"pending": cg.review_list()}
@@ -2483,6 +3140,7 @@ def _dispatch(cg, name, args):
 # JSON-RPC / stdio 主循环
 # --------------------------------------------------------------------------
 
+# 生效条件：error 非 None 时 msg 含 "error"=error、否则含 "result"=result，随后向 sys.stdout 写 _j(msg)+"\n" 并 flush，无返回值。
 def _reply(rid, result=None, error=None):
     msg = {"jsonrpc": "2.0", "id": rid}
     if error is not None:
@@ -2493,6 +3151,7 @@ def _reply(rid, result=None, error=None):
     sys.stdout.flush()
 
 
+# 生效条件：os.environ.get("MDCG_SUSTAIN","1") 取值属 ("0","false","False") 时返回 None；否则以 name=os.environ.get("MDCG_SUSTAIN_NAME") or "md_cg"、各 interval=float(os.environ.get(...) or sustain.DEFAULT_*)（空串回落默认）、各 auto_* 取 os.environ.get 默认值且值属 ("0","false","False") 时为关，调 sustain.ensure_loop 后 lp.start() 并返回 lp。
 def _start_sustain(cg):
     """启动常驻自维持循环（MDCG_SUSTAIN=0 关闭；间隔可用环境变量调）。"""
     if os.environ.get("MDCG_SUSTAIN", "1") in ("0", "false", "False"):
@@ -2525,6 +3184,7 @@ def _start_sustain(cg):
     return lp
 
 
+# 生效条件：s=str(s or "").strip()；不以 "session-" 开头、或去前缀按 "-" 分组后长度不等于 [8,4,4,4,12]、或某组字符不都在 "0123456789abcdef" 时返回 False，三者皆过返回 True。
 def _is_dsh_session(s: str) -> bool:
     """DSH 会话 id 形态判定：session-<8>-<4>-<4>-<4>-<12>（uuid4）。"""
     s = str(s or "").strip()
@@ -2536,6 +3196,7 @@ def _is_dsh_session(s: str) -> bool:
     return all(all(c in "0123456789abcdef" for c in g) for g in groups)
 
 
+# 生效条件：s=str(raw or "").strip()；s 为空返回 "anonymous"；非 DSH 形态返回 s；DSH 形态时以 root=os.environ.get("MDCG_DSH_SESSIONS_ROOT") or ~/.dsh/sessions 遍历条目，存在 root/<name>/s 目录则返回 s，os.listdir 抛 OSError 时返回 s，否则返回 "anonymous"。
 def _normalize_session(raw):
     """会话 id 归一 + 轻校验（只影响归因，不影响写入）。
 
@@ -2563,6 +3224,7 @@ def _normalize_session(raw):
     return "anonymous"
 
 
+# 生效条件：环境变量 MDCG_SESSION（优先）或 DSH_SESSION_ID 去空白后非空时把 p.session 设为 _normalize_session(raw)，MDCG_HARNESS 去空白后非空时把 p.harness 设为该值，MDCG_UNIT 去空白后非空时把 p.unit 设为该值，三者均为空串或未设置时 p 的对应字段保持原值；
 def _apply_attribution(p):
     """归因维度注入（嵌套身份：(harness, session)），**不参与授权**。
 
@@ -2583,6 +3245,7 @@ def _apply_attribution(p):
         p.unit = unit
 
 
+# 生效条件：环境变量 MDCG_TOKEN 去空白后非空时经 verify_token(token, tenant=os.environ.get("MDCG_TENANT")) 构造——抛 TokenError 则返回 (None, f"令牌校验失败：{e}")，成功则返回 (_attach_theory(p), None)；否则 MDCG_LEGACY_ENV_AUTH 值为 "1"/"true"/"True" 时按 MDCG_CAN_ADMIN/MDCG_CAN_WRITE 落到 designer/recorder/output 角色的 legacy_env 身份，两者都不满足时构造 can_write=False、can_admin=False、auth_mode="anonymous" 的 guest 身份，后两条路径同样返回 (_attach_theory(p), None)；
 def _build_principal():
     """构造 Principal（令牌优先，fail-closed）。返回 (principal, error)。
 
@@ -2633,6 +3296,7 @@ def _build_principal():
     return _attach_theory(p), None
 
 
+# 生效条件：p 传入后调用 theory.ensure() 得到 st，把 p.theory_ok 置为 bool(st.get("theory_ok"))（缺键或假值均为 False，而非保留原值或 None），p.theory_version 置为 st.get("version")（缺键为 None），返回 p，且校验过程不抛异常；
 def _attach_theory(p):
     """附加版本层状态（theory_ok / theory_version）。校验永不抛异常。
 
@@ -2645,6 +3309,7 @@ def _attach_theory(p):
     return p
 
 
+# 生效条件：环境变量 MDCG_ROOT 非空且其 os.path.abspath 规范化后的 basename 小写不以 "_md_cg_" 开头、且 _build_principal() 返回的 err 为空时，构造 MdCGSecure(root, principal=principal, autoflush=1) 并对 sys.stdin 逐行 method 分派（initialize 回 protocolVersion=PROTOCOL_VERSION 与 SERVER_NAME/SERVER_VERSION，tools/list 回 tools_for_surface()，tools/call 经 call_tool 后回 content，shutdown 跳出循环），遍历结束后调用 sustain.stop_all() 与 cg.close() 并返回 0；MDCG_ROOT 为空或 basename 命中 "_md_cg_" 前缀返回 2，令牌校验失败返回 3；
 def main():
     root = os.environ.get("MDCG_ROOT")
     if not root:
@@ -2664,6 +3329,24 @@ def main():
             "[mdcg-mcp] 请指向主认知图目录（如仓库内 md_cg/）。\n")
         return 2
     from .mdcos import MdCGSecure
+    # 数据面迁出插件包（issue #18 相邻问题）：旧版把运行时数据与路径配置写在包内
+    # `<pkg>/data`，pnpm 更新会连目录一起替换（实机实证 data/ 54 文件 → 0）。首启把
+    # 「旧位置仍有货」的数据**复制**到用户级数据根——node 侧插件启动时已做过一次，
+    # 这里是 python 独立使用（不经插件）时的同口径兜底。fail-safe：迁移只是增益，
+    # 任何失败都不阻塞启动，但不静默（走 stderr）。
+    try:
+        from .datapath import migrate_legacy_data as _migrate_legacy
+        _mig = _migrate_legacy()
+        if _mig.get("ran"):
+            sys.stderr.write(
+                "[mdcg-mcp] 数据面已迁出插件包（旧位置只复制未删除）：%s → %s"
+                "（%d 项）\n" % (_mig["from"], _mig["to"], _mig["copied"]))
+        elif _mig.get("failed"):
+            sys.stderr.write("[mdcg-mcp] 数据面迁移部分失败（不阻塞启动）：%s\n"
+                             % (_mig["failed"],))
+    except Exception as _mig_exc:       # 迁移故障不得影响服务可用性
+        sys.stderr.write("[mdcg-mcp] 数据面迁移检查失败（不阻塞启动）: %r\n"
+                         % (_mig_exc,))
     principal, err = _build_principal()
     if err:
         sys.stderr.write(
@@ -2678,7 +3361,14 @@ def main():
     _p_session = os.environ.get("MDCG_SESSION", "").strip()
     if _p_session:
         principal.session = _p_session
-    cg = MdCGSecure(root, principal=principal)
+    # 索引可见性（2026-09-16）：autoflush=1 —— 逐条写入立即落分片日志
+    # `_index_log/`。根因（第4条取证）：默认 autoflush=64 且常驻进程不 close，
+    # 单条写入在达阈值前**对其他进程不可见**（`_load_index` = 快照 + 分片日志
+    # 重放；`_index.json` 只在 compact/rebuild 时重写），表现为「写入返回
+    # committed=true 但第16条读回确认在跨进程读面上不可检索」。本参数是
+    # server 级兜底：覆盖不经 writepipe 写链的路径（propose / remember_gated /
+    # add_rejected 等）；写链另有显式提交边界（writepipe._commit_visibility）。
+    cg = MdCGSecure(root, principal=principal, autoflush=1)
     # 外部验证器注入（**能力外置**）：识图/实测/验收等能力不在认知图内，
     # 由 MDCG_VERIFIER_MODULES（逗号分隔 import 路径）声明的外部模块注入，
     # 通常位于私有运行时仓。加载失败不阻塞启动——失败原因写进 stderr 与
@@ -2688,6 +3378,42 @@ def main():
     if _verifiers.get("loaded") or _verifiers.get("failed"):
         sys.stderr.write("[mdcg-mcp] 外部验证器: loaded=%s failed=%s\n"
                          % (_verifiers.get("loaded"), _verifiers.get("failed")))
+    # ③ 两段式对账：上个进程若被杀在「落盘前后」之间，账本里会留下「有意图
+    # 无结果」的写入——启动即清账（内容确已落盘 → 补账 committed；没落上 →
+    # 如实标记 interrupted）。失败**不阻塞启动**：对账是增益，不是服务前提，
+    # 但必须上报（stderr），不静默。
+    try:
+        _rep = cg.reconcile_writes()
+        if _rep.get("unpaired"):
+            sys.stderr.write("[mdcg-mcp] 写入两段式对账: 未结清=%s 补账=%s "
+                             "中断=%s\n" % (_rep.get("unpaired"),
+                                            _rep.get("committed"),
+                                            _rep.get("interrupted")))
+    except Exception as _exc:         # 对账故障不得影响服务可用性
+        sys.stderr.write("[mdcg-mcp] 两段式对账失败（不阻塞启动）: %r\n"
+                         % (_exc,))
+    # 进程自报（诊断设施，fail-safe）：把「md_cg 实际加载源 + render 契约代际」
+    # 落成 `<tempdir>/md_cg_servers/<pid>.json`，供 `scripts/mdcg_stale_servers.py`
+    # 机械判定**活进程代际**。根因（第4条取证）：原先只能比「进程启动时间 vs
+    # md_cg/*.py 最新 mtime」，该判据有活体盲区——npm 副本进程启动于 11:37~11:39
+    # 而源码 mtime 为 09:24，故 stale=False，却持插件包 0.4.8 的旧契约
+    # `codeindex.render`，把全量重建成果刷回 old_synth（AGENTS.md §5 运维注记）。
+    # 自报给的是**绝对事实**（进程自己报出实际加载源），不再依赖相对量推断。
+    # 失败不阻塞启动：自报是增益，不是服务前提，但必须上报（stderr），不静默。
+    try:
+        from . import selfreport
+        _sr = selfreport.report(tag="mcp_server")
+        if _sr:
+            sys.stderr.write(
+                "[mdcg-mcp] 自报: source=%s render_version=%s\n"
+                "[mdcg-mcp] 自报文件: %s\n"
+                % (_sr.get("source_dir"), _sr.get("render_version"),
+                   _sr.get("self_report_path")))
+        else:
+            sys.stderr.write("[mdcg-mcp] 自报写入失败（不阻塞启动；"
+                             "该进程的代际将无法被外部机械判定）\n")
+    except Exception as _exc:             # noqa: BLE001 —— 自报不得阻塞启动
+        sys.stderr.write("[mdcg-mcp] 自报异常（不阻塞启动）: %r\n" % (_exc,))
     _start_sustain(cg)
 
     for line in sys.stdin: