@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/census.py

@@ -31,6 +31,7 @@ DEFAULT_ROOT = os.path.join(
 ARCHIVE_DIRS = ("trash", "_protected_history", "_protected", "_index_log", "hippocampus")
 
 
+# 生效条件：当 root 为记忆库根目录、其下 .md 能被 nodefile.loads 解析出 frontmatter 时，返回 [(node_id, layer, condition_space, tags)...]；ARCHIVE_DIRS 与 _protected_history_ 目录整棵剪枝，无 frontmatter 的 md 跳过。
 def load(root):
     """遍历 md 记忆库根，返回 [(node_id, layer, condition_space, tags), ...]。
 
@@ -62,6 +63,7 @@ def load(root):
     return out
 
 
+# 生效条件：rows 非空、每行可解包为 (_, _, d, t) 且 keyfn(d, t) 可调用时，打印桶数、最大桶占比、单例桶比与期望扫描占比，无返回值。
 def report(name, rows, keyfn):
     cnt = collections.Counter(keyfn(d, t) for _, _, d, t in rows)
     n = len(rows)
@@ -78,12 +80,14 @@ def report(name, rows, keyfn):
     print(f"  ★条件路由后期望扫描占比 = {exp * 100:.1f}%  (100%=退化成全量, 越低越有效)")
 
 
+# 生效条件：传入 keys（任意可迭代键序列，含空序列时对 json.dumps({}) 求哈希）即返回一个接收 (d, t) 的 lambda，该 lambda 按 keys 逐个取 d.get(k)（缺键得 None）并 sort_keys=True、ensure_ascii=False 序列化后取 sha256 十六进制前 10 位，形参 t 不参与计算。
 def by_keys(keys):
     return lambda d, t: hashlib.sha256(
         json.dumps({k: d.get(k) for k in keys}, sort_keys=True,
                    ensure_ascii=False).encode()).hexdigest()[:10]
 
 
+# 生效条件：以 root 调用 load(root) 得 rows，先打印「总节点: len(rows)」（空序列也会先打印该行），仅当 rows 为假值时才打印空库提示并 return 2，否则继续打印分层与各维度取值分布、并执行方案A/B/C/D 的 report 后 return 0。
 def main(root):
     rows = load(root)
     print(f"md 记忆库: {root}")
@@ -126,4 +130,4 @@ if __name__ == "__main__":
     # 会在解释器退出阶段丢缓冲（实测只落盘 444 字节），CI 里会看不到失败原因。
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
-    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ROOT))
+    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else DEFAULT_ROOT))

package/md_cg/chain.py

@@ -39,11 +39,17 @@ EDGE_WEIGHTS = {
     "correlational": 0.45,
     "cyclic": 0.35,
     "opposite": 0.30,
+    # 正文引用边（linkref，写入侧自动解析，2026-09-17）：取弱权重——正文提及
+    # ≠ 语义相似 ≠ 因果依赖，故与 DEFAULT_EDGE_WEIGHT 同值；显式登记的意义在
+    # 「类型已知」（可审计、可按类型调参、可区分于未登记类型的兜底默认）。
+    "reference": 0.50,
 }
 DEFAULT_EDGE_WEIGHT = 0.50
 
 CAUSAL_TYPES = ("causal",)
 # 检索默认沿「有语义方向」的关系走：因果 / 时序 / 条件适用
+# 注：reference **刻意不入**——正文提及不应进入「前提→结论」条件序列遍历，
+# 否则 causal 链会被「提到过」这类无向弱关联稀释（模式分离）。
 CHAIN_TYPES_DEFAULT = ("causal", "sequential", "applies_to")
 
 MAX_DEPTH_DEFAULT = 5
@@ -51,6 +57,7 @@ MAX_DEPTH_HARD = 64
 MAX_NODES_DEFAULT = 500
 
 
+# 生效条件：edge 为 dict 时按 relation_type→relation→type 顺序取首个真值、非 dict 时 rel 记为 None，两者统一返回 str(rel or "").strip().lower()——键缺失或全为假值时得空串。
 def edge_rel(edge):
     """取边的 relation_type（兼容 dict / 字符串两种写法），统一小写。"""
     if isinstance(edge, dict):
@@ -60,6 +67,7 @@ def edge_rel(edge):
     return str(rel or "").strip().lower()
 
 
+# 生效条件：edge 为 dict 时取 target or target_id（前者假值回落后者），该值非 None 则返回其 str().strip()、为 None 返回 None；edge is None 返回 None；其余（裸字符串等）返回 str(edge).strip() 或空白串时 None。
 def edge_target(edge):
     """取边的目标节点 id（兼容 target / target_id / 裸字符串）。"""
     if isinstance(edge, dict):
@@ -70,6 +78,7 @@ def edge_target(edge):
     return str(edge).strip() or None
 
 
+# 生效条件：base 取 EDGE_WEIGHTS.get(edge_rel(edge), DEFAULT_EDGE_WEIGHT)；edge 为 dict 时 conf 为 float(edge.get("confidence", 1.0))（缺该键得 1.0，值不可转 float 如 None 触发 TypeError/ValueError 时也回落 1.0），非 dict 时 conf 恒为 1.0，返回 round(base * max(0.0, min(1.0, conf)), 6)；
 def edge_weight(edge):
     """边权重 = 类型 base × 边置信度（缺失置信度视为 1.0 的已声明边）。"""
     base = EDGE_WEIGHTS.get(edge_rel(edge), DEFAULT_EDGE_WEIGHT)
@@ -82,6 +91,7 @@ def edge_weight(edge):
     return round(base * max(0.0, min(1.0, conf)), 6)
 
 
+# 生效条件：edge 非 dict 时返回 ""；edge 为 dict 时按 ("condition","conditions","条件") 顺序取第一个真值（list/tuple 先以 "；" 连接其中 str(x).strip() 非空的项，连接结果为空则视为假值跳过该键）并返回 str(v).strip()；三键均无真值且 edge.get("condition_space") 为 dict 时返回 condition_space_text(cs, require_full=False)；否则返回 ""；
 def edge_condition(edge):
     """边的条件标注：条件链上「这一跳在什么条件下成立」。"""
     if not isinstance(edge, dict):
@@ -101,6 +111,7 @@ def edge_condition(edge):
     return ""
 
 
+# 生效条件：cg.get(nid) 为假值（该节点缺失或为空）时返回 []；否则以 node.get("frontmatter") or {} 与 node.get("content") or "" 调 _declared_conditions，返回其正向条件列表 pos；
 def node_conditions(cg, nid):
     """节点自己声明的生效条件（CCG `# 生效条件：` 等三处来源合并）。"""
     node = cg.get(nid)
@@ -112,6 +123,7 @@ def node_conditions(cg, nid):
     return pos
 
 
+# 生效条件：cg 已有 _chain_adj 且其 [0] 等于 bool(include_hierarchy) 时直接返回缓存的 [1]；否则以 cg.index["nodes"]（无 index 或无该键时视为无节点）逐节点收集 frontmatter.edges 中 edge_target 非空的出边，include_hierarchy 为真时再为 subgraph.nodes 各合成一条 relation_type="part_of"、confidence=1.0 的层级边，仅对有出边的 nid 建表，写回 cg._chain_adj=(bool(include_hierarchy), adj) 后返回 adj；
 def adjacency(cg, include_hierarchy=True):
     """出邻接表：nid → [(target_id, edge_dict)]。
 
@@ -146,6 +158,7 @@ def adjacency(cg, include_hierarchy=True):
     return adj
 
 
+# 生效条件：调用即把 cg._chain_adj 置为 None（赋值抛异常时静默忽略），无返回值；
 def invalidate_cache(cg):
     """写入/删除节点后丢弃邻接缓存（与 subgraph.invalidate_cache 成对调用）。"""
     try:
@@ -154,6 +167,7 @@ def invalidate_cache(cg):
         pass
 
 
+# 生效条件：对 adj 的每个 src→[(tgt, e)] 逐条把 (src, e) 追加到 rev[tgt]（同 tgt 多次追加保持出现顺序），adj 为空字典时 rev 为空字典并返回；
 def _reverse(adj):
     rev = {}
     for src, outs in adj.items():
@@ -162,6 +176,7 @@ def _reverse(adj):
     return rev
 
 
+# 生效条件：start_id 起步迭代 DFS——max_depth 非 None 时先钳为 max(0, min(int(max_depth), MAX_DEPTH_HARD))，rels 为 (relation_types or ()) 的小写元组（None 或空则不作类型过滤），direction=="in" 时邻接表改用 _reverse(adjacency(cg, include_hierarchy))，每跳要求 rel∈rels（rels 非空时）、tgt 不在 seen、weight*edge_weight(e) ≥ min_weight，链在 max_depth 为 None 或 len(hops+[hop]) ≤ max_depth 时收入、在 max_depth 为 None 或 len(hops+[hop]) < max_depth 时继续下探，首跳且边无显式条件时条件回退 start_id 的 node_conditions，扩展节点数受 max_nodes、收链数受 max_chains 限制，sort=="length" 时按 (depth, -avg_weight) 排序否则按 (-weight, -depth) 排序，返回 chains[:max_chains]；
 def walk(cg, start_id, relation_types=CAUSAL_TYPES, max_depth=MAX_DEPTH_DEFAULT,
          direction="out", max_nodes=MAX_NODES_DEFAULT, min_weight=0.0,
          max_chains=200, include_hierarchy=True, sort="strength"):
@@ -218,13 +233,18 @@ def walk(cg, start_id, relation_types=CAUSAL_TYPES, max_depth=MAX_DEPTH_DEFAULT,
                 stack.append((tgt, seen | {tgt}, nhop, nw))
         if not extended and not hops:
             continue
+    # 终键 tuple(nodes)：图遍历序取决于邻接结构的枚举序，并列（同 depth/
+    # weight/avg_weight）时若无终键，截断结果随索引构建路径漂移。
     if sort == "length":            # 对齐 AEIS infer_causal_paths 的 Occam 偏好
-        chains.sort(key=lambda c: (c["depth"], -c["avg_weight"]))
+        chains.sort(key=lambda c: (c["depth"], -c["avg_weight"],
+                                   tuple(c["nodes"])))
     else:
-        chains.sort(key=lambda c: (-c["weight"], -c["depth"]))
+        chains.sort(key=lambda c: (-c["weight"], -c["depth"],
+                                   tuple(c["nodes"])))
     return chains[:max_chains]
 
 
+# 生效条件：kw 未含 relation_types 时先注入 CAUSAL_TYPES，再以 walk(cg, start_id, **kw) 的每条链逐跳渲染（跳条件为空串则显示「（未声明条件）」），返回 {"start": start_id, "count": 渲染链数, "chains": rendered}；
 def explain(cg, start_id, **kw):
     """人类可读的链式解释：「什么条件下 → 发生什么」。"""
     kw.setdefault("relation_types", CAUSAL_TYPES)
@@ -242,6 +262,7 @@ def explain(cg, start_id, **kw):
     return {"start": start_id, "count": len(rendered), "chains": rendered}
 
 
+# 生效条件：seeds 为 dict 时取其 items、否则取 list(seeds or [])（假值 seeds 得空列表，返回空 best），逐 (sid, s0) 跳过 sid 为假值或 float(s0) 抛 TypeError/ValueError 的项，对 walk(cg, sid, relation_types, max_depth, max_nodes, max_chains, include_hierarchy) 每条链取 nodes[-1] 为 nid（nid==sid 则跳过）并按 s0*链 weight*decay^depth 对每个 nid 只保留最高分，返回 best；
 def expand_from_seeds(cg, seeds, relation_types=CHAIN_TYPES_DEFAULT,
                       max_depth=MAX_DEPTH_DEFAULT, decay=0.9,
                       max_nodes=MAX_NODES_DEFAULT, max_chains=500,
@@ -277,4 +298,4 @@ def expand_from_seeds(cg, seeds, relation_types=CHAIN_TYPES_DEFAULT,
             if cur is None or sc > cur["score"]:
                 best[nid] = {"score": round(sc, 6), "chain": c,
                              "depth": c["depth"], "conditions": c["conditions"]}
-    return best
+    return best

package/md_cg/codeindex.py

@@ -31,14 +31,37 @@ MAX_DOC = 400
 LANG_COMPILER = "compiler"
 LANG_WEAK = "other"
 
+# --------------------------------------------------------------------------
+# 渲染契约代际（版本戳）
+# --------------------------------------------------------------------------
+# 生效条件：`render` 的**产物形态**发生不兼容变化时 +1（形态不变的重构不 +1）；
+# 由 refindex 写入 frontmatter.code_ref.render_version（节点侧），由 selfreport
+# 随常驻进程自报（进程侧），两侧同取本常量——**同源，无第二处硬编码**。
+#
+# 用途（第③道防线，防「旧契约静默覆盖重建成果」）：
+#   ① 节点侧：`scripts/mdcg_verify_render_meta.py` 据 code_ref.render_version 机械
+#      判定「节点由哪一代 render 产出」，不再只靠形态启发式（正文含元条件行）；
+#   ② 进程侧：`scripts/mdcg_stale_servers.py` 据自报值判定活进程代际，堵住
+#      「进程启动时间晚于源码 mtime 故 stale=False、却持旧 render」的盲区
+#      （AGENTS.md §5 运维注记的活体实证：旧契约把全量重建成果刷回 old_synth）。
+#
+# 代际史：
+#   1 = 旧契约（npm 0.4.8 及以前）：合成区产出 `# 生效条件：载体/位置：…`，
+#       索引元条件冒用 CCG 字段名（合成即冒充）。
+#   2 = 三分区契约（2026-09-19）：源码 CCG 区置首 → 合成 CCG 区（不产出生效
+#       条件行）→ 索引元信息区（`# 索引元条件：…` 非 CCG 字段名 + 位置行）。
+RENDER_VERSION = 2
+
 
 # --------------------------------------------------------------------------
 # Python：AST 提取（精确）
 # --------------------------------------------------------------------------
+# 生效条件：node 传入后，取 ast.get_docstring(node, clean=True) 的返回值，若该返回值为假值则回落空串，返回 strip 后截断到模块级 MAX_DOC 的文本；
 def _doc_of(node):
     return (ast.get_docstring(node, clean=True) or "").strip()[:MAX_DOC]
 
 
+# 生效条件：lines 为源码行列表、lineno 为 1-based 定义行时，从 lines[lineno-2] 向上收集连续以 "#" 起始的行，遇空行且已收集到注释即停止，遇空行且未收集到注释则跳过继续，遇非注释非空行停止，返回按物理顺序排列的注释列表；lineno<=1 或初始无匹配时返回空列表；
 def _leading_comments(lines, lineno):
     """定义行前的连续注释（# ...）。"""
     out, i = [], lineno - 2
@@ -56,6 +79,55 @@ def _leading_comments(lines, lineno):
     return list(reversed(out))
 
 
+# 生效条件：node 具有真值 body 属性时返回 body[0].lineno；否则（body 为 None/假值/缺属性）返回 node.lineno；
+def _body_first_line(node):
+    """符号体首个语句的行号（1-based）；无体 → 定义行本身（窗口为空）。"""
+    body = getattr(node, "body", None) or []
+    return body[0].lineno if body else node.lineno
+
+
+# 生效条件：lines 为 source.split("\n") 得到的行列表、lineno 为 1-based 定义行、body_lineno 为 1-based 体首语句行时，在 end=max(lineno, body_lineno-1) 下扫描 lines[lineno:end]，收集 strip 后以 "#" 起始的行并返回；body_lineno-1 <= lineno 时返回空列表；
+def _body_comments(lines, lineno, body_lineno):
+    """符号**体内首个语句之前**的连续 `#` 注释（定义行紧下方，声明头区）。
+
+    这是与 `_leading_comments`（定义行**之上**）并列的**第二个窗口**：
+
+    · 既有白箱单元库 104+ 处把 CCG 注释块写在**这里**
+      （例：`md_cg/whitebox_kb/wisdom/python_code_units.py` 的模板
+      `def tokenize(src):` 下一行即 `    # 生效条件：参数 src 合法`）；
+    · 本函数是 body 窗口的**唯一真源**——`whitebox_kb/wisdom/verifier._ccg_block`
+      委托此处（历史文档里那句「与 `codeindex._body_comments` 同款语义」曾是
+      **悬空引用**：该名当时并不存在）。
+
+    参数：`lines`=源码行列表（`source.split("\\n")`）；`lineno`=定义行（1-based）；
+    `body_lineno`=体首个语句行（1-based）。窗口 = `lines[lineno : body_lineno-1]`
+    （0-based 切片：定义行之后 → 体首语句之前），只收 `#` 起始行。
+    语法上该窗口**结构性地只可能含注释/空行/docstring**——体首语句之前的区域。
+    """
+    start = lineno                      # 0-based 索引 → 定义行的下一行
+    end = max(start, body_lineno - 1)
+    out = []
+    for ln in lines[start:end]:
+        s = ln.strip()
+        if s.startswith("#"):
+            out.append(s)
+    return out
+
+
+# 生效条件：lines 为源码行列表且 node 含 lineno 时，返回 _leading_comments(lines, node.lineno) 与 _body_comments(lines, node.lineno, _body_first_line(node)) 的拼接结果（leading 在前、body 在后）；
+def _symbol_comments(lines, node):
+    """符号的「源码 CCG 区」= leading 窗口 + body 窗口，**按物理行序**合并。
+
+    不发明额外优先级：两个窗口在源文件里的物理先后天然确定（leading 在定义行
+    之上、body 在其下），而检索侧 `mdcos._ccg_field` 取**首个**匹配——于是
+    「靠前者胜出」与「物理序」是同一件事，确定性可复算。
+    单窗口文件的行为与改造前逐字一致（只多收 body 窗口）。
+    """
+    return (_leading_comments(lines, node.lineno)
+            + _body_comments(lines, node.lineno, _body_first_line(node)))
+
+
+# 生效条件：source 与 node 传入后，取 ast.get_source_segment(source, node) 的返回值，若抛 ValueError/TypeError 或返回假值则 seg 为空串，返回 seg.split("\n",1)[0].strip()[:200]；
 def _sig(source, node):
     try:
         seg = ast.get_source_segment(source, node) or ""
@@ -64,6 +136,7 @@ def _sig(source, node):
     return seg.split("\n", 1)[0].strip()[:200]
 
 
+# 生效条件：tree 为 AST 根节点时，调用嵌套 rec(tree, "") 按 ast.iter_child_nodes 源码顺序递归产出 (定义节点, 所属类名)；ClassDef 自身以当前 parent 产出并对其内部递归改用类名，FunctionDef/AsyncFunctionDef 以当前 parent 产出并保持 parent，其他节点递归保持 parent；
 def _walk_defs(tree):
     """按**源码顺序**产出 (定义节点, 所属类名)。
 
@@ -71,6 +144,7 @@ def _walk_defs(tree):
     父级归属是「子功能」与「不适用条件」两项的判定依据（同名方法必须能区分
     是哪个类的），不能省。
     """
+# 生效条件：node 为 AST 节点、parent 为当前所属类名字符串时，按 ast.iter_child_nodes(node) 顺序递归产出 (定义节点, 所属类名)：ClassDef 以 parent 产出并递归改用 child.name，FunctionDef/AsyncFunctionDef 以 parent 产出并递归保持 parent，其他节点递归保持 parent；
     def rec(node, parent):
         for child in ast.iter_child_nodes(node):
             if isinstance(child, ast.ClassDef):
@@ -84,6 +158,7 @@ def _walk_defs(tree):
     return rec(tree, "")
 
 
+# 生效条件：source 可被 ast.parse 成功解析时，返回首项为 module 条目（path、name=os.path.basename(path) or "<module>"、lineno=1、end=len(source.split("\n"))、doc=_doc_of(tree)）后接 _walk_defs(tree) 各定义条目的列表；source 触发 SyntaxError 时抛 ValueError(f"{path}:{exc.lineno}: {exc.msg}")；
 def _extract_python(source, path):
     try:
         tree = ast.parse(source)
@@ -101,7 +176,7 @@ def _extract_python(source, path):
             "path": path, "name": node.name, "kind": kind, "parent": parent,
             "lineno": node.lineno, "end": getattr(node, "end_lineno", node.lineno),
             "sig": _sig(source, node), "doc": _doc_of(node),
-            "comments": _leading_comments(lines, node.lineno)})
+            "comments": _symbol_comments(lines, node)})
     return items
 
 
