@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/autonomy.py

@@ -26,13 +26,24 @@ import json
 import os
 import time
 
-from . import metacognition, predict
+from . import d_meta, metacognition, predict
 from .fsutil import append_jsonl
 
 #: 信息差评分权重：不确定度二阶差分 |d2|（加速度）×1，
 #: BLINDSPOT ×2（资格失败最重）、DEFER ×1（降级但可确认）。
 W_D2, W_BLINDSPOT, W_DEFER = 1.0, 2.0, 1.0
 
+#: D_meta 排序加分（方案 §2.4，**默认生效**）：D_meta 只进**排序键**，
+#: 不改 `score`（ΔD 定价器口径不变）、不改资格判据（score>0 才是资格）、
+#: 也不改 σ(Gain) 筛选（#37 价值链）。加分取**单一指定代理**（DMETA_PROXY），
+#: 禁三代理加权合成（智能论3.4 DEV-002a）。`MDCG_D_META=0` → compute()
+#: 返回 enabled=False → 加分退化 0（回到旧排序）。
+#: 口径诚实标注：本轮取库侧 query 无关代理 → 同轮全部提案加分同值 → **当前
+#: 口径下排序不变**；区分性待 query-relative 口径（`_neg_coverage`）在
+#: reflect 侧落盘后自然生效（不提前编造区分性）。
+W_DMETA = 0.1
+DMETA_PROXY = "unmodeled_growth"
+
 EXPLORE_LOG = "_explore.jsonl"
 
 # P-T-40 信息增益门槛（#6/#37 投影）：Value = ΔD·σ(Gain)——
@@ -44,10 +55,12 @@ GAIN_COOLDOWN = 3600.0 # 冷却秒数：过期后 σ 回 1.0（给探索机会
 _GAIN_STUCK = ("carried", "unresolved", "unknowable", "no_anchor")
 
 
+# 生效条件：cg 无 root 属性时以 '.' 作为 os.path.join 的第一参数，有 root 属性时始终使用 cg.root 的值（即使为 None，也会传入 os.path.join 导致报错），再与模块常量 EXPLORE_LOG 拼接。
 def _explore_log_path(cg):
     return os.path.join(getattr(cg, "root", "."), EXPLORE_LOG)
 
 
+# 生效条件：给定 cg 与 bid 读取探索留痕，无该 bid 的 outcomes 时返回 gain=None、sigma=1.0，最近 window（默认 GAIN_WINDOW）次终态全属 _GAIN_STUCK 且 now-last_t 小于 cooldown（默认 GAIN_COOLDOWN）时返回 sigma=0.0、gain=0，终态全属 _GAIN_STUCK 但冷却已过、且与该 bid 相关轮次的 meta_outcomes.delta[DMETA_PROXY] 均值大于 0 时同样返回 sigma=0.0、gain=0（压力仍在扩大则不放行），其余返回 sigma=1.0、gain=1；meta_outcomes 键缺失、delta 非字典或其值为非数值的轮次不计入压力均值（缺键即不触发新分支，既有 ①-④ 行为逐字不变）。
 def gain_gate(cg, bid: str, now: float | None = None,
               window: int = GAIN_WINDOW, cooldown: float = GAIN_COOLDOWN) -> dict:
     """信息增益门槛（P-T-40 第四保护投影，纯读无副作用）。
@@ -61,7 +74,7 @@ def gain_gate(cg, bid: str, now: float | None = None,
     `now` 可注入以便测试冷却过期。
     """
     now = time.time() if now is None else float(now)
-    terminals, last_t = [], 0.0
+    terminals, last_t, meta_deltas = [], 0.0, []
     try:
         with open(_explore_log_path(cg), encoding="utf-8") as f:
             for line in f:
