@furongjun1999/dsh-memory 0.6.1 → 0.7.1

package/md_cg/nodefile.py

@@ -637,4 +637,77 @@ def cond_terms(text: str) -> list[str]:
             if seg not in seen:
                 seen.add(seg)
                 out.append(seg)
-    return out
+    return out
+
+
+# ---- §5.1 六要素的**索引角色**：那张表从 4 行长成 6 行（P2-1）------------------
+#
+# 理论真源 `docs/theory/智能论3.4.md:3053-3059` 的「要素 | 标记 | 内容 |
+# **图的索引角色**」表**只有 4 行**（功能名/生效条件/子功能/执行）。v0.4 §5.1
+# 依裁定 2 把表补成 6 行，后两行为**新增检索维度**；本常量即那 6 行的
+# **代码侧唯一真源**（检索面、索引条目、守卫三处共用一份，禁止各写一份）。
+#
+# 表的两列语义：
+#   · 字段名 = CCG 六要素之一（`CCG_MARKS` 的子集，顺序即理论表序）；
+#   · 索引键 = 该要素在检索面上的**键名**（前 4 行既有，后 2 行本批新增）。
+# 「索引键」进索引条目（`MdCG._node_entry`）成为**免读文件的扁指标量**——
+# 与既有 `time_window` / `observation_position` 同款理由（检索期不读盘）。
+CCG_INDEX_ROLES = (
+    ("功能名",     "语义符号",   "已有"),
+    ("生效条件",   "条件词",     "已有（S2 门控）"),
+    ("子功能",     "结构词",     "已有"),
+    ("执行",       "机制词",     "已有"),
+    ("验证方式",   "后置条件词", "P2-1 新增：按验证手段检索"),
+    ("不适用条件", "拒绝域词",   "P2-1 新增：按边界检索（boundary_hit）"),
+)
+
+#: 新增两行的**字段名 → 索引键名**映射（索引条目里的扁平键；单一真源）。
+#: 键名刻意带 `_terms` 后缀：它们是**词项列表**（扁指标量），不是正文行原样。
+POSTCONDITION_FIELD = "验证方式"
+REJECTION_FIELD = "不适用条件"
+POSTCONDITION_TERMS_KEY = "postcondition_terms"
+REJECTION_TERMS_KEY = "rejection_terms"
+INDEX_TERMS_KEYS = (POSTCONDITION_TERMS_KEY, REJECTION_TERMS_KEY)
+
+#: 索引词项的最小长度。口径与 `mdcg.NEG_MIN_TERM`（负条件判据的词长下限）
+#: **同值同义**：单字符碎片（的/与/3）不是检索键。两处不可各自取值——
+#: `md_cg/test_p2_six_elements.py` 有交叉断言钉住两常量相等。
+ELEMENT_TERM_MIN = 2
+
+#: 索引词项的切分面：槽分隔（；;）、短语分隔（，,、/）、括号与空白。
+#: 为什么与 `cond_terms` 不同：那两个要素是**自由文本行**（不是条件空间四槽
+#: 合成串），没有「槽标签：」前缀，故不需要剥标签那一步；切分面本身同族。
+_ELEMENT_TERM_SPLIT_RE = re.compile(r"[；;，,、/（）()\[\]【】{}\s]+")
+
+
+# 生效条件：value 为假值（None/空串/纯空白）时按空文本处理返回 []；否则按「；;，,、/（）()[]【】{}空白」切分、逐段 strip、丢弃长度 < ELEMENT_TERM_MIN 的段与纯数字段、命中 is_dep_sentinel（空值语义哨兵）或 is_placeholder_text（骨架占位）的段、以及已入选的重复段，返回保序去重的 out；
+def element_terms_from_text(value, min_len: int = ELEMENT_TERM_MIN) -> list[str]:
+    """要素文本 → 索引词项（**确定性切分，无语义猜测**）。
+
+    这是「六要素索引键」的**切分单点**：`MdCG._node_entry` 与守卫共用。
+    只做形态切分 + 空值语义剔除，不做任何同义/近义扩展（同 `cond_terms` 纪律）。
+    """
+    out, seen = [], set()
+    for seg in _ELEMENT_TERM_SPLIT_RE.split(str(value or "")):
+        seg = seg.strip().strip("。.．:：")
+        if len(seg) < int(min_len) or seg.isdigit():
+            continue
+        if is_dep_sentinel(seg) or is_placeholder_text(seg):
+            continue
+        if seg not in seen:
+            seen.add(seg)
+            out.append(seg)
+    return out
+
+
+# 生效条件：field_name 为 CCG 要素名且 content 含该行时，取该行值（走 ccg_field_value 单点）→ 经 element_terms_from_text 切分成词项列表；该行缺失/值为空时返回 []；
+def ccg_element_terms(content: str, field_name: str,
+                      min_len: int = ELEMENT_TERM_MIN) -> list[str]:
+    """CCG 要素文本 → 索引词项（**取值走既有单点**，检索面不得另写正则）。
+
+    取值**必须**经 `ccg_field_value`（仓内 CCG 行解析的唯一真源：冒号可有可无、
+    首个命中行为准、与写入闸门 `data/policy.json` 同一行语义）；本函数只在其上
+    叠加**切分**，绝不自己 `re.match(r"^#\\s*验证方式")` ——那会立刻长出第二套
+    行语义（`ccg_mark_present` 的取单点动因即此类分叉）。
+    """
+    return element_terms_from_text(ccg_field_value(content, field_name), min_len)

