@furongjun1999/dsh-memory 0.6.1 → 0.7.1

package/md_cg/mcp_server.py

@@ -180,7 +180,9 @@ TOOLS = [
                        "「跳过超大、继续试更小的」在预算紧张时淘汰最有价值的详实条目。"
                        "会话开始或重要工作前调用。可选启用第 5 路模糊召回（分级隶属度）"
                        "与第 6 路条件语义路（条件结构驱动），并注入调用方 LLM 的查询"
-                       "扩展词（索引侧始终白箱）。",
+                       "扩展词（索引侧始终白箱）。缺省另含第 7 路因果路（沿 edges 多跳）"
+                       "与第 8 路时间路（时间邻近度）——按裁定「全进默认检索」缺省开，"
+                       "可用 causal=false / temporal=false 单独关。",
         "inputSchema": _s("", query=_p("string", "描述当前任务的查询", True),
                           budget_tokens=_p("integer", "token 预算（默认 1200）"),
                           max_item_tokens=_p("integer", "单条上限（默认 250）；超限条目截断纳入。"
@@ -203,12 +205,22 @@ TOOLS = [
                           goal=_p("string", "当前目标（第 5 篇第 3 章）：启用 goal 路给召回定向；"
                                             "省略则自动取活跃目标"),
                           goal_path=_p("boolean", "启用目标定向路（默认否；给 goal 即自动启用）"),
+                          causal=_p("boolean", "因果路（P3，设计稿 §6.2）：以词法/实体命中"
+                                               "为种子沿 edges 多跳扩散，**缺省开**（全进默认"
+                                               "检索）；传 false 单独关本路。无 edges 的库上"
+                                               "自然为空"),
+                          temporal=_p("boolean", "时间路（P3，设计稿 §6.3）：按时间邻近度"
+                                                "排序的排名项，核走 time_core.cred_factor；"
+                                                "**缺省开**；传 false 单独关本路。无时间算子/"
+                                                "区间时恒空"),
                           include_recent=_p("boolean", "是否附「近期事件」窗口（默认否）"),
                           recent_limit=_p("integer", "近期事件条数（默认 10）"),
                           fusion=_p("string", "融合模式：sum（经典 RRF，奖励多路共识）"
                                               "| max（取各路最高贡献，不奖励共识）。"
                                               "fuzzy=true 时缺省 max——实测 sum 会低估"
-                                              "「只有模糊路捞到」的目标，self@1 −10.1%")),
+                                              "「只有模糊路捞到」的目标，self@1 −10.1%；"
+                                              "因果路（causal，缺省开）同为单路独有召回型，"
+                                              "故一并缺省 max")),
     },
     {
         "name": "mdcg_search",
@@ -1567,6 +1579,7 @@ def _sustain_call(cg, a):
     路线图「常驻服务：会话/心跳/自愈」。原则：诊断只读；自愈只碰派生物
     （索引/临时文件/日志边界），永不删节点；缺密钥属于权限事实，只报告不修。
     """
+    from . import sleep as _sleep
     from . import sustain
     act = (a.get("action") or "status").strip().lower()
     name = a.get("name") or os.environ.get("MDCG_SUSTAIN_NAME") or "md_cg"
@@ -1627,16 +1640,27 @@ def _sustain_call(cg, a):
                                 or sustain.DEFAULT_BEAT_INTERVAL),
             heal_interval=float(a.get("heal_interval")
                                 or sustain.DEFAULT_HEAL_INTERVAL),
-            auto_heal=bool(a.get("auto_heal", True)),
+            # 四档 auto_* 一律经 sustain 的**单一真源读取器**（P0-2）——此处
+            # 不得再写缺省字面量：op 路径原 `auto_tidy` 缺省 False 与 env 路径
+            # 的 True 相反，同 (root,name) 走两条入口语义不一致。显式入参仍优先。
+            auto_heal=sustain.auto_from_args("auto_heal", a),
             scrub_interval=float(a.get("scrub_interval")
                                  or sustain.DEFAULT_SCRUB_INTERVAL),
-            auto_scrub=bool(a.get("auto_scrub", False)),
+            auto_scrub=sustain.auto_from_args("auto_scrub", a),
             evolve_interval=float(a.get("evolve_interval")
                                   or sustain.DEFAULT_EVOLVE_INTERVAL),
-            auto_evolve=bool(a.get("auto_evolve", False)),
+            auto_evolve=sustain.auto_from_args("auto_evolve", a),
             tidy_interval=float(a.get("tidy_interval")
                                 or sustain.DEFAULT_TIDY_INTERVAL),
-            auto_tidy=bool(a.get("auto_tidy", False)))
+            auto_tidy=sustain.auto_from_args("auto_tidy", a),
+            # 第六档睡眠周期（§4.7）：五个值一律经 `md_cg/sleep.py` 的**单一真源
+            # 读取器**（此处不得再写缺省字面量，也不得再写 env 键名字面量——
+            # 键名真源是 `sleep.SLEEP_ENV_KEYS`）。与 env 路径逐字同一组调用。
+            sleep_interval=_sleep.sleep_interval(),
+            auto_sleep=_sleep.sleep_enabled(),
+            sleep_merge=_sleep.sleep_merge_mode(),
+            sleep_window=_sleep.sleep_window(),
+            sleep_scrub_apply=_sleep.sleep_scrub_apply())
         return {"loop": lp.start().status()}
     if act in ("stop", "down"):
         lp = sustain.get_loop(cg, name)
@@ -2047,7 +2071,7 @@ def _task_call(cg, a):
     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；
+# 生效条件：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；fork：op=="forget" 的**删除**分支走 cg.forget_gated（三档自治批次②：档位判定在既有资格闸之后，变更确认档出变更单且不软删；restore 分支不变），op=="write" 经 writepipe 默认链（链尾 autonomy 档位闸）；
 def _cg_dispatch(cg, a):
     """认知图唯一入口的 op 分发主体。"""
     op = (a.get("op") or "read").strip().lower()
@@ -2220,6 +2244,21 @@ def _cg_dispatch(cg, a):
             h["write_policy"] = audit.unavailable_report(_pe)
         h["theory"] = _th.check()
         h["links"] = _lk.ls()
+        # 代校验（纯增量，2026-09-30）：长驻进程可被问「你现在这一代是不是盘面那一代」。
+        # 根因（第4条取证）：升级后长驻进程仍持有启动代模块，与升级后惰性导入的新代
+        # 模块跨代混用（实测 cg 写入 ImportError: cannot import name 'mint_auto_id'
+        # from 'md_cg.mdcg'，而盘面正常）——盘面无从自证，须由进程自报。
+        # 落点＝generation.report()（单点）：code_generation / disk_generation /
+        # stale_on_disk / restart_required / hint。**纯增量**：既有键名、键值、
+        # 嵌套结构一字不动（本行只追加五个新键，键名与既有键无冲突）。
+        # 失败不得把 op=info 拖崩（同为诊断面契约）：异常在此收口成不可用形状。
+        from . import generation as _gen
+        try:
+            h.update(_gen.report())
+        except Exception as _ge:            # noqa: BLE001
+            h.update({"code_generation": None, "disk_generation": None,
+                      "stale_on_disk": None, "restart_required": None,
+                      "hint": "代校验不可用：%s: %s" % (type(_ge).__name__, _ge)})
         return h
 
     if op == "route":
@@ -2369,8 +2408,11 @@ def _cg_dispatch(cg, a):
     if op == "forget":
         if (a.get("action") or "forget").strip().lower() == "restore":
             return cg.restore(a.get("node_id", ""), force=bool(a.get("force")))
-        return cg.forget(a.get("node_id", ""), a.get("reason", ""),
-                         override=bool(a.get("override")))
+        # 三档自治批次②（设计 §三 D 删除）：工具面经 forget_gated——档位判定在
+        # 既有资格闸（not_found / protect.guard_forget）**之后**，变更确认档
+        # 出变更单且不软删；库层 forget 语义不变（脚本通道不接，本批边界）。
+        return cg.forget_gated(a.get("node_id", ""), a.get("reason", ""),
+                               override=bool(a.get("override")))
 
     if op == "protect":
         return _protect_call(cg, a)
@@ -3085,7 +3127,7 @@ def _whitebox_call(cg, a):
     return whitebox.dispatch(cg, a)
 
 
-# 生效条件：op=(a.get("op") or "").strip().lower()；op=="relation" 时返回 stg.relation(cg, a.get("a",""), a.get("b",""), time_axis=axis)；op=="timeline" 时返回 stg.timeline(cg, layer=a.get("layer"), limit=int(a.get("limit") or 50), desc=bool(a.get("desc", True)), time_axis=axis, session=a.get("session"))（session 缺省不过滤读遍所有会话，"*" = 显式跨会话，其它值 = 本会话视图）；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。
+# 生效条件：op=(a.get("op") or "").strip().lower()；op=="relation" 时返回 stg.relation(cg, a.get("a",""), a.get("b",""), time_axis=axis)；op=="timeline" 时返回 stg.timeline(cg, layer=a.get("layer"), limit=int(a.get("limit") or 50), desc=bool(a.get("desc", True)), time_axis=axis, session=a.get("session"))（session 缺省不过滤读遍所有会话，"*" = 显式跨会话，其它值 = 本会话视图）；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；返回体**原样透传**——stg 三接口的 truncated/scanned/kept/hint 读数与修正后的 count 语义（条件命中总数，issue #52）不经本层裁剪或改写，max_scan 本批不开显式入参。
 def _stg_call(cg, a):
     """语义时空图唯一入口。
 
@@ -3094,6 +3136,13 @@ def _stg_call(cg, a):
     的透传策略**相反**——`cg` 侧缺省由库层定（不启用的时间算子），`stg` 侧轴
     决定「排序/关系依据」必须**恒有值**，故在此填默认；非法轴仍由
     `trust.time_axis_of` fail-closed 抛错（本层不预先白名单，避免两套枚举）。
+
+    返回体**原样透传**（issue #52）：timeline/anchors/consistency 新增的
+    `truncated` / `scanned` / `kept` 读数与截断时的 `hint` 随返回值自动带出，
+    本层不裁剪、不改写；`count` 语义已是**条件命中总数**（不再受索引切片影响，
+    在役对照 `timeline(session=…)` 由 25 恢复为 229）。`max_scan` 本批不在
+    MCP 面开显式入参（契约：数值不是修法——需要收窄时细化生效条件/
+    不适用条件，或按设计稿建立条件索引）。
     """
     from . import stg
     op = (a.get("op") or "").strip().lower()
@@ -3229,7 +3278,26 @@ _MDCG_OP_REQUIRE = {
 }
 
 
-# 生效条件：name 为已注册工具名之一（cg / stg / mdcg_whitebox / mdcg_service_info / mdcg_remember 等）；name 属 _MDCG_OP_REQUIRE 且 cg.principal 具 require_op 属性时先 require_op（越权抛 AccessDenied），principal 为 None 或无该方法时跳过；cg 走 _cg_call、stg 走 _stg_call、whitebox 走 _whitebox_call；未识别的 name 返回含 error 的响应字典而不抛异常，进程不因此中断；
+# 生效条件：四个布尔入参任意组合下无条件返回 "max"（当 use_fuzzy 或 use_semantic 或 use_goal 或 use_causal 任一为真）或 None（全为假）；use_temporal 不参与判据；不做 IO、不看环境变量；
+def recall_fusion_default(use_fuzzy, use_semantic, use_goal, use_causal,
+                          use_temporal=False):
+    """`mdcg_recall` 的**缺省融合口径**判据（唯一单点，供守卫断言）。
+
+    P3-遗留 A（2026-10-01 补披露）：`use_causal` **缺省 True** ⇒ 默认 recall 的
+    融合口径由 `sum` 变成 **`max`**（影响**所有**默认召回调用，与库是否有边无关）。
+    该口径符合设计稿 §6.2「因果路融合缺省 max」与既有先例表达式
+    （fuzzy/semantic/goal 同款），故**保留**；本函数只把那个表达式从调用点提为
+    **可断言的名字**——否则「缺省到底是 sum 还是 max」只能靠读表达式，
+    静默漂移（少写一个 `or use_causal`）无守卫可抓。
+
+    `use_temporal` **刻意不入判据**：时间路是**排名项**（§6.3(e)：与 S4 层级
+    激活同类，不是单路独有召回型），它开着也不改变融合口径。
+    """
+    return ("max" if (use_fuzzy or use_semantic or use_goal or use_causal)
+            else None)
+
+
+# 生效条件：name 为已注册工具名之一（cg / stg / mdcg_whitebox / mdcg_service_info / mdcg_remember 等）；name 属 _MDCG_OP_REQUIRE 且 cg.principal 具 require_op 属性时先 require_op（越权抛 AccessDenied），principal 为 None 或无该方法时跳过；cg 走 _cg_call、stg 走 _stg_call、whitebox 走 _whitebox_call；未识别的 name 返回含 error 的响应字典而不抛异常，进程不因此中断；mdcg_forget 走 cg.forget_gated（同 cg(op=forget) 的档位路径）、mdcg_remember 的非 gated 直写分支在同 id 覆写时先过 cg.write_qualify 再按档位判定（三档自治批次②）；
 def _dispatch(cg, name, args):
     a = args or {}
     # P1-1：mdcg_* 面的角色作用域闸（与 cg 工具的 require_op 同一语义——
@@ -3296,6 +3364,51 @@ def _dispatch(cg, name, args):
         _prior_cov = (_forgetting.self_coverage(cg, _prior, _content)
                       if _prior is not None else None)
         _dup = _forgetting.redundancy(cg, _content, layer=_layer, exclude=nid)
+        # 三档自治批次②（设计 §三）：本分支是**热写入路径的第二落点**（另两处 =
+        # writepipe 链尾执行器、remember_gated）——同 id 已存在 ⇒ C 改写、
+        # 不存在 ⇒ A 新增，判据复用 forgetting.prior_node（不另写一份存在性判据）。
+        # 位置：既有 `if a.get("gated")` 分支之后、`cg.add` 之前（直写面没有别的
+        # 资格闸；audit/限流属 gated 分支的链）。确认档 ⇒ 出单且不落盘。
+        from . import autonomy_modes as _am
+        _action = _am.C_REWRITE if _prior is not None else _am.A_ADD
+        if _prior is not None:
+            # 资格在先（纯加严）：见 writepipe._gate_autonomy 同款注释——覆写的
+            # 层闸/写保护闸在 cg.add 内部，档位闸不得抢在它们之前把拒绝变成入队。
+            cg.write_qualify(nid, target_layer=_layer,
+                             override=bool(a.get("override")),
+                             actor=getattr(cg, "actor", None))
+        _dec = _am.decide(_action)
+        if _dec["decision"] != _am.ALLOW:
+            _aut = {"mode": _dec["mode"], "action": _dec["action"],
+                    "action_name": _dec["action_name"],
+                    "decision": _dec["decision"]}
+            if _dec["decision"] == _am.FORBID:
+                return {"ok": False, "id": nid, "committed": False,
+                        "moved_to": "autonomy_forbidden",
+                        "error": "autonomy_forbid", "autonomy": _aut,
+                        "hint": _dec["hint"]}
+            _meta = {k: a[k] for k in
+                     ("tags", "condition_space", "verification_basis",
+                      "non_applicable_conditions", "derived_from", "relation",
+                      "role", "importance") if a.get(k) is not None}
+            # 直写面的裁决参数（本分支的 add 会自己跑冲突闸）：随单落进复现 meta，
+            # 否则「确认后落盘」与「直接落盘」两条路径的判据不等价。
+            _meta["consistency"] = bool(a.get("consistency", True))
+            _meta["on_conflict"] = a.get("on_conflict") or "reject"
+            _meta["override"] = bool(a.get("override"))
+            _pay = _am.mutation_payload(
+                _action, nid, after=_content,
+                reason="mdcg_remember 直写（%s）" % _am.ACTION_NAMES[_action],
+                primitive="add", meta=_meta)
+            _pr = _am.propose_mutation(cg, _action, nid, payload=_pay,
+                                       layer=_layer,
+                                       sensitivity=a.get("sensitivity"),
+                                       info=True)
+            return {"ok": True, "id": nid, "committed": False,
+                    "moved_to": "review_queue", "pid": _pr["pid"],
+                    "mutation": _pay, "autonomy": _aut,
+                    "hint": "%s 本次未落盘：变更单已入审核队列（pid=%s，目标 %s）。"
+                            % (_dec["hint"], _pr["pid"], nid)}
         written = cg.add(nid, _content, layer=_layer,
                          # B2：同上——落盘面丢字段＝上游声明静默失效。
                          sensitivity=a.get("sensitivity"),
@@ -3332,7 +3445,16 @@ def _dispatch(cg, name, args):
         use_fuzzy = bool(a.get("fuzzy"))
         use_semantic = bool(a.get("semantic"))
         use_goal = bool(a.get("goal_path") or a.get("goal"))
-        if use_fuzzy or use_semantic or use_goal:
+        # P3（裁定 9「全进默认检索」）：因果路（chain）/ 时间路（temporal）**进缺省集**，
+        # 但**每路可单独关**——显式传 causal=false / temporal=false 即从本次调用剔除。
+        # 未显式传（None）= 缺省进路；与既有 fuzzy/semantic/goal 的「显式启用」语义相反，
+        # 这是刻意的非对称：这两路在无 edges / 无时间参数的库上自然为空，缺省开不产噪声。
+        use_causal = a.get("causal")
+        use_temporal = a.get("temporal")
+        use_causal = True if use_causal is None else bool(use_causal)
+        use_temporal = True if use_temporal is None else bool(use_temporal)
+        if (use_fuzzy or use_semantic or use_goal
+                or not use_causal or not use_temporal):
             paths = ["lexical", "bucket", "entity", "graph"]
             if use_fuzzy:
                 paths.append("fuzzy")
@@ -3340,13 +3462,22 @@ def _dispatch(cg, name, args):
                 paths.append("semantic")
             if use_goal:
                 paths.append("goal")
+            if use_causal:
+                paths.append("chain")
+            if use_temporal:
+                paths.append("temporal")
             paths = tuple(paths)
         else:
-            paths = None
+            paths = None          # 缺省六路（mdcos.search_rrf 的缺省集）
         # fuzzy 路缺省用 max 融合：实测（memory-bench-1000，870 查询）sum 会把
         # self@1 拉低 10.1%，因为求和奖励「多路共识」、低估「模糊路独有」的目标。
         # semantic 路同理：条件结构命中常是「独有召回」，故一并缺省 max。
-        fusion = a.get("fusion") or ("max" if (use_fuzzy or use_semantic or use_goal) else None)
+        # P3：因果路按设计稿 §6.2「融合口径」同为**单路独有召回型**，照抄本条先例
+        # 形态（同一表达式内追加条件，不另起第二套判据）。
+        # P3-遗留 A（2026-10-01）：表达式提为 `recall_fusion_default` 单点，
+        # 使「缺省口径 = max」可被守卫直接断言（防静默漂移）。
+        fusion = a.get("fusion") or recall_fusion_default(
+            use_fuzzy, use_semantic, use_goal, use_causal)
         # 默认单条上限从 mdcos 取（该模块只在 main() 里惰性导入，模块级没有名字，
         # 直接引用 mdcos.DEFAULT_MAX_ITEM_TOKENS 会 NameError —— 故此处按需导入）。
         from .mdcos import DEFAULT_MAX_ITEM_TOKENS as _DEFAULT_MAX_ITEM
@@ -3448,8 +3579,9 @@ def _dispatch(cg, name, args):
         return {"records": cg.review_records(pid=a.get("pid"))}
 
     if name == "mdcg_forget":
-        return cg.forget(a.get("node_id", ""), a.get("reason", ""),
-                         override=bool(a.get("override")))
+        # 三档自治批次②：与 cg(op=forget) 同一档位路径（forget_gated，见该分支注释）。
+        return cg.forget_gated(a.get("node_id", ""), a.get("reason", ""),
+                               override=bool(a.get("override")))
 
     if name == "mdcg_restore":
         return cg.restore(a.get("node_id", ""), force=bool(a.get("force")))
@@ -3555,6 +3687,7 @@ def _start_sustain(cg):
     """启动常驻自维持循环（MDCG_SUSTAIN=0 关闭；间隔可用环境变量调）。"""
     if os.environ.get("MDCG_SUSTAIN", "1") in ("0", "false", "False"):
         return None
+    from . import sleep as _sleep
     from . import sustain
     name = os.environ.get("MDCG_SUSTAIN_NAME") or "md_cg"
     lp = sustain.ensure_loop(
@@ -3563,22 +3696,28 @@ def _start_sustain(cg):
                             or sustain.DEFAULT_BEAT_INTERVAL),
         heal_interval=float(os.environ.get("MDCG_SUSTAIN_HEAL")
                             or sustain.DEFAULT_HEAL_INTERVAL),
-        auto_heal=os.environ.get("MDCG_SUSTAIN_AUTOHEAL", "1")
-        not in ("0", "false", "False"),
+        # 四档 auto_* 一律经 sustain 的**单一真源读取器**（P0-2）：缺省值只在
+        # `sustain.AUTO_DEFAULTS` 定义一处，此处不得再写字面量（含 env 键名——
+        # 键名真源是 `sustain.AUTO_ENVS`）。整理巡检缺省开：确定性动作、
+        # 永不删除节点（可逆可审计）；opt-out `MDCG_AUTO_TIDY=0`。
+        auto_heal=sustain.auto_from_env("auto_heal"),
         scrub_interval=float(os.environ.get("MDCG_SCRUB_INTERVAL")
                              or sustain.DEFAULT_SCRUB_INTERVAL),
-        auto_scrub=os.environ.get("MDCG_AUTO_SCRUB", "0")
-        not in ("0", "false", "False"),
+        auto_scrub=sustain.auto_from_env("auto_scrub"),
         evolve_interval=float(os.environ.get("MDCG_EVOLVE_INTERVAL")
                               or sustain.DEFAULT_EVOLVE_INTERVAL),
-        auto_evolve=os.environ.get("MDCG_AUTO_EVOLVE", "0")
-        not in ("0", "false", "False"),
+        auto_evolve=sustain.auto_from_env("auto_evolve"),
         tidy_interval=float(os.environ.get("MDCG_TIDY_INTERVAL")
                             or sustain.DEFAULT_TIDY_INTERVAL),
-        # 整理巡检（contextual 同构组聚合+成员降权）默认开：确定性动作、
-        # 永不删除节点（可逆可审计）；MDCG_AUTO_TIDY=0 关闭
-        auto_tidy=os.environ.get("MDCG_AUTO_TIDY", "1")
-        not in ("0", "false", "False"))
+        auto_tidy=sustain.auto_from_env("auto_tidy"),
+        # 第六档睡眠周期（§4.7）：五个值一律经 `md_cg/sleep.py` 的**单一真源
+        # 读取器**——键名真源是 `sleep.SLEEP_ENV_KEYS`、缺省真源是
+        # `sleep.SLEEP_ENV_DEFAULTS`，本处（与 op 路径）都不得再写字面量。
+        sleep_interval=_sleep.sleep_interval(),
+        auto_sleep=_sleep.sleep_enabled(),
+        sleep_merge=_sleep.sleep_merge_mode(),
+        sleep_window=_sleep.sleep_window(),
+        sleep_scrub_apply=_sleep.sleep_scrub_apply())
     lp.start()
     return lp
 
@@ -4109,6 +4248,32 @@ def main():
                              "该进程的代际将无法被外部机械判定）\n")
     except Exception as _exc:             # noqa: BLE001 —— 自报不得阻塞启动
         sys.stderr.write("[mdcg-mcp] 自报异常（不阻塞启动）: %r\n" % (_exc,))
+    # 代校验（generation 单点，2026-09-30）：stdio 服务**真正开始服务之前**，把盘面
+    # 上所有「函数内延迟导入」在本进程的模块面上试解析一遍（导入目标模块 → getattr
+    # 取名字）。根因（第4条取证）：长驻进程只在模块首次导入时读盘，而 md_cg 内有
+    # 大量写在函数里的延迟导入（AST 实测 328 处，相当一部分是为避开循环导入）——
+    # 升级后旧代已载入模块与新代惰性模块跨代混用，实测表现为 cg 写入返回
+    # `ImportError: cannot import name 'mint_auto_id' from 'md_cg.mdcg'` 而盘面完全
+    # 正常（该延迟导入要到运行期才炸，且报错点离根因很远）。此处提前到启动期显式
+    # 判一次：**名字缺失即拒绝启动**（fail-closed，消息自带「请重启常驻 MCP 进程」
+    # 指引）；外部可选模块缺失（不在盘面的可选降级面，如 whitebox_kb/aeis_core 的
+    # 惰性身体面）非致命，但计数如实上报，不静默。
+    # 调用点必须在**函数体内**：这些延迟导入里相当一部分是为避开循环导入才写在函数
+    # 里的，本校验若放到模块顶层会把避环结构重新咬回来（同族守卫
+    # md_cg/test_generation_guard.py 有 AST 断言钉死这一点）。
+    try:
+        from . import generation as _gen
+        _dep = _gen.verify_delegations()
+    except Exception as _dep_exc:        # noqa: BLE001 —— 未通过即拒绝服务，不带病运行
+        sys.stderr.write("[mdcg-mcp] 代校验未通过（拒绝启动，fail-closed）：%s\n%s\n"
+                         % (type(_dep_exc).__name__, _dep_exc))
+        return 4
+    sys.stderr.write(
+        "[mdcg-mcp] 代校验：延迟导入 %d 项 / 目标模块 %d 个 / 已解析 %d 项 / "
+        "可选缺失 %d 项 · 代 %s\n"
+        % (_dep.get("delegations"), _dep.get("target_modules"),
+           _dep.get("resolved"), len(_dep.get("unavailable") or []),
+           _gen.STARTUP_FINGERPRINT[:12]))
     _start_sustain(cg)
 
     for line in sys.stdin: