@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/nodefile.py

@@ -39,6 +39,7 @@ CCG 要素的语义对应（白箱第 1 篇第 17 章）：
 """
 import hashlib
 import json
+import re
 import time
 
 _DELIM = "---"
@@ -54,7 +55,7 @@ CCG_REQUIRED = CCG_MARKS
 # 六要素不是注释/描述，而是**接口契约**——每行在契约里有一个确定角色：
 #     功能名 = 签名 signature（可执行入口符号）
 #     生效条件 = 前置条件 precondition（由 condition_space 四槽合成，唯一入口）
-#     子功能 = 依赖 dependency
+#     子功能 = 内部子功能分解（自述）**兼** 依赖 dependency（跨节点）
 #     执行 = 调用 invocation
 #     验证方式 = 后置条件 postcondition + test
 #     不适用条件 = 拒绝域 rejection_domain
@@ -62,14 +63,51 @@ CCG_REQUIRED = CCG_MARKS
 # 的既有硬约束同源：缺前置条件的接口无法判定可否调用，故缺参即编译错误。
 # 本常量是术语的**唯一真源**；其余模块（如 ccgc.CONTRACT_ROLES）一律引用本处，
 # 禁止各自再定义一份，防「术语双写法」漂移。
+#
+# 「子功能」的**双语义**（收窄裁定 b · 使用者 2026-09-19）——这是本槽位的既成事实，
+# 不能只看本常量的 "dependency" 四字：理论真源（智能论 3.4 §6章.3 六要素表）把该行
+# 定义为「内部子功能分解（①②③）」= **对自身的描述**；本常量记其契约角色为
+# dependency = **寄生于他者**。同一槽位承载两种语义，**靠形态区分**（不是靠猜）：
+#   · 自然语言描述本单元内部构成 → **自述**，不构成依赖声明，无需 depends_on；
+#   · `@<节点 id>` 显式引用其它单元 → **跨节点依赖声明**，必须落 depends_on。
+# 判据真源 = `declares_dependency`（本模块）；闸门 = `ccgc._check_deps` /
+# `writepipe._gate_deps`（两闸共用同一判据，收窄一处即两闸同步）。
+# **不得再退回「值非哨兵即声明」**：CCG 编译产物六要素必含本行，退回即让每个节点
+# 落库后被 E050 永久锁死（test_ccgc V16f 实证），且与理论真源的自述口径直接冲突。
 CCG_CONTRACT_ROLES = {
     "功能名":     "签名 signature（可执行入口符号）",
     "生效条件":   "前置条件 precondition",
-    "子功能":     "依赖 dependency",
+    "子功能":     "内部子功能分解 self_decomposition ／ 依赖 dependency"
+                  "（双语义，以 @<节点 id> 显式引用为界）",
     "执行":       "调用 invocation",
     "验证方式":   "后置条件 postcondition + test",
     "不适用条件": "拒绝域 rejection_domain",
 }
+
+# ---- 裁定 C（Phase 0 契约裁决 · 2026-09-17）：索引元条件与功能生效条件字段分家 ----
+# 病根：codeindex.render 曾把**机械推导的索引元条件**（本地源码仓 / 全时窗 /
+# AST 工具 / 文件可读）写成「生效条件」行，与「功能生效条件」（人工声明：
+# 这段代码在何种输入/状态下正确）**共用同一字段名**。检索侧
+# mdcos._ccg_field 取首个匹配 → 源码里人工写的生效条件行被永久压制 →
+# 「补了注释」与「没补」在检索结果上不可区分。
+# 处置（沿用 backfill.py 已裁定先例「观测位置 ≠ 生效条件」）：
+#   · 「生效条件」只承载**功能前置条件**，来源仅限人工/源码声明，
+#     **不由 render 合成**（合成即冒充）；
+#   · 索引元条件改由 INDEX_META_MARK 承载，与 CCG_MARKS **零重名**
+#     （机械可判，见 is_ccg_mark）。
+# 权威契约：docs/mdcg/代码评审与条件化注释_契约_v0.1.md
+INDEX_META_MARK = "索引元条件"
+
+
+# 生效条件：name 无论为何值先经 str().strip() 归一（name 为 None 时即字符串 "None"），归一结果落在模块常量 CCG_MARKS 中即返回 True，否则 False。
+def is_ccg_mark(name: str) -> bool:
+    """该字段名是否为 CCG 六要素之一（合成区零重名契约的机械判据）。
+
+    给「合成区字段名 ∩ CCG_MARKS = ∅」提供**可执行**判据，而不是靠注释约定：
+    test_codeindex 逐行核合成区用到的字段名。
+    """
+    return str(name).strip() in CCG_MARKS
+
 # 外部验证基底的可取值（frontmatter.verification_basis）
 #
 # 分两档（口径：文科宽松、理科严格）：
@@ -85,7 +123,156 @@ REPRODUCIBLE_BASIS = ("compiler", "test", "measurement", "formal_proof", "data")
 #: 来源一致性档：文科断言可用（来源表述一致即可）
 CONSISTENCY_BASIS = ("textbook", "public_kb")
 
+# ---- 裁定 D（2026-09-19）：可验证记忆单元的**字段名真源** --------------------------
+# 「子功能」的契约角色是**依赖 dependency**（见 CCG_CONTRACT_ROLES），其落字段即
+# `depends_on`——名字与角色对齐（不叫 sub_features，避免同一概念两种写法）。
+# 依赖一旦失效，下游的「还成不成立」就变了，故它与验证态、时间轴同属一层。
+DEPENDS_ON_FIELD = "depends_on"
+
+#: 双时间轴：何时开始成立 / 何时不再成立（判定未生效·生效中·已过期）。
+#: `valid_until` 既有（已被 scrub 的过期消费面使用）；`valid_from` 本轮补齐。
+VALID_FROM_FIELD = "valid_from"
+VALID_UNTIL_FIELD = "valid_until"
+
+#: 双时间轴的**规范键**（2026-09-19 阶段一）：新写入落此；历史键 `valid_from` /
+#: `valid_until` 保留为**读取侧回落别名**（存量不迁移、零破坏）。本处只登记字段名；
+#: **行为真源**（取值优先级 `effective_* > valid_* > 其余别名` 与三态判定）见
+#: md_cg/trust.py 的 FROM_ALIASES / UNTIL_ALIASES / validity()。
+EFFECTIVE_FROM_FIELD = "effective_from"
+EFFECTIVE_UNTIL_FIELD = "effective_until"
+
+#: 信念时间：体系**何时确认此条**——取代（supersede）/ 审核的排序锚。
+#: **第三类语义**：既不是「尚未开始」也不是「已经结束」，故**不入** scrub 的任一
+#: 键族（并入即把「已确认」误判成「已生效 / 已失效」）。物理隔离守卫见
+#: test_validity_filter.py 的交叉断言。
+BELIEVED_AT_FIELD = "believed_at"
+
+#: 过期时刻（写盘冗余：由 effective_until 派生，供审计 / 对账免计算直读）。
+EXPIRED_AT_FIELD = "expired_at"
+
+#: 巩固留痕（2026-09-19 阶段一）：何时巩固 / 巩固进哪一条（成员 → 概念 id）。
+#: 与 `promoted_at`（层迁移时刻）同族——把「归并产物可溯源」从流程记录升为一等字段。
+#: **行为真源**（写入侧）见 md_cg/consolidate.py 的 induce / promote。
+CONSOLIDATED_AT_FIELD = "consolidated_at"
+CONSOLIDATED_INTO_FIELD = "consolidated_into"
+
+#: 归纳来源（概念节点侧）：前身成员清单 / 归纳时刻。与 `consolidated_*` 同族——
+#: 成员侧列「巩固进哪一条」，概念侧列「前身是谁」，两侧互查即完整血缘。
+INDUCED_FROM_FIELD = "induced_from"
+INDUCED_AT_FIELD = "induced_at"
+
+#: 巩固 / 归纳留痕字段族（单一真源）：全族**不进索引白名单**（审计/血缘向，非查询
+#: 热点），故 `add()` 覆写时须**回读节点文件**继承（索引快照里没有这些键）——
+#: 否则概念节点被一次普通覆写（如审核 edit/merge 重写）即丢掉前身清单。
+CONSOLIDATION_FIELDS = (CONSOLIDATED_AT_FIELD, CONSOLIDATED_INTO_FIELD,
+                        INDUCED_FROM_FIELD, INDUCED_AT_FIELD)
+
+#: 验证态字段。**刻意不叫 `state`**——该名已被裁决四态（ACCEPT/REJECT/DEFER/
+#: BLINDSPOT）占用，`lifecycle_state` 的先例同此动机（观测位置不同即命名不同）。
+#: 状态枚举与合法迁移表的**行为真源是 md_cg/trust.py**；本处只登记字段名，
+#: **不复制枚举**——复制即制造第二份真源，与 CCG_CONTRACT_ROLES 的单一真源纪律相悖。
+VERIFICATION_STATE_FIELD = "verification_state"
+
+# ---- 「子功能」声明的**值语义**：哨兵与解析 --------------------------------------
+# 行存在 ≠ 有声明：`# 子功能：无` 是合法填充（绝大多数知识节点不依赖任何单元），
+# 若把它也算成「声明了依赖」，全库普通节点都会被 E050 硬拒——闸门立刻沦为噪声源。
+# 故必须区分「行存在」与「构成真实声明」，判据收在这里（单一真源，ccgc/writepipe 共用）。
+DEP_DECL_SENTINELS = ("无依赖", "无", "不适用", "不需要", "none", "n/a", "na", "-", "—")
+
+
+# 生效条件：value 为 None 或 strip 后为空 → True；strip 后等于 DEP_DECL_SENTINELS 任一项、或为该哨兵加尾部括号说明（如「无（不依赖其他单元）」）→ True；其余 False（不做语义判断）；
+def is_dep_sentinel(value) -> bool:
+    """纯函数：依赖槽的值是否属于「无依赖」哨兵。
+
+    只认**完全相等**或**哨兵+括号说明**两种形态，不做语义猜测——「无法确定」
+    这类真实陈述不得被误判为「无」（宁可多要求一次 depends_on，不可漏掉声明）。
+    """
+    s = "" if value is None else str(value).strip()
+    if not s:
+        return True
+    for mark in DEP_DECL_SENTINELS:
+        if s == mark:
+            return True
+        for lp, rp in (("（", "）"), ("(", ")")):
+            if s.startswith(mark + lp) and s.endswith(rp):
+                return True
+    return False
+
+
+# 生效条件：content 中不存在名字等于 field_name 的 `# 字段：` 行 → 返回 None；存在 → 返回首个命中行首个冒号之后的 strip 结果（可为空串）；
+def ccg_field_value(content, field_name: str):
+    """读取 `# <字段>：<值>` 的值（首个命中行；全/半角冒号兼容）。无该行 → None。
+
+    与 `ccgc._upsert_ccg_line` 的解析口径一致（去 `#`→按冒号切名字→名字相等即
+    命中）——即**写入口径与读入口径共用同一条行语义**，避免「写进去读不出」。
+    """
+    for ln in (content or "").split("\n"):
+        s = ln.strip()
+        if not s.startswith("#"):
+            continue
+        if s.lstrip("#").strip().split("：")[0].split(":")[0].strip() != field_name:
+            continue
+        for p in ("# " + field_name + "：", "# " + field_name + ":"):
+            if p in ln:
+                return ln.split(p, 1)[1].strip()
+        return ""
+    return None
+
+
+# ---- 「子功能」行中的**跨节点引用**：显式标记与提取 -------------------------------
+# 为什么需要它（收窄判据 · 使用者 2026-09-19 裁定 b）：「子功能」的契约角色是
+# dependency，但同一个槽里实际承载着两种语义完全不同的内容——
+#   ① **自述子功能**：本单元**内部**由哪些子步骤/子模块构成（如「按扩展名把文件
+#      路由到对应摄取器」）。它描述的是自身，不引用任何其它记忆单元。
+#   ② **跨节点依赖**：本单元的成立与否**寄生于另一个记忆单元**（如 `@code_xxx`）。
+#      只有它才是失效传播的入口，也只有它才需要落 `depends_on`。
+# 旧判据「值非哨兵即声明依赖」把①一并判成②：CCG 编译产物六要素必含「子功能」
+# 行，于是该节点一旦落库就被永久要求 `depends_on`——第二次 link 必被 E050 硬拒
+# （test_ccgc V16f 实证：合法内容被自己的闸门锁死）。故**收窄判据：只有显式引用
+# 形态才构成跨节点依赖声明**，自然语言自述不算（依赖不是必填元数据，不得默认要求）。
+#
+# 形态约定：`@` 紧跟节点 id（`[A-Za-z0-9_]` 起头，可含 `.`/`-`）；`@` 左侧不得是
+# 标识符字符——后半条排除 `user@host`（邮箱等）被误读为引用。中文自然语言里 `@`
+# 极罕见，故该标记本身就是「这是引用」的显式信号，**不依赖语义猜测**（与哨兵
+# 「只认完全相等」同一纪律：能机械判的绝不猜）。
+DEP_REF_MARK = "@"
+DEP_REF_RE = re.compile(r"(?<![A-Za-z0-9_])@([A-Za-z0-9_][A-Za-z0-9_.\-]*)")
 
+
+# 生效条件：value 为 None 时按空串处理 → 返回空列表；为任意值且 str 化后正则无命中 → 空列表；命中 → 按出现顺序返回去重后的 id 列表。
+def dep_refs(value) -> list:
+    """从「子功能」行的值中提取**显式跨节点引用**（`@<节点 id>`）→ 去重保序列表。
+
+    只做**形态提取**，不校验目标是否存在——「声称依赖」与「目标存在」是两件事，
+    混在一处会让「声称依赖一个并不存在的节点」被静默当成「没声明」（E051 永不触发）。
+    """
+    if value is None:
+        return []
+    out = []
+    for m in DEP_REF_RE.finditer(str(value)):
+        if m.group(1) not in out:
+            out.append(m.group(1))
+    return out
+
+
+# 生效条件：content 中「# 子功能：」行缺失 → False；行存在且其值为空或命中依赖哨兵（is_dep_sentinel）→ False；行存在且值含显式跨节点引用（dep_refs 非空）→ True；其余（自然语言自述子功能）→ False；
+def declares_dependency(content) -> bool:
+    """「# 子功能：」是否构成**跨节点依赖声明**（行存在 ∧ 值非哨兵 ∧ 含 `@<id>`）。
+
+    这是 E050 硬拒的**前置判据真源**：只有**显式声称**依赖某节点，才要求
+    `depends_on` 给出可解析目标。行缺失、哨兵、以及**自述子功能**（自然语言描述
+    本单元的内部构成）一律按「未声明」处理——依赖不是必填元数据，把自述当声明会
+    让每个 CCG 节点（六要素必含「子功能」行）永久被要求 depends_on，闸门反过来
+    锁死合法写入。**只有「声称依赖却不落字段」才是契约违规**（声称与落盘不一致，
+    被依赖单元变动时下游无处可传，传播链从源头断掉）。
+    """
+    val = ccg_field_value(content, "子功能")
+    if val is None or is_dep_sentinel(val):
+        return False
+    return bool(dep_refs(val))
+
+
+# 生效条件：content 为 None 或空串时按源码的 content or "" 回落空串计算，非空时按其原值编码，一律返回 sha256(utf-8) 十六进制摘要的前 12 位（content 的 frontmatter 不计入口径由调用方保证）。
 def content_hash(content: str) -> str:
     """节点正文的**内容指纹**（sha256 前 12 位）——全仓唯一实现。
 
@@ -102,6 +289,7 @@ def content_hash(content: str) -> str:
     return hashlib.sha256((content or "").encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：frontmatter（任意 dict，键按 sorted 输出）与 content（任意 str）均无前置校验即生效；content 不以 "\n" 结尾时补一个换行，返回 "---" + 各键的 "{k}: {json.dumps(v, ensure_ascii=False)}" 行 + "---" 行 + 正文。
 def dumps(frontmatter: dict, content: str) -> str:
     lines = [_DELIM]
     for k in sorted(frontmatter):
@@ -113,6 +301,7 @@ def dumps(frontmatter: dict, content: str) -> str:
     return "\n".join(lines) + "\n" + body
 
 
+# 生效条件：text 以 "---\n" 开头且其后存在 "\n---\n" 时才解析——head 段内含 ":" 的行按首个 ":" 拆键值（json.loads 成功取值、抛 ValueError 则保留原字符串），不含 ":" 的行跳过，返回 (fm, content)；不满足上述两个起始条件时返回 ({}, text)。
 def loads(text: str):
     """返回 (frontmatter dict, content str)。非法格式返回 ({}, 原文)。"""
     if not text.startswith(_DELIM + "\n"):
@@ -135,6 +324,7 @@ def loads(text: str):
     return fm, content
 
 
+# 生效条件：content 中出现 "# {mark}：" 或 "# {mark}:"（中/英文冒号）即把该 mark 计入 present 与 required_present；complete 为 required_present 覆盖全部 CCG_REQUIRED、all_present 为 present 覆盖全部 CCG_MARKS，ratio = len(required_present)/len(CCG_REQUIRED)，四键连同两个清单一起返回。
 def ccg_completeness(content: str) -> dict:
     """CCG 要素齐全度——白箱可审计性的量化指标。
 
@@ -157,6 +347,7 @@ def ccg_completeness(content: str) -> dict:
     }
 
 
+# 生效条件：fm 的 "verification_basis" 缺键或取值为 None 时（.get 回落 None）直接返回 False；取值非 None 时，仅当该值属于模块常量 VERIFICATION_BASIS 才返回 True。
 def verification_basis_valid(fm: dict) -> bool:
     """frontmatter.verification_basis 是否落在可接受枚举里。"""
     vb = fm.get("verification_basis")
@@ -173,6 +364,7 @@ def verification_basis_valid(fm: dict) -> bool:
 PLACEHOLDER_MARKERS = ("骨架锚点", "内容待填充", "待填充", "骨架节点")
 
 
+# 生效条件：value 为 None 或 str(value).strip() 为空串时返回 True；否则仅当去空白后的字符串包含 PLACEHOLDER_MARKERS 中任一标记词时返回 True，其余返回 False（不做语义判断）。
 def is_placeholder_text(value) -> bool:
     """占位标记的纯函数判定：空值或含占位标记 → 不可渲染为事实。
 
@@ -185,6 +377,7 @@ def is_placeholder_text(value) -> bool:
     return any(m in s for m in PLACEHOLDER_MARKERS)
 
 
+# 生效条件：content 中含 "# 不适用条件："（全角冒号）或 "# 不适用条件:"（半角冒号）即返回 True，两者都不出现返回 False。
 def has_non_applicable(content: str) -> bool:
     """是否声明了不适用条件——REJECT 路径成立的必要条件。
 
@@ -198,6 +391,7 @@ def has_non_applicable(content: str) -> bool:
 NEG_FIELD = "不适用条件"
 
 
+# 生效条件：content 为 None 时按 "" 处理；逐行 strip 后，仅当该行以 "#" 开头且 lstrip("#").strip() 又以 NEG_FIELD 开头时丢弃该行，其余行原样保留（保留原缩进），返回保留行的 "\n".join。
 def positive_body(content: str) -> str:
     """剥离 `# 不适用条件：` 行后的正文——负条件不作召回键。
 
@@ -253,6 +447,7 @@ FULL_TIME_WINDOW_TEXT = "全时窗（任意时刻成立）"
 LEGACY_POSITION_PREFIX = "观测位置："
 
 
+# 生效条件：value 为 list/tuple 时用「、」连接各元素 str().strip() 后非空的部分（空元素跳过）；value 为 None 时返回 ""；其余类型返回 str(value).strip()。
 def _as_slot_text(value) -> str:
     """槽值 → 单行文本；列表值用「、」连接（「；」留给槽间分隔，不可混用）。"""
     if isinstance(value, (list, tuple)):
@@ -262,6 +457,7 @@ def _as_slot_text(value) -> str:
     return str(value).strip()
 
 
+# 生效条件：value 可被 value[0]、value[1] 取下标并 float 化，且 lo <= FULL_TIME_WINDOW_MIN 同时 hi >= FULL_TIME_WINDOW_MAX 时返回 True；取值或 float 转换抛 TypeError/ValueError/IndexError/KeyError 时返回 False。
 def is_full_time_window(value) -> bool:
     """时间窗是否覆盖全时窗（任意时刻成立）。解析不了 → False（不冒充已声明）。"""
     try:
@@ -271,6 +467,7 @@ def is_full_time_window(value) -> bool:
     return lo <= FULL_TIME_WINDOW_MIN and hi >= FULL_TIME_WINDOW_MAX
 
 
+# 生效条件：float(value) 能被 time.gmtime 接受时按 UTC 返回 "%Y-%m-%d %H:%M"；转换或格式化抛 TypeError/ValueError/OSError/OverflowError 时返回 ""。
 def _fmt_ts(value) -> str:
     """unix 时间戳 → 「YYYY-MM-DD HH:MM」（UTC）；解析不了 → ""。"""
     try:
@@ -279,6 +476,7 @@ def _fmt_ts(value) -> str:
         return ""
 
 
+# 生效条件：先判 is_full_time_window(value) 为真则直接返回 FULL_TIME_WINDOW_TEXT（不落裸数组）；否则取 value[0]、value[1] 的 UTC 文本（下标/取值抛 TypeError/IndexError/KeyError 返回 ""），两者有任一为空串也返回 ""，均非空时返回 "{lo}～{hi}（UTC）"。
 def time_window_text(value) -> str:
     """时间窗 → 可读文本。
 
@@ -296,6 +494,7 @@ def time_window_text(value) -> str:
     return f"{lo}～{hi}（UTC）"
 
 
+# 生效条件：cs 为非 dict 时返回 ""；否则取 cs.get(key)（缺 key 键得 None），key == "time_window" 走时间窗文本、其余键走槽值文本，结果为假值或经 is_placeholder_text 判为占位时返回 ""，否则返回该文本。
 def condition_slot_text(cs, key: str) -> str:
     """单槽 → 可读值；缺失/空/待填充占位 → ""（不冒充已声明）。"""
     if not isinstance(cs, dict):
@@ -307,6 +506,7 @@ def condition_slot_text(cs, key: str) -> str:
     return s
 
 
+# 生效条件：cs（任意值，非 dict 由 condition_slot_text 兜为 ""）下，仅把 CONDITION_SLOTS 中 condition_slot_text(cs, key) 返回非空串的槽按固定顺序收集为 (槽名, 标签, 文本) 列表，缺失槽不写入。
 def condition_space_slots(cs) -> list:
     """→ [(槽名, 标签, 文本)]，只含**已声明**的槽（缺失槽不写）。"""
     out = []
@@ -317,12 +517,14 @@ def condition_space_slots(cs) -> list:
     return out
 
 
+# 生效条件：cs（任意值）下，以 condition_space_slots(cs) 实际产出的槽名为已声明集合 have，返回 CONDITION_SLOTS 中不在 have 里的键名列表（已声明槽不计）。
 def condition_space_missing(cs) -> list:
     """缺失槽名清单（待补台账用）；已声明槽不计。"""
     have = {k for k, _l, _t in condition_space_slots(cs)}
     return [k for k, _l in CONDITION_SLOTS if k not in have]
 
 
+# 生效条件：cs 任意值；require_full（默认 True）为真且 condition_space_slots(cs) 的槽数不等于 len(CONDITION_SLOTS) 时返回 ""；否则按固定顺序用「；」连接已声明槽的 "{label}：{text}"（require_full 为 False 时仅部分槽也照渲，无槽则返回 ""）。
 def condition_space_text(cs, require_full: bool = True) -> str:
     """condition_space → 单行生效条件声明。**唯一合成入口**（纯函数，无 IO）。
 
@@ -337,10 +539,38 @@ def condition_space_text(cs, require_full: bool = True) -> str:
     return "；".join(f"{label}：{text}" for _k, label, text in slots)
 
 
+# 生效条件：text 为 None 时按 "" 处理；去空白后的字符串以 LEGACY_POSITION_PREFIX 开头且长度严格大于该前缀长度时返回 True，其余（含仅等于前缀本身、空串）返回 False。
 def is_legacy_position_condition(text) -> bool:
     """文本是否为「观测位置：X」形态的单槽冒充（旧口径残留）。
 
     只认前缀形态，不做语义猜测：用于审计与迁移定位，不参与正常渲染。
     """
     s = "" if text is None else str(text).strip()
-    return s.startswith(LEGACY_POSITION_PREFIX) and len(s) > len(LEGACY_POSITION_PREFIX)
+    return s.startswith(LEGACY_POSITION_PREFIX) and len(s) > len(LEGACY_POSITION_PREFIX)
+
+
+# 生效条件：text 为假值（None/空串）时按空文本处理返回 []；否则按「；/;」拆槽、槽内含「：」或「:」时取首个分隔符之后的内容，再按「，,、/（）()」切短语，丢弃长度 <2、纯数字及命中时间维哨兵关键词的短语并去重后返回 out；
+def cond_terms(text: str) -> list[str]:
+    """生效条件声明 → 匹配短语列表（确定性切分，无语义猜测）。
+
+    切分规则：按槽分隔「；/;」拆槽（condition_space_text 以「；」连四槽）
+    → 每槽剥「槽标签：」前缀（载体/位置、时间、方法、约束等标签是通用词，
+    参与命中必误判）→ 槽内按「，,、/（）」切短语 → 丢弃长度 <2、纯数字、
+    全时窗哨兵短语（全时窗 = 时间维无信息量，不因其未命中而降级）。
+    """
+    out, seen = [], set()
+    for slot in re.split(r"[；;]", str(text or "")):
+        if "：" in slot:
+            slot = slot.split("：", 1)[1]
+        elif ":" in slot:
+            slot = slot.split(":", 1)[1]
+        for seg in re.split(r"[，,、/（）()]", slot):
+            seg = seg.strip()
+            if len(seg) < 2 or seg.isdigit():
+                continue
+            if "全时窗" in seg or "任意时刻" in seg:
+                continue
+            if seg not in seen:
+                seen.add(seg)
+                out.append(seg)
+    return out

package/md_cg/pooling.py

@@ -61,6 +61,7 @@ class PoolError(ValueError):
 # 分类 / 校验 / 计划
 # --------------------------------------------------------------------------
 
+# 生效条件：pools 为 None 或 False 时返回 None；pools is True 时先替换为模块常量 WEIGHTS 再交 validate；pools 为其他值（含 dict）时直接交 validate(pools)。
 def resolve(pools):
     """把 `pools` 参数解成生效配置：None→关闭；True→内置表；dict→校验后副本。"""
     if pools is None or pools is False:
@@ -70,6 +71,7 @@ def resolve(pools):
     return validate(pools)
 
 
+# 生效条件：entry 为假值（含 None）时按 entry or {} 处理，其 "layer" 去假值后经 str() 属模块常量 NEG_LAYERS → 返回 POOL_NEGATIVE；否则 node_id 去假值转 str 后以模块常量 INDEX_PREFIXES 起始，或 entry 的 "tags"（假值按 []）小写后任一元素恰为 index/artifact/code_index/doc_index → 返回 POOL_INDEX；其余 → POOL_KNOWLEDGE。
 def pool_of(node_id, entry=None) -> str:
     """节点归池（确定性、只看 id 前缀 / 层 / 标签，不读文件）。"""
     e = entry or {}
@@ -84,6 +86,7 @@ def pool_of(node_id, entry=None) -> str:
     return POOL_KNOWLEDGE
 
 
+# 生效条件：pools 非 dict、缺 POOL_ORDER 中任一池、pools[p] or {} 不是 dict、float(spec.get("cap_ratio")) 或 float(spec.get("weight", 1.0)) 抛 TypeError/ValueError、ratio<=0、weight<=0、或各池 cap_ratio 之和与 1.0 之差超过 _RATIO_EPS 时抛 PoolError，全部通过才返回各项为 float 的 out（desc 经 spec.get("desc") or WEIGHTS[p]["desc"] 补齐）。
 def validate(pools) -> dict:
     """校验并归一化权重表（**硬约束：额度之和必须恰为 1.0**）。"""
     if not isinstance(pools, dict):
@@ -114,6 +117,7 @@ def validate(pools) -> dict:
     return out
 
 
+# 生效条件：total 先 int(total)，total<=0 时各池返回 0；total < len(POOL_ORDER) 时把 total 全给 POOL_KNOWLEDGE、其余池为 0；否则每池保底 1、余量按 left*float(pools[p]["cap_ratio"]) 取 floor 后，余数按小数部分降序（并列按 POOL_ORDER 序）补 1，返回额度之和恰为 total 的 out。
 def caps(total: int, pools) -> dict:
     """按比例分配额度；**各池额度之和恰等于 total**。
 
@@ -141,6 +145,7 @@ def caps(total: int, pools) -> dict:
     return out
 
 
+# 生效条件：total 给出后，pools 为 None/False 等使 resolve(pools) 返回假值时返回 {'enabled': False, 'total': int(total), 'note': ...}；cfg 为真时用 caps(total, cfg) 并逐池取 cfg[p]["weight"]/cfg[p]["cap_ratio"]，返回启用态计划。
 def plan(total: int, pools=None) -> dict:
     """分池计划（供审计 / A/B 复算）：额度 + 系数 + 是否启用。"""
     cfg = resolve(pools)
@@ -155,6 +160,7 @@ def plan(total: int, pools=None) -> dict:
             "index_prefixes": list(INDEX_PREFIXES)}
 
 
+# 生效条件：pools 为 None/False 使 resolve(pools) 返回假值时返回 1.0；cfg 为真时返回 float(cfg[pool_of(node_id, entry)]["weight"])，其中 entry 缺省为 None。
 def weight_of(node_id, entry=None, pools=None) -> float:
     """节点的打分乘数（未启用分池 → 1.0，保证原行为）。"""
     cfg = resolve(pools)
@@ -163,6 +169,7 @@ def weight_of(node_id, entry=None, pools=None) -> float:
     return float(cfg[pool_of(node_id, entry)]["weight"])
 
 
+# 生效条件：docs 与 total 给出后无条件调用 take(docs, total, pools=pools, key_of=key_of) 并只返回其第 0 项，pools 与 key_of 缺省为 None 原样透传。
 def allocate(docs, total: int, *, pools=None, key_of=None) -> list:
     """分池截断（只要结果；需要各池实取数用 `take()`）。未启用 → 平截（原行为）。
 
@@ -172,6 +179,7 @@ def allocate(docs, total: int, *, pools=None, key_of=None) -> list:
     return take(docs, total, pools=pools, key_of=key_of)[0]
 
 
+# 生效条件：cfg 为真时先 quota=caps(total, cfg)，遍历 docs 时 key_of 为真则用 key_of(d) 解出 (nid, entry)、否则把 d 解包为 (nid, entry)，按 pool_of(nid, entry) 入 buckets；backflow 为真时以 total 减去各池 min(len(buckets[p]), quota[p]) 得 left，按 POOL_ORDER 只对尚有 room 的池补 quota 到 left 用尽为止，返回 (buckets, quota)。
 def _bucketize(docs, total: int, cfg, key_of, backflow: bool):
     """归池 + 分额 + 回流 → `(buckets, quota)`（`take` 与 `cut_report` 共用）。"""
     quota = caps(total, cfg)
@@ -193,6 +201,7 @@ def _bucketize(docs, total: int, cfg, key_of, backflow: bool):
     return buckets, quota
 
 
+# 生效条件：docs 经 list(docs or [])（None/空容器→[]），pools 为 None/False 使 resolve(pools) 返回假值时返回 (docs[:int(total)], {})；cfg 为真时转为 cut_report(docs, total, pools=pools, key_of=key_of, backflow=backflow) 并返回 (picked, report["taken"])。
 def take(docs, total: int, *, pools=None, key_of=None, backflow: bool = True):
     """分池截断并**回报各池实取数** → `(picked, taken)`。
 
@@ -210,6 +219,7 @@ def take(docs, total: int, *, pools=None, key_of=None, backflow: bool = True):
     return picked, report["taken"]
 
 
+# 生效条件：docs 经 list(docs or [])、total 经 int(total)，pools 为 None/False 使 resolve(pools) 返回假值时返回 (docs[:total], {"enabled": False})；cfg 为真时用 _bucketize(docs, total, cfg, key_of, backflow)，按 POOL_ORDER 逐池取 buckets[p][:quota[p]] 拼接 picked 并记录 taken/cands/lost，返回启用态完整 report。
 def cut_report(docs, total: int, *, pools=None, key_of=None,
                backflow: bool = True):
     """同 `take`，但回报**完整池账** → `(picked, report)`。
@@ -235,11 +245,13 @@ def cut_report(docs, total: int, *, pools=None, key_of=None,
                     "cands": cands, "taken": taken, "lost": lost}
 
 
+# 生效条件：docs 与 total 给出后无条件调用 take(docs, total, pools=pools, key_of=doc_key) 并只返回其第 0 项，pools 缺省为 None 原样透传。
 def cut(docs, total: int, *, pools=None) -> list:
     """检索 T2/T3 截断点专用：`docs = [(entry, fm, content)]`（只取结果）。"""
     return take(docs, total, pools=pools, key_of=doc_key)[0]
 
 
+# 生效条件：report 为真值且 report.get("enabled") 为真时，把 dict(report["taken"])/dict(report["cands"])/dict(report["lost"]) 写入 stat 的 pool_taken/pool_cands/pool_lost；否则一个键都不写，始终返回 stat。
 def record_audit(stat: dict, report) -> dict:
     """把 `cut_report` 的池账落进检索 `stat`（**关闭态不写** → 不伪造池账）。
 
@@ -252,6 +264,7 @@ def record_audit(stat: dict, report) -> dict:
     return stat
 
 
+# 生效条件：d[1].get("id") 取到真值（非 None/空串等假值）时以其为 node_id，否则回落 d[0]["path"]，并总是把 d[0] 作为 entry 返回；d[0] 无 "path" 键时在回落分支抛 KeyError。
 def doc_key(d):
     """检索文档三元组 `(entry, fm, content)` → `(node_id, entry)`。"""
     return (d[1].get("id") or d[0]["path"]), d[0]
@@ -261,6 +274,7 @@ def doc_key(d):
 # 口径冻结与复测（只读）
 # --------------------------------------------------------------------------
 
+# 生效条件：xs 先按 float 排序，xs 为空时返回 0.0；否则取 idx=max(0, min(len(xs)-1, ceil(q*len(xs))-1)) 并返回 xs[idx]，q 本身未做取值范围校验。
 def _pct(xs, q):
     """分位数（最近秩法，确定性；零依赖）。"""
     xs = sorted(float(x) for x in xs)
@@ -270,6 +284,7 @@ def _pct(xs, q):
     return xs[idx]
 
 
+# 生效条件：ids=sorted((cg.index.get("nodes") or {}).keys()) 为空时返回 []；否则 n 经 max(1, int(n))（n=0 会变成 1）、step=max(1, len(ids)//max(1,int(n)))，对 ids[::step][:max(1,int(n))] 逐个 cg._read(entry)，读失败或无 content 则 continue，首个以 # 开头的行按「含全角冒号取其后、否则去 # 与空格」生成 q，q 非空才追加，返回 out。
 def bench_queries(cg, n: int = 50) -> list:
     """从索引**确定性**取样查询词（按 id 排序等距抽，取节点标题行）。
 
@@ -308,10 +323,12 @@ DELTA_KEYS = ("p95_scanned", "p50_scanned", "mean_candidates",
               "index_share", "knowledge_share", "pool_lost_rate")
 
 
+# 生效条件：xs 为真值（非空容器）时返回 sum(xs)/len(xs)，xs 为假值（空容器或 None）时返回 0.0。
 def _mean(xs):
     return (sum(xs) / len(xs)) if xs else 0.0
 
 
+# 生效条件：res 为假值（None/空列表）时返回空 dict；否则对每个 r 取 node=r[0] or {}，以 pool_of(node.get("id"), node.get("frontmatter")) 归池并累加计数，返回 out。
 def _pool_counts(res) -> dict:
     """结果集的归池构成（对分池**敏感**的口径：索引类是否吃满召回）。"""
     out = {}
@@ -322,6 +339,7 @@ def _pool_counts(res) -> dict:
     return out
 
 
+# 生效条件：queries 为真值时用 list(queries)、为假值（None/空列表）时改用 bench_queries(cg, n=n_queries)；逐 q 调 cg.search(q, k=int(k), record=False, judge=judge, pools=pools) 且该调用抛异常则跳过该 q；meta.get("pre_cap") 为 None 时回落 meta.get("candidates")/cap，仅 cap 为真且 pre>cap 才计入截断与损失，且 pl.get("lost") 与 pl.get("cands") 均非空才计入 pool_lost_rate。
 def measure(cg, queries=None, *, k: int = 20, pools=None, judge: bool = False,
             n_queries: int = 50) -> dict:
     """同口径跑一遍（**只读**）：系统成本口径 + 结果构成口径 + 池级截断损失。
@@ -387,12 +405,14 @@ def measure(cg, queries=None, *, k: int = 20, pools=None, judge: bool = False,
                      "同口径前后对比只看方向与幅度，不当绝对结论")}
 
 
+# 生效条件：调用即从 md_cg.mdcg 取 GLOBAL_CAP（getattr 缺省 0），取到假值（0/None/空串）时经 or 0 回落 0，返回 int(...)。
 def meta_cap(cg) -> int:
     """读当前全局额度（避免硬编码漂移）。"""
     from . import mdcg
     return int(getattr(mdcg, "GLOBAL_CAP", 0) or 0)
 
 
+# 生效条件：queries 为真值时用 list(queries)、为假值（None/空列表）时用 bench_queries(cg, n=n_queries)；before 恒以 pools=None 调用 measure，after 在 pools 为 None 时用模块常量 WEIGHTS、pools 显式（含 False）时原样传入；delta 只统计 DELTA_KEYS 中 before/after 两侧均为 int/float 的键，其余不参与 Δ 计算。
 def compare(cg, queries=None, *, k: int = 20, pools=None, n_queries: int = 50) -> dict:
     """§七 要求的「同口径复测」：关闭态 vs 启用态 一并给出 + 差值 + 副作用归因。"""
     qs = list(queries) if queries else bench_queries(cg, n=n_queries)
@@ -418,6 +438,7 @@ def compare(cg, queries=None, *, k: int = 20, pools=None, n_queries: int = 50) -
                             "只说明该口径测不到池内重分配")}
 
 
+# 生效条件：无入参，调用即返回由模块常量 POOL_ORDER/WEIGHTS/INDEX_PREFIXES/NEG_LAYERS/ENV_SWITCH 组装的自描述 dict，cap_ratio_sum 为 round(sum(WEIGHTS[p]["cap_ratio"] for p in POOL_ORDER), 12)。
 def catalog() -> dict:
     """自描述（供 MCP / 人工核对）。"""
     return {"layer": "召回分池与降权（§七）",
@@ -441,6 +462,7 @@ def catalog() -> dict:
             }
 
 
+# 生效条件：pools 非 None 且非 False 时原样返回 pools；pools 为 None 或 False 时读 os.environ.get(ENV_SWITCH)，缺失/空串经 or "" 归空串并 strip().lower()，属于 ("1","on","true","yes","y") 则返回 True，否则返回 None。
 def from_env(pools=None):
     """载体侧开关：`pools` 显式给出时优先；否则读 `MDCG_POOLING`（默认关）。"""
     if pools is not None and pools is not False:
@@ -448,4 +470,4 @@ def from_env(pools=None):
     v = (os.environ.get(ENV_SWITCH) or "").strip().lower()
     if v in ("1", "on", "true", "yes", "y"):
         return True
-    return None
+    return None