package/md_cg/protect.py

@@ -82,7 +82,7 @@ def _entry(cg, node_id):
     return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
 
 
-# 生效条件：cg 索引中无 node_id 条目时返回 None；有条目时先取 layer/importance（缺 importance 键回落 0.5）/protected/protection_reason/immutable/self_state，仅当条目缺 protected 或 immutable、或（缺 self_state 且条目 layer∈PROTECTED_LAYERS）、或（条目 layer∈PROTECTED_LAYERS 且 _GATE_UNKNOWN_KEYS 中任一键的值为 None）时再经 cg.get(node_id) 用 frontmatter 覆盖这四个键（cg.get 抛异常或返回假值时保留索引值；layer 取 frontmatter.layer or 索引 layer，importance 缺键时回落索引 importance）。
+# 生效条件：cg 索引中无 node_id 条目时返回 None；有条目时先取 layer/importance（缺 importance 键回落 0.5）/protected/protection_reason/immutable/self_state/importance_source（issue50-e：缺键读 None），仅当条目缺 protected 或 immutable、或（缺 self_state 且条目 layer∈PROTECTED_LAYERS）、或（条目 layer∈PROTECTED_LAYERS 且 _GATE_UNKNOWN_KEYS 中任一键的值为 None）时再经 cg.get(node_id) 用 frontmatter 覆盖这些键（cg.get 抛异常或返回假值时保留索引值；layer 取 frontmatter.layer or 索引 layer，importance 缺键时回落索引 importance）。
 def _fm(cg, node_id):
     """取判定所需的 frontmatter 字段；索引快照门控字段**未知**时回退读文件。"""
     e = _entry(cg, node_id)
@@ -95,6 +95,9 @@ def _fm(cg, node_id):
         "protection_reason": e.get("protection_reason"),
         "immutable": e.get("immutable"),
         "self_state": e.get("self_state"),
+        # issue50-e：重要度来源进判定面（_node_entry/_stage 恒落该键，值可为
+        # None ⇒「缺省来源」；老索引条目缺键时 .get() 同样得 None，等价缺省）。
+        "importance_source": e.get("importance_source"),
     }
     # 回退读文件：索引快照缺字段时。self_state 只在受保护层（self/anchor）
     # 需要，回退代价被限制在少量节点上，不影响全量统计性能。
@@ -128,12 +131,30 @@ def _fm(cg, node_id):
             fm["self_state"] = f2.get("self_state")
             fm["layer"] = f2.get("layer") or fm["layer"]
             fm["importance"] = f2.get("importance", fm["importance"])
+            fm["importance_source"] = f2.get("importance_source")
     return fm
 
 