@@ -75,30 +88,58 @@ def gain_gate(cg, bid: str, now: float | None = None,
                 if bid in oc:
                     terminals.append(str(oc[bid]))
                     last_t = max(last_t, float(r.get("t") or 0.0))
+                    # D_meta 跨轮压力增量（缺键/关闭 → 不计入 → 不触发新分支）
+                    mo = r.get("meta_outcomes")
+                    dlt = mo.get("delta") if isinstance(mo, dict) else None
+                    v = dlt.get(DMETA_PROXY) if isinstance(dlt, dict) else None
+                    if isinstance(v, (int, float)) and not isinstance(v, bool):
+                        meta_deltas.append(float(v))
     except OSError:
         pass
     if not terminals:
         return {"sigma": 1.0, "gain": None, "last_t": 0.0,
                 "reason": "无探索历史（首探放行：无证据不否决）"}
     recent = terminals[-int(window):]
-    if (len(recent) >= int(window)
-            and all(t in _GAIN_STUCK for t in recent)
-            and (now - last_t) < float(cooldown)):
+    stuck = (len(recent) >= int(window)
+             and all(t in _GAIN_STUCK for t in recent))
+    rising = bool(meta_deltas) and (sum(meta_deltas) / len(meta_deltas)) > 0
+    meta_txt = ""
+    if rising:
+        meta_txt = ("；D_meta 压力均值 %+.4f（%s，近 %d 轮留痕）"
+                    % (sum(meta_deltas) / len(meta_deltas), DMETA_PROXY,
+                       len(meta_deltas)))
+    if stuck and (now - last_t) < float(cooldown):
         return {"sigma": 0.0, "gain": 0, "last_t": round(last_t, 3),
                 "reason": ("增益门槛（P-T-40）：连续 %d 次终态无变化 %s → "
-                           "DEFER_EXHAUSTED（冷却 %ds 内不再重复探索）"
-                           % (len(recent), list(recent), int(cooldown)))}
+                           "DEFER_EXHAUSTED（冷却 %ds 内不再重复探索）%s"
+                           % (len(recent), list(recent), int(cooldown),
+                              meta_txt))}
+    if stuck and rising:
+        return {"sigma": 0.0, "gain": 0, "last_t": round(last_t, 3),
+                "meta_rising": True,
+                "reason": ("增益门槛（P-T-40）：连续 %d 次终态无变化 %s 且 "
+                           "D_meta 压力仍在扩大%s → "
+                           "DEFER_EXHAUSTED_UNDER_PRESSURE（冷却已过但不放行："
+                           "压力扩大而终态停滞 = 重复探索不再产生增益）"
+                           % (len(recent), list(recent), meta_txt))}
     return {"sigma": 1.0, "gain": 1, "last_t": round(last_t, 3),
             "reason": "有增益证据或冷却已过"}
 
 