@@ -118,6 +193,7 @@ _JS_DEF = re.compile(
 _JS_MODULE_SCOPE_ONLY = ("const", "type", "enum")
 
 
+# 生效条件：lines 为源码行列表、lineno 为 1-based 定义行时，从 lines[lineno-2] 向上收集连续以 "//" 开头的行注释，或遇到 strip 后以 "*/" 结尾的行时向上收集到首个 strip 后以 "/*" 开头的行（含该行）作为块注释；lookback 默认 25 限制收集行数，lookback=0 时循环不进入并返回空列表；遇空行且已有收集即停止，空行且未收集则跳过，其他行停止；
 def _leading_js_comments(lines, lineno, lookback=25):
     """定义行前的连续行注释块，或紧邻的 /** ... */ 块。"""
     out, i = [], lineno - 2
@@ -146,6 +222,7 @@ def _leading_js_comments(lines, lineno, lookback=25):
     return list(reversed(out))
 
 
+# 生效条件：对 source 用 _JS_DEF.finditer 命中项生成条目（首项模块条目 name 为 os.path.basename(path) or "<module>"），跳过 kind 属于 _JS_MODULE_SCOPE_ONLY 且 indent 组非空的命中；其余命中按出现顺序取 lineno、kind、name、sig，end 为下一命中行号减一或 len(source.split("\n")) 且不小于 lineno，comments 由 _leading_js_comments(lines, lineno) 生成。
 def _extract_weak(source, path):
     """正则弱提取：返回条目，`end` 为**上界**（到下一个定义之前），不保证精确。"""
     lines = source.split("\n")
@@ -182,6 +259,7 @@ EXTRACTORS = {
 SUFFIX = tuple(sorted(EXTRACTORS))
 
 
+# 生效条件：lines 为行列表、lineno 与 end 为 1-based 行号时，对 "\n".join(lines[max(0, lineno-1):max(0, end)]) 的 UTF-8 字节求 sha1，返回其十六进制前 12 位；
 def region_hash(lines, lineno, end):
     """被引用行的 sha1 前 12 位（变更探测用，非内容寻址）。
 
@@ -192,6 +270,7 @@ def region_hash(lines, lineno, end):
     return hashlib.sha1(seg.encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：source 与 path 传入后，ext=suffix or os.path.splitext(path)[1].lower()；当 ext 存在于模块级 EXTRACTORS 时，用对应 fn(source, path) 抽取并给每个条目补 lang/precise/basis/hash（hash 由 region_hash(lines, it["lineno"], it["end"]) 算）后返回；ext 不在 EXTRACTORS 时抛 ValueError(f"无提取器（suffix={ext or '<none>'}）")；
 def extract(source, path="", suffix=None):
     """抽取一个文件的条目；按后缀分派提取器。语法错误抛 ValueError。
 
@@ -213,15 +292,18 @@ def extract(source, path="", suffix=None):
     return items
 
 
+# 生效条件：item 为条目字典时，path=item.get("path") or ""、top=path.split("/")[0] or "."，按 item.get("precise", True)（缺键默认 True，键存在假值走弱提取）选择 LANG_COMPILER 或 LANG_WEAK 方法文本，返回 observation_position 用 top、time_window 用 nodefile.FULL_TIME_WINDOW_MIN 与 nodefile.FULL_TIME_WINDOW_MAX、observation_tool 用方法文本、existence_constraint 含 path 的四槽字典；
 def condition_space(item):
     """条目 → 条件空间四槽（纯函数，**唯一来源**）。
 
-    为什么必须与 `render` 同源：正文的 `# 生效条件：` 行与 frontmatter 的
+    为什么必须与 `render` 同源：正文的 `# 索引元条件：` 行与 frontmatter 的
     `condition_space` 一旦各写一套，就会出现「正文有声明、条件空间是空的」
     ——`nodefile.condition_space_text(require_full=True)` 只看 frontmatter，
     于是节点**存得进、判得了，条件空间却没声明**。改造前正是这样：正文写
     「大域=X；检索…时」（第三种方言），frontmatter 只写 `observation_position`
     **单槽**。单槽不是生效条件（见 nodefile.CONDITION_SLOTS_REQUIRED），
+    该四槽在正文里由「索引元条件」行承载（**不再**占用「生效条件」字段——
+    Phase 0 契约裁决，见 nodefile.INDEX_META_MARK），
     故本函数按四槽齐备产出，供 `render` 与 `refindex.add_items` 共用。
 
     时间槽用**全时窗哨兵**而非 `mdcg.add` 缺省补的「写入时刻锚定 1 小时窗」：
@@ -244,8 +326,9 @@ def condition_space(item):
     }
 
 
+# 生效条件：item 为含 "name"、"kind"、"path"、"lineno"、"end" 键的条目字典时（缺这些必需键会 KeyError），返回由 item.get("comments") 的源码 CCG 区、合成 CCG 区、索引元信息区依次拼接的正文；parent/doc/comments/sig 按 item.get 缺键或假值回落，precise 缺键默认 True、键存在假值走弱提取，item["lineno"]/item["end"] 用于 basis 与位置行；
 def render(item):
-    """条目 → CCG 6 行正文（可被 search 命中，不含实现）。
+    """条目 → 正文三分区：源码 CCG 区（人工优先）→ 合成 CCG 区 → 索引元信息区。
 
     **必须渲染成 CCG 格式**，这是本模块最容易踩的坑：
     `judge_qualification` 第一步就查 `ccg_completeness` 的 5 要素
@@ -255,6 +338,16 @@ def render(item):
     `# path::name` / `# sig` / `# doc:` 这类非 CCG 行，于是**所有代码节点
     恒定 BLINDSPOT**：存得进、判不了、检索不到（与「目标节点的 CCG 渲染」
     是同一策略，见 mdcg.py 的对应注释）。
+
+    Phase 0 修复（行序压制 + 字段语义分家；契约见
+    docs/mdcg/代码评审与条件化注释_契约_v0.1.md）：
+      ① **源码 CCG 区置首**——mdcos._ccg_field 取**首个**匹配，置首即
+         「人工优先」的确定性序：人工声明的生效条件不再被合成行压制；
+      ② 合成区**不再产出生效条件行**——索引元条件不是功能前置条件
+         （裁定见 nodefile.INDEX_META_MARK）。故源码未声明的条目会**诚实地
+         缺该要素（BLINDSPOT）**，而不是被元条件冒充成 DEFER；
+      ③ 索引元信息区改用非 CCG 字段名（索引元条件行 + 位置行），两个语义
+         不再挤同一个字段名（可机械判：nodefile.is_ccg_mark）。
     """
     name = item["name"]
     kind = item["kind"]
@@ -270,27 +363,37 @@ def render(item):
     else:
         basis = (f"{LANG_WEAK}（正则弱提取，未过编译器；区间为**上界**，"
                  f"以 op=ref 回读为准：{path} L{item['lineno']}-L{item['end']}）")
-    lines = [
+    # ---- 三分区组装（顺序即语义，不许随手改）------------------------------
+    #   ① 源码 CCG 区：人工/源码声明逐字保留，**置首**取得「首个匹配」优先权
+    #   ② 合成 CCG 区：机械补齐 5 要素，保证 ccg_completeness 不因缺行整体失效
+    #   ③ 索引元信息区：非 CCG 字段名 + 位置行（与 CCG_MARKS 零重名）
+    lines = ["# " + c for c in comments]
+    lines += [
         f"# 功能名：{name}（{kind}）",
-        f"# 生效条件：{nodefile.condition_space_text(condition_space(item))}",
         f"# 子功能：{parent + '.' if parent else ''}{sub[:MAX_DOC]}",
         f"# 执行：{sig}",
         f"# 验证方式：{basis}",
         "# 不适用条件：其它大域的**同名**符号（同名不同域时以 path 区分；"
         f"本条目属于 {path}）",
+        # 索引元条件**不占用**生效条件字段：它是「条目在何处/何时可被观测」，
+        # 不是「这段代码在何种输入下正确」。合成即冒充（nodefile.INDEX_META_MARK）。
+        f"# {nodefile.INDEX_META_MARK}："
+        + nodefile.condition_space_text(condition_space(item),
+                                        require_full=False),
         f"# 位置：{path}:{item['lineno']}-{item['end']}"
         f"（{item.get('lang')}，precise={bool(item.get('precise', True))}）",
     ]
-    lines.extend("# " + c for c in comments)
     return "\n".join(lines)
 
 
+# 生效条件：item 为含 "path" 与 "name" 键的字典时（缺任一键会 KeyError），返回 "code_" 加 (item["path"] + "::" + item["name"]).encode("utf-8") 的 sha1 十六进制前 12 位；
 def node_id(item):
     """稳定 id：path::name 的短哈希（重复索引幂等）。"""
     key = (item["path"] + "::" + item["name"]).encode("utf-8")
     return "code_" + hashlib.sha1(key).hexdigest()[:12]
 
 
+# 生效条件：skip_dirs 传入后，遍历 (skip_dirs or ()) 把每项 str(raw).strip().replace("\\","/").strip("/")，空串跳过；含 "/" 的加入 paths，不含 "/" 的加入 names；若归一化后无规则返回 (None, [])，否则返回 (hit, rules)，其中 hit(rel_dir, base) 在 base 命中 names 或 rel_dir 等于/前缀匹配 paths 中某条加 "/" 时为 True；
 def skip_matcher(skip_dirs):
     """把调用方的 `skip_dirs` 编译成「该子目录是否排除」的判定 `hit(rel_dir, base)`。
 
@@ -320,6 +423,7 @@ def skip_matcher(skip_dirs):
     if not rules:
         return None, []
 
+# 生效条件：在 skip_matcher 返回的闭包中，rel_dir 与 base 传入后，若 base 命中由 skip_dirs 归一化出的不含 "/" 的目录名集合 names 则返回 True；否则若 rel_dir 等于或以其某个含 "/" 的路径规则 paths 加 "/" 为前缀则返回 True；两者都不满足返回 False；
     def hit(rel_dir, base):
         if base in names:
             return True
@@ -328,6 +432,7 @@ def skip_matcher(skip_dirs):
     return hit, rules
 
 
+# 生效条件：当 root 为可 os.walk 的目录时返回 (items, errors, stats)；patterns 为 None 时按模块常量 SUFFIX 取后缀，命中 max_files 或 max_items 上限则在 stats['truncated'] 上报截断，fresh 为 None 时逐文件读盘。
 def index_dir(root, patterns=None, max_files=500, max_items=2000,
               fresh=None, on_file=None, skip_dirs=None):
     """按大域（目录）遍历代码，产出 `(items, errors, stats)`。零 LLM。
@@ -350,11 +455,25 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
     pats = tuple(patterns or SUFFIX)
     hit_skip, skip_rules = skip_matcher(skip_dirs)
     items, errors, files = [], [], 0
+    hit_files = 0
     seen_suffix = set()
     stats = {"root": root, "patterns": list(pats), "files": 0, "truncated": False,
              "truncated_reason": "", "max_files": max_files, "max_items": max_items,
              "skipped_suffixes": [], "skipped_unchanged": 0,
-             "skip_dirs": list(skip_rules), "skipped_dirs": []}
+             "skip_dirs": list(skip_rules), "skipped_dirs": [],
+             # 截断**可复算**：命中（后缀匹配）文件数与本轮已产出条目数。
+             # 与 truncated_reason 一起读，调用方才能核对「差多少」而不是只看到"被截断了"。
+             "hit_files": 0, "indexed_items": 0}
+
+# 生效条件：无参闭包，只在本次扫库作用域内可调用；把 files / hit_files / indexed_items / skipped_suffixes / skipped_dirs 一次性落进 stats，三处 return 共用同一口径；
+    def _snap():
+        """把「截断相关」计数一次性落进 stats（三处 return 共用，避免各处口径漂移）。"""
+        stats["files"] = files
+        stats["hit_files"] = hit_files
+        stats["indexed_items"] = len(items)
+        stats["skipped_suffixes"] = sorted(
+            s for s in seen_suffix if s and s not in pats)[:12]
+
     for dirpath, dirnames, filenames in os.walk(root):
         rel_dir = os.path.relpath(dirpath, root).replace("\\", "/")
         if rel_dir == ".":
@@ -369,21 +488,22 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
                 stats["skipped_dirs"].append(child)
                 continue
             keep.append(d)
-        dirnames[:] = keep
+        # 目录序**必须确定性**：os.walk 给出的 dirnames 顺序由文件系统决定，
+        # 同一次输入两次运行可能不同 → 索引结果不可复算。排序后 walk 顺序唯一。
+        dirnames[:] = sorted(keep)
         for fn in sorted(filenames):
             ext = os.path.splitext(fn)[1].lower()
             seen_suffix.add(ext)
             if not fn.lower().endswith(pats):
                 continue
+            hit_files += 1
             if files >= max_files or len(items) >= max_items:
                 stats["truncated"] = True
                 stats["truncated_reason"] = (
                     f"files={files}>=max_files={max_files}"
                     if files >= max_files else
                     f"items={len(items)}>=max_items={max_items}")
-                stats["files"] = files
-                stats["skipped_suffixes"] = sorted(
-                    s for s in seen_suffix if s and s not in pats)[:12]
+                _snap()
                 return items, errors, stats
             files += 1
             fp = os.path.join(dirpath, fn)
@@ -404,12 +524,9 @@ def index_dir(root, patterns=None, max_files=500, max_items=2000,
                     stats["truncated"] = True
                     stats["truncated_reason"] = (
                         f"items={len(items)}>=max_items={max_items}")
-                    stats["files"] = files
-                    stats["skipped_suffixes"] = sorted(
-                        s for s in seen_suffix if s and s not in pats)[:12]
+                    _snap()
                     return items, errors, stats
             except (OSError, UnicodeDecodeError, ValueError) as exc:
                 errors.append(f"{rel}: {exc}")
-    stats["files"] = files
-    stats["skipped_suffixes"] = sorted(s for s in seen_suffix if s and s not in pats)[:12]
-    return items, errors, stats
+    _snap()
+    return items, errors, stats