-# 生效条件：cg 索引无 node_id 条目（_fm 直接返回 None，不走回退读文件）时返回 (False, '')；有条目时按 layer∈PROTECTED_LAYERS 返回 (True, 层保护)；否则 protected is True 时返回 (True, protection_reason 或 '显式保护标记')；否则 importance（缺失/假值/float 转换异常一律按 0.0）≥AUTO_PROTECT_IMPORTANCE 时返回 (True, 重要性保护)；其余返回 (False, '')。
+# 生效条件：cg 索引无 node_id 条目（_fm 直接返回 None，不走回退读文件）时返回 (False, '')；有条目时按 layer∈PROTECTED_LAYERS 返回 (True, 层保护)；否则 protected is True 时返回 (True, protection_reason 或 '显式保护标记')；否则 importance（缺失/假值/float 转换异常一律按 0.0）≥AUTO_PROTECT_IMPORTANCE 且 importance_source 为 None（键缺省）或 'hint' 时返回 (True, 重要性保护)——issue50-e：'heuristic' 等显式非 hint 来源不得由分数触发；其余返回 (False, '')。
 def is_protected(cg, node_id):
-    """**不可遗忘**判定 → (是否受保护, 原因)。节点不存在返回 (False, "")。"""
+    """**不可遗忘**判定 → (是否受保护, 原因)。节点不存在返回 (False, "")。
+
+    issue50-e（2026-10-02，使用者裁定「读面也只认显式来源」）：按分自动保护
+    只对**缺省来源或显式 hint** 的分数生效。issue50-d 落盘了启发式真分
+    （importance=0.7x + importance_source="heuristic"、不打保护位），若本
+    判定不看来源，读面（遗忘/搬迁闸、protect.check、scrub 净化与 confidence
+    校准的 skip 判定、stats 盘点）会把机器推断的分数重新认回受保护——写侧
+    「只落分不打位」被读侧单方面推翻。边界：
+    ① 键缺省（None）= 存量节点（既有 cg.add(importance=0.9) 直写、维护路径
+      调分等从未有过该键）⇒ 行为一字不变——按「缺省即不认」会大规模改变
+      既有保护面，禁止；
+    ② "hint" = 显式声明（写侧对 hint 过线本就打位，按分分支只是其无位形态
+      的兜底，语义不变）；
+    ③ "heuristic" 及其它显式来源不得由分数触发——机器推断的重要度不构成
+      不可遗忘的依据。层保护（PROTECTED_LAYERS）、fm.protected 位、
+      is_immutable 一律不动；MERGE 强化（forgetting.reinforce 跨 0.7 置
+      protected=True）是「重复确认」的显式动作，不经本分支，不受影响。
+    """
     fm = _fm(cg, node_id)
     if fm is None:
         return False, ""
@@ -146,7 +167,11 @@ def is_protected(cg, node_id):
         imp = float(fm.get("importance") or 0.0)
     except Exception:
         imp = 0.0
-    if imp >= AUTO_PROTECT_IMPORTANCE:
+    # issue50-e（2026-10-02）：按分保护**只认缺省或显式 hint 来源**——
+    # 语义与边界见 docstring ①②③；_fm 恒带 importance_source 键（缺省读
+    # None），老索引条目缺键同样落 None ⇒ 存量按分保护一字不变。
+    _src = fm.get("importance_source")
+    if imp >= AUTO_PROTECT_IMPORTANCE and (_src is None or _src == "hint"):
         return True, f"重要性保护：importance={imp:.2f}≥{AUTO_PROTECT_IMPORTANCE}"
     return False, ""
 
@@ -220,6 +245,56 @@ def snapshot(cg, node_id):
     return rel
 
 