+# 生效条件：cg 的反思记录经 metacognition._reflections 取末 int(window) 条切片（window=0 时切片即全量），按非空 query 聚合后仅 score=W_D2*d2_abs+W_BLINDSPOT*blindspot+W_DEFER*defer>0 的项进入 out（**资格判据先于加分**：score<=0 即 continue，D_meta 不构成资格），其中 enforce_gain 为真值时还须 gain_gate(cg, …, now)["sigma"]>0 否则该项标 deferred_exhausted 转入 deferred，enforce_gain 为假值时不做增益筛选全数进入 out；D_meta 加分 W_DMETA*d_meta.pressure(d_meta.compute(cg, window), DMETA_PROXY) 每轮只算一次并在循环内复用，只写入 sort_score 与 reason 证据（不改 score、不改资格、不改 σ），MDCG_D_META 关闭或未启用时该加分为 0.0；最终 out 按 (-sort_score, -last_t) 排序后截取 max(1, int(limit)) 条（limit=0 或负数也返回 1 条）并随 n_signals=len(agg) 返回；
 def proposals(cg, window: int = 200, limit: int = 3,
               enforce_gain: bool = True) -> dict:
     """从反思日志聚合信息差信号，产出排序后的探索提案。
 
     每条提案携带证据明细（d2 之和/绝对值和、BLINDSPOT/DEFER 计数、样本数），
-    排序键 = W_D2*Σ|d2| + W_BLINDSPOT*BLINDSPOT + W_DEFER*DEFER。
-    无信号的查询不产生提案（不编造探索价值）。
+    `score` = W_D2*Σ|d2| + W_BLINDSPOT*BLINDSPOT + W_DEFER*DEFER（**ΔD 定价器，
+    口径不变**）；`sort_score` = score + W_DMETA×D_meta 边界压力（排序键）。
+    无信号的查询不产生提案（不编造探索价值）——**D_meta 加分不构成资格**：
+    `score<=0` 的项在加分之前就被 continue 掉。
+
+    D_meta 只影响**排序**、不改 σ(Gain) 筛选；本轮取库侧 query 无关的单一
+    代理（DMETA_PROXY），同轮各提案加分同值，故当前口径下排序不变——
+    区分性待 query-relative 口径落盘后自然生效（不提前编造）。
 
     `enforce_gain`（默认 True）：σ(Gain) 资格筛选（#37 价值链——score 是
     定价器，Gain 是筛选器）。被门槛拦下的提案不静默丢弃，落入 `deferred`
@@ -129,17 +170,24 @@ def proposals(cg, window: int = 200, limit: int = 3,
 
     out, deferred = [], []
     now = time.time()
+    mv = d_meta.compute(cg, window=window)   # 每轮一次、循环内复用（禁 N× 扫描）
+    bonus = (round(W_DMETA * d_meta.pressure(mv, DMETA_PROXY), 4)
+             if mv.get("enabled") else 0.0)
     for a in agg.values():
         score = (W_D2 * a["d2_abs"] + W_BLINDSPOT * a["blindspot"]
                  + W_DEFER * a["defer"])
         if score <= 0:
             continue                       # 无信息差信号 → 不提案（不编造）
         a = dict(a)
-        a["score"] = round(score, 4)
+        a["score"] = round(score, 4)       # ΔD 定价器：口径不变
+        a["d_meta_bonus"] = bonus          # D_meta 排序加分（只影响排序）
+        a["sort_score"] = round(score + bonus, 4)
         a["reason"] = ("信息差信号：Σ|d2|=%s（Σd2=%s）+ BLINDSPOT×%d + DEFER×%d"
-                       "（近 %d 次反思）"
+                       "（近 %d 次反思）；D_meta 排序加分 +%s（%s=%s，三代理"
+                       "不合成；不改资格/σ(Gain)）"
                        % (a["d2_abs"], a["d2_sum"], a["blindspot"],
-                          a["defer"], a["samples"]))
+                          a["defer"], a["samples"], bonus, DMETA_PROXY,
+                          d_meta.pressure(mv, DMETA_PROXY)))
         if enforce_gain:                   # P-T-40 增益门槛：资格由实现值裁决
             gate = gain_gate(cg, metacognition._key(a["query"]), now=now)
             a["gain_gate"] = gate
@@ -148,13 +196,17 @@ def proposals(cg, window: int = 200, limit: int = 3,
                 deferred.append(a)
                 continue
         out.append(a)
-    out.sort(key=lambda x: (-x["score"], -x["last_t"]))
+    out.sort(key=lambda x: (-x["sort_score"], -x["last_t"]))
     return {"ok": True, "proposals": out[:max(1, int(limit))],
             "n_signals": len(agg), "deferred": deferred,
+            "d_meta": {"enabled": bool(mv.get("enabled")), "bonus": bonus,
+                       "proxy": DMETA_PROXY},
             "value_chain": ("Value=ΔD·σ(Gain)：score 定价排序（ΔD 代理），"
-                            "σ(Gain) 资格筛选（实现值=outcomes 留痕）")}
+                            "σ(Gain) 资格筛选（实现值=outcomes 留痕）；"
+                            "D_meta 只加排序分、不改资格（DEV-002a）")}
 
 
+# 生效条件：cg 必需，该符号始终返回 ok=True、action="explore"；其中 bypass_gain 为真值时以 enforce_gain=False 调 proposals、为假值时以 True 调（window/limit 原样透传），逐条提案用 apply/actor 调 predict.learn_blindspots 并把其首个 step 的 terminal 记入 outcomes[bid]，同一 blindspot_id 本轮已见则记为 skipped，调用抛异常则记为 error（"%s: %s" % (type(exc).__name__, exc)），并额外取本轮 d_meta.compute（append 前状态）与上一条 explore 留痕的 meta_outcomes.before，并列写入 meta_outcomes={before, prev_before, delta, proxy, enabled}（**outcomes 值类型不变**），最后 append_jsonl 写 _explore_log_path(cg) 时仅 OSError 被忽略；
 def explore(cg, apply: bool = False, limit: int = 3, window: int = 200,
             actor: str = "autonomy", bypass_gain: bool = False) -> dict:
     """最小探索闭环：提案 → 逐盲区五态验证 →（apply）回写待补线索。