+# 生效条件：cg.get(node_id) 抛异常或返回假值时返回 None（与 snapshot 同口径——目标不存在＝动作不会发生，由调用方按既有错误路径处理）；否则在 cg.root/HISTORY_DIR/node_id 下以「秒级时间戳-微秒后缀」命名写入当前 frontmatter 与 content（写盘形态与 snapshot 逐位一致：同目录、同 nodefile 序列化、同 _write_node 封装钩子），_write_node 抛异常时返回 None，成功则追加一条 action="preimage" 的审计（reason 交代动作类与 pid）并返回相对 cg.root 且以 '/' 分隔的路径；
+def snapshot_preimage(cg, node_id, action="", pid=None, reason="", actor=None):
+    """执行时点前像（设计 §四「回滚原语通用化」：快照面推广为一切 C/D/B）。
+
+    与 `snapshot()` 的关系（**面复用、语义泛化**，既有行为一字不动）：
+    `_protected_history/<id>/` + `_protected_audit.jsonl` 这一对从「仅受保护节点」
+    推广为「一切 C/D/B 动作」的**前像面**——本函数是新入口，`snapshot()` /
+    `guard_*` 的既有形态（文件名 `%Y%m%d-%H%M%S.md`、审计 action="snapshot"、
+    reason「显式快照（rel）」、覆盖路径快照数）**不改一行**（守卫钉死）。
+    两条差别都是为「执行时点前像」的场景补强：
+      · 文件名带微秒后缀——同一节点的多个变更单可能在**同一秒**内先后执行，
+        秒级名会互相覆盖（探针实测：同秒二次 snapshot 返回同一路径）——前像
+        被后来的前像踩掉，早先那张的回滚句柄就指向错误时点的内容；
+      · 审计 action="preimage" 且 reason 交代动作类/pid——回滚与 §七 R3 读数
+        （「存在实测回滚记录」）要能把「变更单前像」与既有显式快照区分开。
+
+    为什么前像必须在**执行时点**拍（设计 §四 明文）：变更单在提议时点构造，
+    从提议到 accept 之间目标可能被第三方改动——回滚必须撤销**本变更本身**，
+    而不是一并抹掉第三方改动。故由执行桥（`mdcos._mutation_execute`）在动作
+    原语落盘**之前**拍摄，作为载荷 `before` 字段（执行时点快照引用）。
+
+    边界（如实）：加密库（覆写了 `_seal_content` 的实例）里本文件的密文层
+    因每次封装熵不同**不保证逐字节可复现**——前像的语义是「明文内容 + 结构
+    的可恢复」，逐字节比对在非加密库（含一切守卫合成库）上成立（探针实测）。
+    """
+    try:
+        node = cg.get(node_id)
+    except Exception:
+        node = None
+    if not node:
+        return None
+    d = os.path.join(cg.root, HISTORY_DIR, node_id)
+    os.makedirs(d, exist_ok=True)
+    ts = (time.strftime("%Y%m%d-%H%M%S", time.localtime())
+          + "-%06d" % (time.time_ns() // 1000 % 1000000))
+    p = os.path.join(d, f"{ts}.md")
+    try:
+        cg._write_node(node.get("id"), p, node.get("frontmatter") or {},
+                       node.get("content") or "")
+    except Exception:
+        return None
+    rel = os.path.relpath(p, cg.root).replace("\\", "/")
+    _audit(cg, "preimage", node_id,
+           reason or ("执行时点前像（动作类 %s，pid=%s）"
+                      % (action or "?", pid or "?")),
+           actor=actor if actor is not None else getattr(cg, "actor", None),
+           snapshot=rel)
+    return rel
+
+
 # 生效条件：cg.root/HISTORY_DIR/node_id 不是目录时返回 []；是目录时返回该目录下以 .md 结尾（不递归）的文件按名称排序后的 `HISTORY_DIR/node_id/文件名` 列表，无匹配文件则列表为空。
 def history(cg, node_id):
     """受保护节点的历史版本列表（按时间升序）。"""

package/md_cg/provenance.py

@@ -431,7 +431,7 @@ def _node_digest(cg, nid) -> dict:
     N226（2026-09-28）：此前直读 `cg.index` 无可见性判定 ⇒ 端点摘要（layer/
     tags/importance/writer/session/temporal）把读闸拒绝节点的元数据照返回
     （实测 guest 经 `cg(op="edges", expand_nodes=true)` 拿到私密节点摘要）。
-    同库同身份的 `stg.timeline`（stg.py:133/172）早已接线 `_readable`——本处
+    同库同身份的 `stg.timeline`（stg.py:144/238）早已接线 `_readable`——本处
     是漏网的旁路出口，改为同一个跨层单点（`security.node_visible`）。
     """
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}

package/md_cg/review_cli.py

@@ -26,6 +26,13 @@ noop 语义：**已评估、判定不改变任何现有记忆**——只留痕
 审计 md 节点）并关闭提案，不落业务节点、不进负记忆。它与 reject 的区别是
 「评估过了、无需改动」而非「否掉这条候选」，故不可借 noop 绕过 accept 门控。
 
+变更单（三档自治批次②，kind=mutation）：队列里除「提案」外还有**变更单**
+——对既有记忆的 B 合并 / C 改写 / D 删除（设计 v0.2 §四）。`list` 会把它显式
+标为 `变更单(动作名→目标)`：accept = **执行**对应动作（B reinforce/converge、
+C 覆写落盘、D 软删），reject = 原样留痕不执行；edit/merge/noop 对变更单未定义
+（fail-closed 报错，不会静默当已处理）。存量条目无 `kind` 键，一律按提案走原
+路径（零迁移）。
+
 裁决留痕：decisions.jsonl + 审计 md 节点（由 review_decide 内部完成）。
 
 落盘归因（P1 修复，2026-09-26，DSH 端在役实测回告）：
@@ -112,6 +119,27 @@ def _brief(rec, width=66):
     return text[:width] + ("…" if len(text) > width else "")
 
 
+# 生效条件：rec 支持 .get 且其 kind 为 "mutation" 时返回「变更单(动作名→目标)」标签，其余（含缺键 = 存量提案）返回「提案」；本函数只读，不产生任何副作用；
+def _kind_label(rec):
+    """队列条目类型标签（三档自治批次②：变更单与提案在同一队列里可分辨）。
+
+    为什么要有：设计 §四「两类条目共用一个队列，靠类型字段区分」——显示面若
+    不区分，裁决者面对一张 `[pid] pending · contextual 层` 的单子看不出它是
+    「新写入候选」还是「对既有记忆的 B/C/D 变更单」，也无从知道确认后会发生
+    什么。缺键（存量条目）一律按提案显示（零迁移）。
+    """
+    try:
+        kind = str(rec.get("kind") or "").strip()
+        slot = (rec.get("extra") or {}).get("mutation") or {}
+    except AttributeError:
+        return "提案"
+    if kind != "mutation":
+        return "提案"
+    name = slot.get("action_name") or slot.get("action") or "?"
+    tgt = slot.get("target") or rec.get("id")
+    return "变更单(%s%s)" % (name, ("→ " + str(tgt)) if tgt else "")
+
+
 # 生效条件：cg 与 args 就绪时按 args.cmd 分派——"list" 时 cg.review_list() 为空则打印空队列并返回 0、非空则逐条打印（tags 取真值拼接、layer/round 为假值显示 "?"/0）后返回 0；"rounds" 时打印 cg.review_rounds(args.pid) 并返回 0；"stats" 时打印 cg.review_stats() 的记录数/提案数/待审数/已关闭数与动作分布（含 noop 计数）并返回 0；"edit" 时以 args.content 加真值 args.tags（按逗号分割并剔除空项）/args.layer 组成 edits 调 cg.review_decide；其余 cmd（含 noop）以 getattr(args, "into", None) 与 args.reason 调 cg.review_decide；后两类再按 out.get("ok") 为真返回 0，否则打印 out 并返回 1。
 def _execute(cg, args):
     """按子命令执行裁决（cg 的生命周期由 main 统一收尾）。"""
@@ -123,8 +151,9 @@ def _execute(cg, args):
         print("待审 %d 条：" % len(pend))
         for r in pend:
             tags = (", tags=" + ",".join(r.get("tags") or [])) if r.get("tags") else ""
-            print("  [%s] %s · %s 层%s · round=%s\n      %s" % (
-                r.get("pid"), r.get("status"), r.get("layer") or "?",
+            print("  [%s] %s · %s · %s 层%s · round=%s\n      %s" % (
+                r.get("pid"), r.get("status"), _kind_label(r),
+                r.get("layer") or "?",
                 tags, r.get("round") or 0, _brief(r)))
         print('\n裁决示例：python -m md_cg.review_cli accept <pid> --reason "实跑测试证据"')
         return 0