@@ -173,6 +225,11 @@ def explore(cg, apply: bool = False, limit: int = 3, window: int = 200,
         （绕过增益筛选照常探索，留痕 bypass_gain 字段可审计）。
     """
     pr = proposals(cg, window=window, limit=limit, enforce_gain=not bypass_gain)
+    mv = d_meta.compute(cg, window=window)      # 本轮 D_meta（append 前状态）
+    prev = None
+    for r in d_meta.tail_jsonl(_explore_log_path(cg), 1):
+        mo = r.get("meta_outcomes") if isinstance(r, dict) else None
+        prev = mo.get("before") if isinstance(mo, dict) else None
     steps, outcomes, seen = [], {}, set()
     for p in pr["proposals"]:
         bid = metacognition._key(p["query"])
@@ -201,6 +258,20 @@ def explore(cg, apply: bool = False, limit: int = 3, window: int = 200,
            "bids": [s["blindspot_id"] for s in steps],
            "outcomes": outcomes,
            "bypass_gain": bool(bypass_gain),
+           # D_meta 并列留痕（**outcomes 值类型不变**：终态字符串契约是
+           # gain_gate 停滞集比对的前提，改成 dict 会让 σ 静默恒为 1.0）：
+           #   before      = 本轮开始时的三代理（含上轮 apply 的效果）
+           #   prev_before = 上一条 explore 留痕的 before（无则 None）
+           #   delta       = before − prev_before（跨轮压力增量 → gain_gate 输入）
+           "meta_outcomes": {
+               "before": {k: float(mv.get(k) or 0.0)
+                          for k in d_meta.PROXY_KEYS},
+               "prev_before": ({k: float(prev.get(k) or 0.0)
+                                for k in d_meta.PROXY_KEYS}
+                               if isinstance(prev, dict) else None),
+               "delta": d_meta.diff(prev, mv),
+               "proxy": DMETA_PROXY,
+               "enabled": bool(mv.get("enabled"))},
            "gain_deferred": [(d.get("query"), d.get("gain_gate", {}).get("reason"))
                              for d in (pr.get("deferred") or [])]}
     try:
@@ -214,4 +285,4 @@ def explore(cg, apply: bool = False, limit: int = 3, window: int = 200,
                      "裁决资格）；终态五态由 learn_blindspots 诚实判定；"
                      "apply=True 仅落地 carried/unresolved 的 gap_hint 待补"
                      "线索（幂等）；P-T-40 四保护=单轮深度/本轮循环去重/"
-                     "增益冷却/预算 limit（bypass_gain 显式豁免可审计）")}
+                     "增益冷却/预算 limit（bypass_gain 显式豁免可审计）")}

package/md_cg/backfill.py

@@ -127,11 +127,13 @@ CAP_RULES = OrderedDict(
 
 # ---- 通用工具 ------------------------------------------------------------
 
+# 生效条件：x 为 str 时返回 MdCGOS(x)，否则原样返回 x。
 def _as_cg(x):
     """接受 root 路径或已构造的 cg 实例——保持密级隔离与密钥上下文。"""
     return MdCGOS(x) if isinstance(x, str) else x
 
 
+# 生效条件：v 为 list/tuple 时返回分号连接的非空元素文本；v 为 None 或空串时返回 ""；否则返回 str(v).strip()（v 为 0 或 False 走此支返回 "0"/"False"）。
 def _as_text(v) -> str:
     if isinstance(v, (list, tuple)):
         return "；".join(str(x).strip() for x in v if str(x).strip())
@@ -140,12 +142,14 @@ def _as_text(v) -> str:
     return str(v).strip()
 
 
+# 生效条件：fm 为假值时按 {} 处理，state_attributes.comment 为 dict 时返回该 dict，否则返回 {}。
 def _comment(fm: dict) -> dict:
     st = (fm or {}).get("state_attributes")
     c = st.get("comment") if isinstance(st, dict) else None
     return c if isinstance(c, dict) else {}
 
 
+# 生效条件：fm 的 state_attributes 为 dict 且其下 comment 为 dict 时原样返回该 comment；否则创建并返回空 comment dict（state_attributes 非 dict 时置 fm["state_attributes"]={}，comment 非 dict 时置 st["comment"]={}）。
 def _ensure_comment(fm: dict) -> dict:
     st = fm.get("state_attributes")
     if not isinstance(st, dict):
@@ -158,10 +162,12 @@ def _ensure_comment(fm: dict) -> dict:
     return c
 
 
+# 生效条件：e 的 id 为真值时返回 id，否则返回 e 的 path 基名去掉最后 3 个字符（path 为假值时基名为空，结果空串）。
 def _node_id(e: dict) -> str:
     return e.get("id") or os.path.basename(e.get("path") or "")[:-3]
 
 
+# 生效条件：fm 的 condition_space 四槽齐全时返回 nodefile.condition_space_text 合成文本，否则返回空串。
 def _condition_text(fm: dict) -> str:
     """→ 条件空间四槽合成的生效条件声明；四槽不齐 → ""（不冒充）。
 
@@ -172,14 +178,17 @@ def _condition_text(fm: dict) -> str:
     return nodefile.condition_space_text((fm or {}).get("condition_space"))
 
 
+# 生效条件：s 为真值时返回其 sha1 前 12 位，s 为假值（None/空串等）时对空串取 sha1 前 12 位。
 def _sha(s: str) -> str:
     return hashlib.sha1((s or "").encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：batch 与 nid 经 f-string 拼接后取 sha1 前 12 位；两者为 None 会字符串化为 "None"。
 def _entry_id(batch: str, nid: str) -> str:
     return hashlib.sha1(f"{batch}|{nid}".encode("utf-8")).hexdigest()[:12]
 
 
+# 生效条件：content 中 strip 后以 # 开头且去掉 # 与空白后、全角或半角冒号前首段等于 field 的整行被删除，其余行保留并 join。
 def _remove_ccg_line(content: str, field: str) -> str:
     """删掉 `# <字段>：…` 整行（回滚用）。"""
     keep = []
@@ -192,12 +201,14 @@ def _remove_ccg_line(content: str, field: str) -> str:
     return "\n".join(keep)
 
 
+# 生效条件：cg.root 与模块级常量 BACKFILL_LOG 拼接为返回路径。
 def _log_path(cg) -> str:
     return os.path.join(cg.root, BACKFILL_LOG)
 
 
 # ---- 字段推导（唯一入口：只搬运已声明的证据） -----------------------------
 
+# 生效条件：fm 与 content 给定时，仅对 content 中尚无对应 CCG 行的字段（功能名/生效条件/子功能/执行/验证方式/不适用条件）从 fm 的已有声明（state_attributes.comment、frontmatter、verification_basis、或形参 basis_text）取值，值非空且非占位文本才写入 out，假值不写、占位文本只把字段名追加进 placeholder_out（未传该形参时用临时列表）。
 def derive_fields(fm: dict, content: str, basis_text: str = None,
                   placeholder_out: list = None) -> dict:
     """按**已有声明**推导可回填字段 → `{field: (value, basis)}`。
@@ -213,6 +224,7 @@ def derive_fields(fm: dict, content: str, basis_text: str = None,
     ph = placeholder_out if placeholder_out is not None else []
     out = {}
 
+# 生效条件：field 与 basis 在 value 为真值且 nodefile.is_placeholder_text(value) 为假时写入 out；value 为假值不写入；value 为占位文本时仅把 field 记入 ph。
     def _put(field, value, basis):
         """有值且非占位标记才写出；占位值只记名，绝不渲染成事实。"""
         if not value:
@@ -267,6 +279,7 @@ def derive_fields(fm: dict, content: str, basis_text: str = None,
 
 # ---- 节点筛选 ------------------------------------------------------------
 
+# 生效条件：cg 无 _readable 可调用时返回 True；有可调用时返回 bool(fn(e))，fn(e) 抛异常时返回 False。
 def _readable_guard(cg, e) -> bool:
     fn = getattr(cg, "_readable", None)
     if not callable(fn):
@@ -277,6 +290,7 @@ def _readable_guard(cg, e) -> bool:
         return False
 
 
+# 生效条件：仅当 cg 对 e 读出的 fm 非 None、content 未被 crypto.is_encrypted、e['layer'] 不在 SKIP_LAYERS 且 fm.get('tags') 无命中 SKIP_TAGS、ccg_completeness(content)['complete'] 为假时才继续——derive_fields（受 basis_text 影响）过滤掉 content 已有 CCG 行的可写字段为空时按 placeholder_out 是否非空返回 ('placeholder'/'unfillable', None)，非空时返回 ('', item)（item 的 id 取 nid、class 依 undeducible 是否为空取 'backfillable' 或 'partial'）；上述四个前置不满足时依次返回 ('unreadable'/'locked'/'derived'/'present', None)。
 def _classify(cg, e, nid, basis_text=None):
     """→ (skip_reason, item)；skip_reason 非空表示不参与回填。"""
     fm, content = cg._read(e)
@@ -317,6 +331,7 @@ def _classify(cg, e, nid, basis_text=None):
     }
 
 
+# 生效条件：x 经 _as_cg 后遍历 cg.index.nodes，按 ids/layer/prefix 过滤，内部层/不可读/locked/derived/present/unfillable/placeholder/partial 且 include_partial 为 False 分别计数跳过，其余标记 entry_id 并计入 targeted，items 受 limit 限制（limit 为 None 或 len(items) < limit 时追加），返回 dry_run rep。
 def plan(x, layer=None, limit=None, ids=None, include_partial=False,
          basis_text=None, prefix=None) -> dict:
     """预演：产出可回填清单，不写盘。
@@ -381,6 +396,7 @@ def plan(x, layer=None, limit=None, ids=None, include_partial=False,
 
 # ---- 回填写入 / 回滚 / 留痕 ----------------------------------------------
 
+# 生效条件：x 可被 _as_cg 解释为 CG 句柄时，按 layer/ids/prefix/entry_ids 选定条目做回填并返回含 written 等计数的 rep，其中 limit 非 None 时把写入数截断到该值。
 def apply(x, ids=None, entry_ids=None, layer=None, limit=None,
           batch=BATCH_DEFAULT, include_partial=False, basis_text=None,
           actor=None, prefix=None) -> dict:
@@ -458,6 +474,7 @@ def apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg 定位后读留痕日志，仅对 action=='backfill' 且（batch 为假值则不过滤 batch，否则 rec['batch']==batch）、（entry_ids 为假值则不过滤，否则 rec['entry_id'] 属于该集合）、write_id 未出现在已完成 rollback 集合中、节点命中 cg.index['nodes'] 且 cg._read(e) 的 fm 可读、字段当前 _ccg_field(content, f) 等于留痕 after 的记录执行撤销写回（before 为 None 则删该 comment 键，否则还原原值），无字段可撤销只计 conflict 不写盘，reverted 非空时 rebuild_index，结果汇总进返回的 rep。
 def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """按留痕反向应用：撤销本批次回填（当前值 ≠ 写入值时跳过，防覆盖）。"""
     cg = _as_cg(x)
@@ -528,6 +545,7 @@ def rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，action/batch 为真值时过滤对应日志记录；limit 不为 None 且 >=0 时按 recs[-limit:] 截断（limit=0 时切片为全部记录），limit 为 None 或负数时不截断；返回 total/returned/records。
 def history(x, limit=100, action=None, batch=None) -> dict:
     cg = _as_cg(x)
     recs = []
@@ -555,6 +573,7 @@ def history(x, limit=100, action=None, batch=None) -> dict:
 _CAP_TEMPLATE_LINES = ("验证方式",)
 
 
+# 生效条件：content 中去除 # 与空白后、全角或半角冒号前首段命中 _CAP_TEMPLATE_LINES 的行被剔除，其余行保留并 join。
 def _cap_body(content: str) -> str:
     """正文（供关键词匹配）——剔除 CCG 模板行，防模板词污染候选。"""
     keep = []
@@ -567,6 +586,7 @@ def _cap_body(content: str) -> str:
     return "\n".join(keep)
 
 
+# 生效条件：当 fm 为可 get 的 frontmatter、e 为带 id 的节点条目、content 为正文文本时，返回 title+e.id+功能名/生效条件/子功能字段+正文前 300 字合并后的小写串（不含 fm.tags）。
 def _cap_text(e, fm, content) -> str:
     """候选匹配文本：节点标识 + CCG 字段 + 正文（**不含 `fm.tags`**）。"""
     parts = [_as_text(fm.get("title")), e.get("id") or ""]
@@ -578,6 +598,7 @@ def _cap_text(e, fm, content) -> str:
     return " ".join(parts).lower()
 
 
+# 生效条件：text 包含 CAP_RULES 中某 cap 的至少一个关键词时，该 cap 以匹配关键词与置信度加入返回，按置信度降序、cap 升序排序；无匹配返回空 hits。
 def cap_matches(text: str) -> list:
     hits = []
     for cap, kws in CAP_RULES.items():
@@ -589,6 +610,7 @@ def cap_matches(text: str) -> list:
     return hits
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 ids/layer 过滤，不可读计 denied，读取失败或加密计 locked，扫描后以 _cap_text 匹配并过滤 confidence >= min_conf 且标签未含 cap:，无命中计 present，有命中则 targeted 并受 limit 限制加入 items，返回 dry_run rep。
 def cap_plan(x, layer=None, limit=None, ids=None, min_conf=0.5) -> dict:
     """预演：按关键词启发式给出 `cap:<op>` 标签建议（含依据与置信度），不写盘。"""
     cg = _as_cg(x)
@@ -626,6 +648,7 @@ def cap_plan(x, layer=None, limit=None, ids=None, min_conf=0.5) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 BATCH_DEFAULT；先 cap_plan 得 items，按 entry_ids 过滤；逐个检查节点存在、读取可读、无新增标签分别计 drift/locked/drift，成功写 tags 并记日志，limit 非 None 且 written >= limit 时 break；返回 rep。
 def cap_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
               batch=BATCH_DEFAULT, min_conf=0.5, actor=None) -> dict:
     """注入 `cap:<op>` 标签：只改 frontmatter.tags，不动正文。"""
@@ -676,6 +699,7 @@ def cap_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg，读取日志中 action=cap 且未回滚的记录，按 batch/entry_ids 过滤，节点存在且原加入标签仍在 tags 中时移除，否则计 conflict/missing，返回 rep。
 def cap_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """撤销 cap 注入：仅移除**仍在 tags 里**的 `cap:` 标签（防覆盖后续修改）。"""
     cg = _as_cg(x)
@@ -730,6 +754,7 @@ def cap_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
 EXEMPT_FLAG = "ccg_exempt"
 
 
+# 生效条件：fm 的 verification_basis 合法且 content 的 ccg_completeness 标记 complete 时返回 (True, [])，否则把缺失项放入 miss 返回 ready=False。
 def _exempt_ready(fm: dict, content: str):
     """摘豁免前置条件 → `(ready, missing)`。
 
@@ -745,6 +770,7 @@ def _exempt_ready(fm: dict, content: str):
     return (not miss), miss
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 ids/prefix/layer 过滤，内部层/不可读/读取失败或加密分别计数跳过，fm 无 EXEMPT_FLAG 计 not_exempt，require_ready 为真且不 ready 时计 unready 并在 want 为 None 时跳过，否则生成 item 受 limit 限制；sample 为真值时按 id 序等距抽取 sample 个。
 def exempt_plan(x, layer=None, limit=None, ids=None, require_ready=True,
                 sample=0, prefix=None) -> dict:
     """预演：列出可摘 `ccg_exempt` 的节点（默认要求证据就绪），不写盘。
@@ -804,6 +830,7 @@ def exempt_plan(x, layer=None, limit=None, ids=None, require_ready=True,
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 BATCH_DEFAULT；先 exempt_plan 得 items，按 entry_ids 过滤；逐个检查节点存在、可读、EXEMPT_FLAG 仍真、require_ready 为真时 _exempt_ready 再次通过；不通过计 skipped_unready 并记 exempt_skip；通过则置 EXEMPT_FLAG=False 写盘记日志；limit 限制 written；返回 rep。
 def exempt_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
                  batch=BATCH_DEFAULT, require_ready=True, actor=None,
                  prefix=None) -> dict:
@@ -864,6 +891,7 @@ def exempt_apply(x, ids=None, entry_ids=None, layer=None, limit=None,
     return rep
 
 
+# 生效条件：当 x 可解析为 cg 时，日志中 action 为 exempt 的记录若其非空 write_id 已存在于既有 action 为 exempt_rollback 的记录 write_id 集合中，则跳过并计入 skipped_done，否则在通过 batch 与 entry_ids 过滤后，节点存在且可读、EXEMPT_FLAG 当前为假时，该记录才被还原并计入 reverted；。
 def exempt_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """反向还原 `ccg_exempt`：仅当当前仍为「已摘」状态时还原，否则计 conflict。"""
     cg = _as_cg(x)
@@ -920,6 +948,7 @@ def exempt_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
 #   ③ verify_conditions    只读复算：验收指标 legacy_position == 0
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 prefix/layer 过滤，内部层/不可读/读取失败或加密/derived 层或 SKIP_TAGS 分别计数跳过；扫描后，正文已有生效条件计 declared，derive_fields 可推出计 derivable，否则按 condition_space 缺失槽计 pending 并受 limit 限制收集 items；返回 rep。
 def conditions_pending(x, prefix=None, layer=None, limit=None) -> dict:
     """只读台账：列出「未声明生效条件、且四槽推不出」的节点及其缺失槽。
 
@@ -978,6 +1007,7 @@ def conditions_pending(x, prefix=None, layer=None, limit=None) -> dict:
     return rep
 
 
+# 生效条件：cg 的留痕日志中存在 basis 为 LEGACY_CONDITION_BASIS 且未被回滚的 backfill 生效条件写入时，按 node 记录最后一次的 after/original 返回；无匹配返回空。
 def _legacy_condition_records(cg) -> dict:
     """→ {node: {after, original, …}}：我们**自己写下的**单槽冒充行（真源 = 留痕）。
 
@@ -1005,6 +1035,7 @@ def _legacy_condition_records(cg) -> dict:
     return out
 
 
+# 生效条件：x 经 _as_cg，从 _legacy_condition_records 取候选，按 prefix 过滤，节点不存在/不可读/读取失败或加密分别计 missing/denied/locked；当前生效条件等于留痕 after 时，四槽合成非空则 rewrite 否则 drop，不等则 conflict；items 受 limit 限制；返回 dry_run rep。
 def fix_conditions_plan(x, prefix=None, limit=None) -> dict:
     """预演：清洗存量单槽冒充行。不写盘。
 
@@ -1054,6 +1085,7 @@ def fix_conditions_plan(x, prefix=None, limit=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，batch 假值回落 FIX_BATCH_DEFAULT；先 fix_conditions_plan 得 items，按 ids/entry_ids 过滤；逐个再验当前值仍等于 before 且 comment_before 一致，否则 skipped_drift；rewrite 时 upsert 生效条件行并写 comment，drop 时删行并还原 comment；写盘记 condition_fix，drop 另记 condition_pending；limit 限制 rewritten+dropped；返回 rep。
 def fix_conditions_apply(x, ids=None, entry_ids=None, prefix=None, limit=None,
                          batch=FIX_BATCH_DEFAULT, actor=None) -> dict:
     """执行清洗：`rewrite` 改写为四槽合成声明；`drop` 删行并登记待补。
@@ -1144,6 +1176,7 @@ def fix_conditions_apply(x, ids=None, entry_ids=None, prefix=None, limit=None,
     return rep
 
 
+# 生效条件：x 经 _as_cg，读取日志中 action=condition_fix 且未回滚的记录，按 batch/entry_ids 过滤，节点存在且当前生效条件等于 after 时，还原 before（空则删行）并还原 comment_before，否则计 conflict/missing；返回 rep。
 def fix_conditions_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     """按留痕反向应用：恢复被改写的旧值 / 重建被删除的冒充行。
 
@@ -1210,6 +1243,7 @@ def fix_conditions_rollback(x, batch=None, entry_ids=None, actor=None) -> dict:
     return rep
 
 
+# 生效条件：x 经 _as_cg，遍历 nodes 按 prefix 过滤、内部层跳过，读取失败或加密跳过；对每个节点当前生效条件行，缺失计 absent，否则按 is_legacy_position_condition、等于 _condition_text 合成、等于 comment、其他分别计数，legacy_ids 受 limit 限制；返回 rep。
 def verify_conditions(x, prefix=None, limit=None) -> dict:
     """复算核对（只读）：生效条件行的来源分布 + 弱等价残留计数。
 
@@ -1264,6 +1298,7 @@ ACTIONS = ("backfill", "backfill_rollback", "backfill_history",
            "exempt", "exempt_rollback", "exempt_history")
 
 
+# 生效条件：按其 action 分派——action=='backfill' 时 kw['apply'] 为真调 apply(x, 去掉 apply 的 kw)、否则调 plan 同参；action=='cap'/'exempt' 同理在 kw['apply'] 为真时调 cap_apply/exempt_apply、否则调 cap_plan/exempt_plan；action=='backfill_rollback'/'cap_rollback'/'exempt_rollback' 分别调 rollback/cap_rollback/exempt_rollback(x, **kw)；action=='backfill_history' 调 history(x, **kw)，'cap_history'/'exempt_history' 调 history(x, action='cap'/'exempt', **kw)；其余 action 值抛 ValueError。
 def run(x, action, **kw) -> dict:
     """`maintain` op 的分派入口：action ∈ ACTIONS。"""
     if action == "backfill":
@@ -1290,4 +1325,4 @@ def run(x, action, **kw) -> dict:
         return exempt_rollback(x, **kw)
     if action == "exempt_history":
         return history(x, action="exempt", **kw)
-    raise ValueError(f"未知 backfill action：{action}（允许：{ACTIONS}）")
+    raise ValueError(f"未知 backfill action：{action}（允许：{ACTIONS}）")

package/md_cg/backfill_bigdomain.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""big_domain 域标签回填（S1 大域收敛的前置元数据；幂等、支持 --dry-run）。
+
+用法：
+  python -X utf8 -m md_cg.backfill_bigdomain --root <库根> [--dry-run] [--limit N]
+
+为何需要单独的回填入口：域标签是**写入侧**新增的元数据，存量节点没有；
+S1 要按域收敛，就必须先把存量补齐（契约 §8.1）。
+"""
+import argparse
+import json
+import sys
+
+from .mdcg import MdCG
+
+
+# 生效条件：无条件解析参数（root 必填，dry_run/limit 可选）、以 MdCG(root) 打开库、调用 backfill_big_domain 并把统计 dict 以 JSON 打印，返回 0。
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True, help="库根目录")
+    ap.add_argument("--dry-run", action="store_true", dest="dry_run",
+                    help="只统计不改盘")
+    ap.add_argument("--limit", type=int, default=None, help="最多补写多少个节点")
+    a = ap.parse_args(argv)
+    cg = MdCG(a.root)
+    st = cg.backfill_big_domain(dry_run=a.dry_run, limit=a.limit)
+    print(json.dumps(st, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())