@furongjun1999/dsh-memory 0.6.0 → 0.6.1

package/md_cg/scrub.py

@@ -715,8 +715,8 @@ def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
 # ④ 校准偏差
 # --------------------------------------------------------------------------
 
-# 生效条件：对 cg 中每个「layer 不在 SELF_LAYERS」且 evidence_count≥int(min_evidence)（min_evidence=0 时该比较恒假而不早退）的节点，若 protect.is_protected 为假或 override 为真，且 cg.get(nid) 未抛异常并返回真值节点，则取 fm.get("confidence", 0.6)（缺键才回落 0.6，键存在为 None/假值不回落）为 old，算出 round(max(0.0, min(0.99, old+float(offset))),4)，与 old 差<1e-9 时跳过，否则写 fm["confidence"] 与 fm["calibration"] 并调用 cg._write_node 成功时 adjusted+1（写回异常被吞掉不计数），返回 (adjusted, skipped)，其中 skipped 只累计「layer 属 SELF_LAYERS」或被 protect 拦下且非 override 的节点。
-def _apply_offset(cg, offset, *, override=False, min_evidence=1):
+# 生效条件：对 cg 中每个「layer 不在 SELF_LAYERS」且 evidence_count≥int(min_evidence)（min_evidence=0 时该比较恒假而不早退）的节点，若 protect.is_protected 为假或 override 为真，且 cg.get(nid) 未抛异常并返回真值节点，则先以节点真层/敏感度过 protect.guard_overwrite（层闸 + 保护闸，override 为真时先快照 + 审计，越权抛 AccessDenied 且整批中止），再取 fm.get("confidence", 0.6)（缺键才回落 0.6，键存在为 None/假值不回落）为 old，算出 round(max(0.0, min(0.99, old+float(offset))),4)，与 old 差<1e-9 时跳过，否则写 fm["confidence"] 与 fm["calibration"] 并调用 cg._write_node，成功后置 cg._dirty[nid]=e（**标脏**：推进读缓存代际与索引增量日志）并 adjusted+1（写回异常被吞掉不计数），返回 (adjusted, skipped)，其中 skipped 只累计「layer 属 SELF_LAYERS」或被 protect 拦下且非 override 的节点。
+def _apply_offset(cg, offset, *, override=False, min_evidence=1, actor=None):
     nodes = _nodes(cg)
     adjusted = skipped = 0
     for nid, e in nodes.items():
@@ -736,6 +736,20 @@ def _apply_offset(cg, offset, *, override=False, min_evidence=1):
         if not node:
             continue
         fm = node.get("frontmatter") or {}
+        # N222（2026-09-28，同族未接线写点）：本函数是 calibrate 落库动作，此前
+        # 直调 `cg._write_node` 改写**全库** `layer∉(self,anchor)` 且
+        # `evidence_count≥1` 节点的 confidence/calibration——不过 principal 层写
+        # 白名单、不过引擎级保护闸、`override` 形参直通（含 importance≥0.7 的
+        # 不可遗忘节点），无快照无审计。持 sustain 令牌（`tokens.py:190`
+        # `layers_allow=('self',)`）即可改 knowledge 层节点置信度（实测
+        # `n_adjusted=5`，0.8→0.95；`override=True` 再 +1）。落盘前统一过
+        # `protect.guard_overwrite`：层/敏感度取**节点 fm 真值**（不信索引缓存），
+        # 解析与层闸由 `protect.require_layer` 单点承担，越权即 AccessDenied
+        # 整批中止（fail-closed，不静默跳过——否则越权面被伪装成「无可校准节点」）；
+        # `override=True` 走同一闸的显式放行分支（快照 + `_protected_audit.jsonl`）。
+        protect.guard_overwrite(cg, nid, layer=fm.get("layer"),
+                                sensitivity=fm.get("sensitivity"),
+                                override=override, actor=actor)
         old = float(fm.get("confidence", 0.6))
         new = round(max(0.0, min(0.99, old + float(offset))), 4)
         if abs(new - old) < 1e-9:
@@ -746,6 +760,18 @@ def _apply_offset(cg, offset, *, override=False, min_evidence=1):
         try:
             cg._write_node(nid, os.path.join(cg.root, e["path"]), fm,
                            node.get("content") or "")
+            # 标脏（N133 修复，对照先例 md_cg/mdcg.py 的 update_tags / verify
+            # 直写分支 `self._dirty[node_id] = e`）：本函数原先写盘后**完全不
+            # 碰索引**（条目字段集不含 confidence，无需同步），但正因如此
+            # path_gen 不推进 ⇒ 读缓存（默认开）把写盘前的旧 fm 判新鲜——
+            # 同进程「calibrate 后读」拿旧 confidence（其余两处同族写点
+            # forgetting.reinforce / insight.verify 同批补标脏）。标脏同时
+            # 让本写进 `_dirty → flush → _index_log` 重放。**不下沉进
+            # `_write_node`**：该口另有「只对账索引不落盘」的调用方，下沉会
+            # 凭空产生写入代际与自重载。
+            _dirty = getattr(cg, "_dirty", None)
+            if isinstance(_dirty, dict):
+                _dirty[nid] = e
             adjusted += 1
         except Exception:                                 # noqa: BLE001
             pass
@@ -777,7 +803,8 @@ def calibrate(cg, *, apply: bool = False, override: bool = False, actor=None,
     adjusted = skipped = 0
     if apply and abs(offset) > 1e-9:
         adjusted, skipped = _apply_offset(cg, offset, override=override,
-                                          min_evidence=min_evidence)
+                                          min_evidence=min_evidence,
+                                          actor=actor)
         _log(cg, "calibrate", ok=True, offset=offset, gap=gap,
              adjusted=adjusted, actor=actor)
     blind = 0

package/md_cg/security.py

@@ -382,4 +382,50 @@ def can_read_restricted(p) -> bool:
         return False
     if getattr(p, "can_admin", False):
         return True
-    return getattr(p, "role", "") in _RESTRICTED_READER_ROLES
+    return getattr(p, "role", "") in _RESTRICTED_READER_ROLES
+
+
+# --------------------------------------------------------------------------
+# 读可见性可选钩子（跨层唯一实现，批次 68）
+# --------------------------------------------------------------------------
+# 为什么放在本模块：可见性单点 `_readable` 定义在**子类** `MdCGSecure`
+# （mdcos.py:4028），而需要它的读数出口散在**下层/旁路模块**——trust（验证态
+# 台账/describe）、provenance（派生边端点摘要与拓扑）、evolution（演化账本
+# 自由文本）、forgetting（遗忘留痕 jsonl）。这些模块若 `from .mdcos import` 会
+# 成环（mdcos 反向导入它们），故单点放在两侧都依赖的 security.py：
+#   · `visible_to(cg, entry)`   —— 条目级判定（口径 = `_readable`）；
+#   · `node_visible(cg, node_id)` —— 节点 id 级判定（索引取条目 + 缺席处置）。
+# 口径与仓内既有三处可选钩子逐条一致：`mdcos._note_visible`（及本函数的
+# 委派）、`backfill._readable_guard`、`linkref._known_ids`、`stg._scan/_preview`
+# ——「无钩子（纯 MdCGOS，无身份/密级模型）= 不限制；有钩子 = 按判据；
+# 判据异常 = 不可见（fail-closed）；宁可少读，不可 fail-open 泄漏」。
+# 生效条件：cg 有可调用的 _readable 时返回 bool(判定结果)，判定抛异常返回 False；无该属性/不可调用（纯 MdCGOS）时返回 True。
+def visible_to(cg, entry) -> bool:
+    """条目级读可见性（cg 无 `_readable` 钩子时不设限）。"""
+    fn = getattr(cg, "_readable", None)
+    if not callable(fn):
+        return True
+    try:
+        return bool(fn(entry))
+    except Exception:                          # noqa: BLE001 —— 判据异常=不可见
+        return False
+
+
+# 生效条件：cg 无可调用 _readable 时返回 True；有钩子且索引条目为 dict 时返回 bool(visible_to(cg, 条目))（判定异常 False）；索引无该条目/条目非 dict 时返回 bool(principal.can_admin)（有身份模型但不可证可见→fail-closed，设计者不受限，否则删除后的治理留痕反被清空）。
+def node_visible(cg, node_id) -> bool:
+    """节点 id 级读可见性（索引取条目；**缺席 = 不可证可见 → fail-closed**）。
+
+    缺席的两种实情：① 节点从未存在/拼错 id；② 节点已被 forget（索引无条目）。
+    有身份模型时两者都不得被「当作可见」——否则 `_forgetting.jsonl` /
+    `trust` 台账 / 派生边摘要就成了「已删内容」的旁路读出（N205/N226/N229）。
+    例外只给 can_admin（设计者=全局观测与治理本职）：否则删除后的裁决留痕
+    对唯一需要它的人也不可见（与 `_readable` 的 can_admin 豁免同款）。
+    """
+    fn = getattr(cg, "_readable", None)
+    if not callable(fn):
+        return True                            # 无身份模型：无「越权」可言
+    e = ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
+    if isinstance(e, dict):
+        return visible_to(cg, e)
+    p = getattr(cg, "principal", None)
+    return bool(p is not None and getattr(p, "can_admin", False))

package/md_cg/self_state.py

@@ -355,7 +355,7 @@ def _relation_counts(cg, subject):
     slug = _slug(subject)
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
     out = inn = 0
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tags = set(e.get("tags") or [])
         if TAG_RELATION not in tags and not nid.startswith(RELATION_PREFIX):
             continue
@@ -656,7 +656,7 @@ def relations(cg, subject=None, direction="both"):
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
     slug = _slug(subject) if subject else None
     out = []
-    for nid, e in nodes.items():
+    for nid, e in list(nodes.items()):
         tags = set(e.get("tags") or [])
         if TAG_RELATION not in tags and not nid.startswith(RELATION_PREFIX):
             continue
@@ -692,7 +692,7 @@ def index(cg, dim, value, limit=50, with_content=False):
                 "allowed": list(DIMENSIONS)}
     tag = dim_tag(d, value)
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
-    hits = [(nid, e) for nid, e in nodes.items()
+    hits = [(nid, e) for nid, e in list(nodes.items())
             if tag in (e.get("tags") or [])]
     hits.sort(key=lambda kv: (-float(kv[1].get("importance") or 0),
                               -float(kv[1].get("created_at") or 0),
@@ -740,7 +740,7 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
 
     # 1 单例：同 subject 的状态卡只能有一张
     slug = _slug(subject)
-    cards = [n for n, e in nodes.items()
+    cards = [n for n, e in list(nodes.items())
              if TAG_STATE in (e.get("tags") or [])
              and f"state_subject:{slug}" in (e.get("tags") or [])]
     if len(cards) > 1:
@@ -878,7 +878,7 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
             continue
         for v in (vals or []):
             tag = dim_tag(d, v)
-            holders = [n for n, e in nodes.items()
+            holders = [n for n, e in list(nodes.items())
                        if tag in (e.get("tags") or [])]
             if not holders:
                 issues.append(_issue("dimension_orphan", "warn",

package/md_cg/sources.py

@@ -273,8 +273,17 @@ class HiveJobsSource(Source):
       result.json 终态 → **权威确认事件**（progress 可能因强杀缺失 final）：
                           done → 「任务完成(job=…)」；error/timeout/killed → 「任务失败(job=…)」
 
-    排序：job_id 名升序 = 时间升序（job.rs 命名保证 h<unix_ms>_<pid>），
-    跨 job 全序成立；seq 由本源按枚举顺序递增（ingest 去重键 = (session, seq)）。
+    排序：**job_id 名升序**（`sorted(listdir)`，确定性），**不是**时间序——
+    契约 v2（`docs/plans/全中文编码与蜂巢任务标识契约_v2.0.md` §四.5）起 id 改为
+    语义四槽 `h_<身份>_<任务>_<单元>_<编号>`，名序不再等于提交时序：旧形态
+    `h<unix_ms>_<pid>` 才是「名序 = 时间序」的**巧合代理**。据实订正（C2：本仓
+    禁止把代理当结构保证）——本源的时序由来源行自带的 ts 承载，排序只求
+    **跨 job 全序且确定**（seq 由本源按枚举顺序递增，ingest 去重键 = (session, seq)，
+    名序的确定性保证该键跨轮稳定）。
+    诚实边界（**已发现、未在本批动码**）：本源的 `_jobs()` 若需要**真时间序**，
+    应改走与 Rust 侧同判据的 created_ts 真值（`hive/src/job.rs::list_jobs_by_created`
+    的语义，Python 侧对应 `mcp_server._list_jobs_by_created`）——契约 §四.5 的消费者
+    清单未列本源，且改动牵动 md_cg 摄入链语义与其守卫，故留待单独裁决，不静默改。
     解析失败的行/条目计入 self.skipped，不终杀批次。
     """
 
@@ -626,11 +635,14 @@ class FileDispatcher:
 
     # ---- stat：看水位与支持面 ----
 
-# 生效条件：from . import refindex 与 refindex.Ledger(self.cg.root).stat() 均不抛异常时返回该 stat 结果，抛任何异常时返回 {}。
+# 生效条件：from . import refindex 与 refindex.Ledger(self.cg.root).summary() 均不抛异常时返回该 summary 结果，抛任何异常时返回 {}。
     def _ledger_stat(self):
+        # `Ledger` 只有 `summary()`、**没有** `stat()`：此前写 `.stat()` 撞
+        # AttributeError 被下面的 except 吞成 `{}`，于是 `ingest stat` 的水位面
+        # 永远是空且无人知晓（唯一实现面是 `refindex.Ledger.summary`）。
         try:
             from . import refindex
-            return refindex.Ledger(self.cg.root).stat()
+            return refindex.Ledger(self.cg.root).summary()
         except Exception:                                  # noqa: BLE001
             return {}
 
@@ -702,7 +714,7 @@ class FileDispatcher:
                 "counts": counts,
                 "note": "预演：仅统计各链文件数，未做任何写入"}
 
-# 生效条件：root 非目录时返回 ok=False 的「目录不存在」；dry_run 为真时返回 _dry_dir(root)；否则对 doc_ref/code_ref 两链各以 patterns/max_files/max_items/incremental/ledger 调 refindex.index_dir 与 add_items，并把 root 下 **/*.jsonl 前 max_files 个逐个 ingest_jsonl 后返回 out。
+# 生效条件：root 非目录时返回 ok=False 的「目录不存在」；dry_run 为真时返回 _dry_dir(root)；否则对 doc_ref/code_ref 两链各以 patterns/max_files/max_items/incremental/ledger 调 refindex.index_dir(commit=False) 与 add_items 后 ledger.save()，并把 root 下 **/*.jsonl 前 max_files 个逐个 ingest_jsonl 后返回 out。
     def ingest_dir(self, root, layer=None, sensitivity=None, patterns=None,
                    max_files=500, max_items=2000, incremental=False,
                    dry_run=False):
@@ -716,13 +728,18 @@ class FileDispatcher:
         for ref_kind, key in (("doc_ref", "doc"), ("code_ref", "code")):
             items, errors, stats = refindex.index_dir(
                 root, kind=ref_kind, patterns=patterns, max_files=max_files,
-                max_items=max_items, incremental=incremental, ledger=ledger)
+                max_items=max_items, incremental=incremental, ledger=ledger,
+                commit=False)
             ids, sens = refindex.add_items(self.cg, items, kind=ref_kind,
                                            root=root, layer=layer,
                                            sensitivity=sensitivity)
+            # 写序（同 op=index_code/index_doc）：节点先落盘，水位随后——
+            # 中途被杀只会留下「节点新 + 水位旧」，下次增量重切，不会静默漏漂移。
+            ledger.save()
             out["chains"][key] = {
                 "indexed": len(ids), "errors": len(errors),
                 "files": stats.get("files"), "truncated": stats.get("truncated"),
+                "empty_scan": stats.get("empty_scan"),
                 "skipped_unchanged": stats.get("skipped_unchanged", 0),
                 "skipped_suffixes": stats.get("skipped_suffixes", []),
                 "sensitivity": sens}

package/md_cg/srcindex.py

@@ -0,0 +1,352 @@
+# -*- coding: utf-8 -*-
+"""md_cg · 真源索引契约层（P0）——通用层 + 细化层，零解码 / 零模型 / 零第三方依赖。
+
+设计依据：`docs/plans/真源索引_通用机制_v0.3.md`（使用者裁定 2026-09-28）。
+本模块只做**契约与纯函数**：把任意文件变成「可寻址单位」，并提供按单位回读。
+落库（写认知图 ref 节点）在 P1 接 `refindex.add_items`，本模块不写任何状态。
+
+三层（v0.3）：
+  ① **通用层**（任意文件）：条目 = {path, name, type, size, mtime, file_hash}，span=whole，
+     text_view = 文件名 + 路径 + 类型（+ 伴随文本）。类型只进检索面，**不决定能否索引**。
+  ② **细化层**（仅当真源本身可读文本）：按章节切成 line 区间单位（每单位自带区间哈希），
+     并产摘要/简介；带 `# 生效条件：` 一类 CCG 行的走既有 condition_space 同源机制。
+  ③ **伴随文本**（多模态的语义通道）：同名 sidecar / 目录说明 —— 它们**本身即真源**，
+     由调用方照常索引；本模块负责**发现并挂到通用层条目上**（`companions()`）。
+
+为什么不需要解码器与模型（v0.3 撤回项）：通用层是**整文件粒度**，不做时间点/区域切片；
+语义面走伴随文本而非模型产出。二者降级为后续可选（方案 §12）。
+
+区间单位（`unit`）本版只有两种：`whole`（整文件）与 `line`（文本行区间）。`time` / `region` /
+`byte` 三种 locator 属后续可选，**本模块显式不实现**（不静默假装支持）。
+
+生效条件：入参 path 指向常规文件（`os.path.isfile` 为真）；`units()` 对不可读/无权限文件返回
+只含通用层单位的列表（不抛），`read_unit('whole')` 一律返回原始字节。
+不适用于：无文件实体的真源（须先物化）；跨机指针（路径为绝对路径，跨机需另立锚）。
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+
+CHUNK = 1 << 20          # 文件哈希分块（大文件不整读进内存）
+SNIFF_BYTES = 4096       # 类型嗅探与「可读文本」判定取的前缀长度
+
+# 本版实现的 unit 类型；time/region/byte 属后续可选（方案 §12），此处显式声明未实现
+UNITS = ("whole", "line")
+
+TEXT_SUFFIX = {
+    ".md": "text/markdown", ".markdown": "text/markdown", ".txt": "text/plain",
+    ".json": "application/json", ".jsonl": "application/x-ndjson",
+    ".yaml": "application/yaml", ".yml": "application/yaml",
+    ".csv": "text/csv", ".tsv": "text/tab-separated-values",
+    ".py": "text/x-python", ".rs": "text/x-rust", ".ts": "text/x-typescript",
+    ".js": "text/javascript", ".sh": "text/x-shellscript", ".toml": "application/toml",
+    ".ini": "text/plain", ".cfg": "text/plain", ".log": "text/plain",
+    ".html": "text/html", ".htm": "text/html", ".xml": "text/xml",
+    ".sql": "text/x-sql", ".c": "text/x-c", ".h": "text/x-c", ".cpp": "text/x-c++",
+}
+# 魔数 → 类型（只列常见；未命中即回落扩展名 / octet-stream，绝不因未知类型拒绝入索引）
+MAGIC = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"GIF87a", "image/gif"), (b"GIF89a", "image/gif"),
+    (b"RIFF", "audio-or-video/riff"),           # 细分再看子类型（WAVE / AVI）
+    (b"ID3", "audio/mpeg"), (b"\xff\xfb", "audio/mpeg"),
+    (b"OggS", "audio-or-video/ogg"),
+    (b"fLaC", "audio/flac"),
+    (b"\x00\x00\x00\x18ftyp", "video/mp4"),
+    (b"\x1aE\xdf\xa3", "video/webm-or-matroska"),
+    (b"PK\x03\x04", "application/zip"),
+    (b"%PDF-", "application/pdf"),
+    (b"BZh", "application/x-bzip2"),
+    (b"\x1f\x8b", "application/gzip"),
+    (b"\x7fELF", "application/x-elf"),
+    (b"MZ", "application/x-dosexec"),
+)
+
+
+# 生效条件：path 为字符串且可 os.stat；返回 {path, name, dir, suffix, size, mtime, file_hash}，
+# 路径取 abspath（真源身份要跨调用稳定）；file_hash 为文件级 sha256（P0 的 staleness 判据）。
+def src_id(path: str) -> dict:
+    """真源身份：**文件名 / 路径 / 大小 / 时间 / 文件哈希**（索引的通用层主键面）。"""
+    ap = os.path.abspath(path)
+    st = os.stat(ap)
+    return {
+        "path": ap,
+        "name": os.path.basename(ap),
+        "dir": os.path.dirname(ap),
+        "suffix": os.path.splitext(ap)[1].lower(),
+        "size": st.st_size,
+        "mtime": st.st_mtime,
+        "file_hash": file_hash(ap),
+    }
+
+
+def file_hash(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            b = f.read(CHUNK)
+            if not b:
+                break
+            h.update(b)
+    return h.hexdigest()
+
+
+# 生效条件：prefix 为 bytes 时按 MAGIC 表逐条 startswith 判定，首个命中即返回其类型；
+# 未命中回落 suffix 表；仍未命中返回 "application/octet-stream"（未知类型**不是**拒绝理由）。
+def sniff_type(path: str, prefix: bytes = None) -> str:
+    """类型判据＝魔数优先、扩展名兜底（零依赖）；只用于检索面与分组，不决定可索引性。"""
+    if prefix is None:
+        try:
+            with open(path, "rb") as f:
+                prefix = f.read(SNIFF_BYTES)
+        except OSError:
+            prefix = b""
+    for magic, t in MAGIC:
+        if prefix.startswith(magic):
+            if magic == b"RIFF":
+                if prefix[8:12] == b"WAVE":
+                    return "audio/wav"
+                if prefix[8:12] == b"AVI ":
+                    return "video/x-msvideo"
+            return t
+    return TEXT_SUFFIX.get(os.path.splitext(path)[1].lower(),
+                           "application/octet-stream")
+
+
+# 生效条件：prefix 含 NUL 字节即判不可读；否则尝试 utf-8 严格解码，成功即判可读文本。
+# 语义边界：只读前缀，宁少判不多判（截断在多字节字符中间的假阴性可接受——细化层缺席不致命）。
+def is_text_readable(prefix: bytes) -> bool:
+    if b"\x00" in prefix:
+        return False
+    try:
+        prefix.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        return False
+
+
+def _read_prefix(path: str) -> bytes:
+    try:
+        with open(path, "rb") as f:
+            return f.read(SNIFF_BYTES)
+    except OSError:
+        return b""
+
+
+# 生效条件：text 与 1-based 行区间给定；返回该区间的哈希——**委托唯一实现**
+# `codeindex.region_hash`（sha1 前 12 位）。其 docstring 明写「必须是唯一定义：索引侧与回读侧
+# 共用同一个函数」，两侧各写一份就会让漂移检测悄悄失效（永远 hash_match=True）。
+# 本模块 P0 初版在此自写了 sha256 第二份，被守卫 5b/5c 当场抓出——本函数即那次修正的产物。
+def region_hash(text: str, lineno: int, end: int) -> str:
+    from . import codeindex
+    return codeindex.region_hash(text.split("\n"), lineno, end)
+
+
+# 生效条件：path 为常规文件时返回单位列表——**至少一条**通用层单位（span=whole，任意文件）；
+# 若前缀可读文本则追加细化层 line 单位（章节来自 docindex.extract，无提取器后缀则不切）。
+# 返回的每条单位形如 {src, span, span_hash, text_view, reader}；不写任何状态。
+def units(path: str, *, with_sections: bool = True) -> list[dict]:
+    """把任意文件变成可寻址单位：通用层恒在（含伴随文本挂载），细化层仅对可读文本追加。"""
+    sid = src_id(path)
+    prefix = _read_prefix(path)
+    typ = sniff_type(path, prefix)
+    sid["type"] = typ
+    out = [{
+        "src": sid,
+        "span": {"unit": "whole"},
+        "span_hash": sid["file_hash"],
+        "text_view": "文件 %s（%s）｜路径 %s" % (sid["name"], typ, sid["path"]),
+        "reader": {"kind": "whole"},
+    }]
+    # 伴随文本属**通用层**：多模态文件的语义面就靠它（P0 初版误挂在「可读文本」分支里，
+    # 而媒体根本不进那个分支 ⇒ 恰好废掉方案的 §10.3 语义通道，被守卫 6b 抓出）
+    comps = companions(sid["path"])
+    if comps:
+        out[0]["text_view"] += "｜伴随文本 " + "、".join(c["name"] for c in comps)
+        out[0]["companions"] = [c["path"] for c in comps]
+        out[0]["companion_kinds"] = sorted({c["kind"] for c in comps})
+    if not is_text_readable(prefix):
+        return out
+    try:
+        text = io.open(path, encoding="utf-8").read()
+    except (OSError, UnicodeDecodeError):
+        return out
+    if not with_sections:
+        return out
+    try:
+        from . import docindex
+        items = docindex.extract(text, path=sid["path"])
+    except Exception:  # noqa: BLE001  —— 无提取器/解析失败：停在通用层，不抛
+        return out
+    lines = text.split("\n")
+    for it in items:
+        lineno = int(it.get("lineno") or 1)
+        end = int(it.get("end") or lineno)
+        head = it.get("heading") or it.get("name") or ""
+        body = "\n".join(lines[lineno - 1:end])
+        out.append({
+            "src": sid,
+            "span": {"unit": "line", "start": lineno, "end": end,
+                     "anchor": it.get("anchor"), "level": it.get("level"),
+                     "heading_path": it.get("heading_path")},
+            # 哈希单一实现：优先用 docindex 已算的（与 region_hash 同源），缺则现算
+            "span_hash": it.get("hash") or region_hash(text, lineno, end),
+            "text_view": ("%s ｜ %s" % (sid["name"], head)).strip(),
+            "reader": {"kind": "line"},
+            # CCG 条件面：与正文同源（docindex.condition_space 解析 `# 生效条件：` 行）
+            "condition_space": (docindex.condition_space(it)
+                                if hasattr(docindex, "condition_space") else None),
+            "summary": body[:200],
+        })
+    return out
+
+
+# 生效条件：同目录下存在与媒体同主的可读文本→视为伴随文本；判定＝同 stem 且后缀属
+# 可读文本集合（.md/.txt/.json/.caption/.prompt），另加同目录 README/_index.md（目录说明）。
+# 只发现与返回路径，不索引、不改动任何文件。
+def companions(path: str) -> list[dict]:
+    """伴随文本发现（多模态的语义通道）：同名 sidecar + 目录说明。"""
+    d = os.path.dirname(os.path.abspath(path))
+    stem = os.path.splitext(os.path.basename(path))[0]
+    found = []
+    for suffix in (".md", ".txt", ".json", ".caption", ".prompt"):
+        p = os.path.join(d, stem + suffix)
+        if os.path.isfile(p) and os.path.abspath(p) != os.path.abspath(path):
+            found.append({"path": os.path.abspath(p), "name": os.path.basename(p),
+                          "kind": "sidecar"})
+    for name in ("README.md", "_index.md", "INDEX.md"):
+        p = os.path.join(d, name)
+        if os.path.isfile(p):
+            found.append({"path": os.path.abspath(p), "name": name, "kind": "dir_doc"})
+            break
+    return found
+
+
+# 生效条件：unit 含 span；unit.span.unit == "whole" 时返回原文件字节；== "line" 时按
+# src.path 读文本并返回 [start, end] 行；未知 unit 返回 ok=False 与 error（**不静默**）。
+# with_hash=True 时附带 span_hash 复核结果（回读文本重算 vs unit 内记录）。
+def read_unit(unit: dict, *, with_hash: bool = True) -> dict:
+    """按单位回读真源：通用层返回整文件字节，细化层返回行区间文本。"""
+    src = unit.get("src") or {}
+    path = src.get("path") or ""
+    span = unit.get("span") or {}
+    kind = span.get("unit")
+    if kind == "whole":
+        try:
+            with open(path, "rb") as f:
+                data = f.read()
+        except OSError as e:
+            return {"ok": False, "error": "读取失败：%s" % e}
+        out = {"ok": True, "bytes": len(data), "hash": hashlib.sha256(data).hexdigest()}
+        if with_hash:
+            out["hash_match"] = out["hash"] == unit.get("span_hash")
+        return out
+    if kind == "line":
+        try:
+            text = io.open(path, encoding="utf-8").read()
+        except (OSError, UnicodeDecodeError) as e:
+            return {"ok": False, "error": "读取失败：%s" % e}
+        a = int(span.get("start") or 1)
+        b = int(span.get("end") or 1)
+        seg = "\n".join(text.split("\n")[max(0, a - 1):max(max(0, a - 1), b)])
+        out = {"ok": True, "text": seg, "lines": b - a + 1, "hash": region_hash(text, a, b)}
+        if with_hash:
+            out["hash_match"] = out["hash"] == unit.get("span_hash")
+        return out
+    return {"ok": False,
+            "error": "未知 span.unit=%r（本版支持 %s；time/region/byte 属后续可选）"
+                     % (kind, "/".join(UNITS))}
+
+
+# ==========================================================================
+# 日志真源适配器（P1）：DSH 会话日志 → 真源身份 + 区间表
+#
+# 日志这一路与普通文件的差别只有一处（v0.3 §9 裁定①）：**真源是 zstd JSONL，
+# 可读区间却落在确定性转写上**。所以适配器把两件事分开交付——
+#   · 真源身份（`session_src_id`）：日志本体的 7 键 + 会话身份 4 键；
+#   · 区间表（`log_units`）：span 取自转写（docindex 切分），src 指向日志本体。
+# 二者都只是**把既有单点拼起来**：身份仍由 `src_id` 定、区间仍由 `docindex.extract`
+# 切、哈希仍由 `region_hash` 算。本模块不写任何状态、不 import scripts。
+# ==========================================================================
+
+#: `srcindex.session_src_id` 认的 path_mode——见函数 docstring 的暴露面说明
+SRC_PATH_MODES = ("abs", "rel", "hash")
+
+
+# 生效条件：log_path 为可 stat 的常规文件；path_mode 属 SRC_PATH_MODES（否则抛 ValueError）；
+# 返回 src_id 的 7 键 + {kind, session_uuid, workspace, sensitivity} 4 键，共 11 键。
+def session_src_id(log_path: str, *, session_uuid: str = None,
+                   workspace: str = None, sensitivity: str = "internal",
+                   path_mode: str = "abs", base: str = None) -> dict:
+    """DSH 会话日志的真源身份：`src_id` 7 键 + 会话身份 4 键（只做加法）。
+
+    `file_hash` 是 staleness 的**唯一**判据（P0 裁定），故任何降级都不得动它。
+
+    `path_mode` 是**暴露面降级开关**：src 含真源绝对路径 + 会话 uuid，而节点是
+    internal 档（跨会话共享可见，dsh_log_index.py:16-21 的共享档语义）⇒ 任何能读
+    该节点的会话都拿到本机日志绝对路径与会话 uuid。三档语义：
+      · `abs`（缺省）——绝对路径，探测能力完整；
+      · `rel`——相对 `base`（缺省取日志自身目录）且 **`dir` 一并置空**：留下绝对
+        目录等于把 rel 刚省下的又落回库里；
+      · `hash`——**path 置空**。
+    rel 与 hash 两档都不支持探测（`logref.probe_src` 返回 unresolved，属「明确
+    不探测」而非静默通过——不猜、不假装能核）；探测能力完整只有 `abs`。
+    """
+    sid = src_id(log_path)
+    ap = sid["path"]
+    if path_mode == "rel":
+        b = os.path.abspath(base) if base else os.path.dirname(ap)
+        sid["path"] = os.path.relpath(ap, b).replace("\\", "/")
+        sid["dir"] = ""
+    elif path_mode == "hash":
+        sid["path"] = ""
+        sid["dir"] = ""
+    elif path_mode != "abs":
+        raise ValueError("未知 path_mode=%r（支持 %s）"
+                         % (path_mode, "/".join(SRC_PATH_MODES)))
+    return {**sid, "kind": "dsh_session_log", "session_uuid": session_uuid,
+            "workspace": workspace, "sensitivity": sensitivity}
+
+
+# 生效条件：transcript_path 为可读 md、src 为日志真源身份（session_src_id 的产物）；
+# 返回按 docindex 章节切分的区间表，每条 {src, span(unit=line), span_hash, text_view,
+# reader, item}；`item` 是**落库口径**的原始条目（path 已按入参 path 定）。
+def log_units(transcript_path: str, src: dict, *, path: str = None) -> list[dict]:
+    """日志真源的区间表：span 落在**确定性转写**上，src 指向 zstd 日志本体。
+
+    `path` 是 docindex 的寻址键面（`path#heading_path` 里的 path，须与最终写进
+    `doc_ref.path` 的值同源），缺省回落转写的 basename——**缺省只用于单会话、
+    单转写根的临时场景**：多工作区同 sid 时会撞 id（见 `md_cg/test_logref.py`
+    的 path 口径守卫）。
+    """
+    from . import docindex          # 局部 import：与 units() 同款，避免模块级循环依赖
+    text = io.open(transcript_path, encoding="utf-8").read()
+    p = path or os.path.basename(transcript_path)
+    out = []
+    for it in docindex.extract(text, path=p):
+        lineno = int(it.get("lineno") or 1)
+        end = int(it.get("end") or lineno)
+        out.append({
+            "src": src,
+            "span": {"unit": "line", "start": lineno, "end": end,
+                     "anchor": it.get("anchor"), "level": it.get("level"),
+                     "heading_path": it.get("heading_path")},
+            "span_hash": it.get("hash") or region_hash(text, lineno, end),
+            "text_view": "%s ｜ %s" % (src.get("name") or "", it.get("heading") or ""),
+            "reader": {"kind": "line"},
+            "item": it,
+        })
+    return out
+
+
+# 生效条件：无（诊断用）；返回本模块对「通用层/细化层」的能力自陈，供文档与守卫比对。
+def capability() -> dict:
+    return {"units": list(UNITS),
+            "universal_layer": "任意常规文件（span=whole）",
+            "detail_layer": "仅可读文本（line 区间 + 摘要 + CCG 条件面）",
+            "companions": ["sidecar", "dir_doc"],
+            "not_implemented": ["time", "region", "byte"],
+            "deps": [], "writes_state": False}

package/md_cg/stg.py

@@ -210,7 +210,49 @@ def relation(cg, a_id, b_id, time_axis="observed"):
                      "space_known": ba is not None and bb is not None}}
 
 
-# 生效条件：以 _scan(cg,layer=layer,max_scan=max_scan) 为范围，session 去空白后非空且不为 "*" 时仅保留 frontmatter.session 精确相等的节点，_interval(n["frontmatter"], time_axis) 为 None 的节点被跳过，其余按 (start,end) 以 reverse=bool(desc) 排序，返回 count=全部命中数、limit=传入 limit、session=生效的会话过滤值（跨会话时为 None）、items 为排序后前 limit 项（limit=0 时为空列表）且每项附 session 归属与 _preview(cg,id)（time_axis 缺省 observed，与旧行为逐位一致；非法轴抛 ValueError）。
+# 生效条件：session 为 None 或 str(session).strip() 为空串时返回 ""（跨会话视图的内部表示，与旧实现 `"" if session is None else str(session).strip()` 逐位一致）；去空白后恰为 "*" 时返回 "*"；否则延迟导入 mcp_server._normalize_session 并返回其归一结果；该导入抛任何异常（ImportError 等）时返回去空白原值（fail-soft 退回旧行为）。
+def _view_session(session):
+    """读侧会话视图值 → 过滤值：**与写侧同一把尺**（H2，2026-09-30）。
+
+    动机（端到端实测，见 `md_cg/test_h2_session_view_norm.py`）：写侧落盘值 =
+    `_normalize_session(请求声明值)`（`MdCGSecure._attribution` 取 `cg.session`，
+    而 `cg.session` 由 `call_tool` → `_declared_session` 归一），读侧若拿
+    **未归一的原值**做等值比较，同一条记忆就「写进去查不出」——DSH 形态的
+    会话 id 在会话根下不存在时，写侧落 `anonymous`、读侧按 `session-…`
+    精确匹配 ⇒ `count=0`。
+
+    由此本函数**只归一「具体会话值」这一态**，三态语义逐位不变：
+      · None / 空串 → 跨会话（缺省不过滤，向后兼容）；
+      · `"*"`       → 跨会话（显式意图；`"*"` 不是会话名，**不归一**）；
+      · 其它值      → 过 `_normalize_session`（本会话视图与写侧同尺）。
+
+    真源只有一份（`mcp_server._normalize_session`），此处**消费而不重写**：
+    写侧读侧各写一份校验必然造出第三种不等值。延迟导入的副作用为零——正常
+    形态下 stg 本就被 mcp_server 调用（模块早已加载）；`stg` 被独立使用时导入
+    失败即 fail-soft 返回原值（退回旧行为，不报错、不改变既有语义）。
+
+    不适用条件：`cg` 侧读路径（search/recall/`cg(op=read)`）的请求 `session`
+    走 `MdCGSecure._candidates` 的**身份判定**（issue #35 定稿：身份不可自报），
+    不经本函数——那不是视图过滤，两处不得互相「对齐」。
+
+    返回值口径：None 与空串一律映射为 `""`（旧实现 `"" if session is None
+    else str(session).strip()` 的内部表示，跨会话分支判据 `sid in ("", "*")`
+    依赖它——返回 None 会让 `cross` 判假、把缺省视图变成「只看 session 为
+    空的节点」，是一处会静默清空整块自动召回的坑）。
+    """
+    if session is None:
+        return ""
+    s = str(session).strip()
+    if s in ("", "*"):
+        return s
+    try:
+        from .mcp_server import _normalize_session
+    except Exception:                          # noqa: BLE001  fail-soft：保旧行为
+        return s
+    return _normalize_session(s)
+
+
+# 生效条件：以 _scan(cg,layer=layer,max_scan=max_scan) 为范围，session 经 _view_session 归一后（None/空/"*"=跨会话不过滤，其它值=归一后的具体会话）非跨会话时仅保留 frontmatter.session 精确相等的节点，_interval(n["frontmatter"], time_axis) 为 None 的节点被跳过，其余按 (start,end) 以 reverse=bool(desc) 排序，返回 count=全部命中数、limit=传入 limit、session=生效的会话过滤值（跨会话时为 None）、items 为排序后前 limit 项（limit=0 时为空列表）且每项附 session 归属与 _preview(cg,id)（time_axis 缺省 observed，与旧行为逐位一致；非法轴抛 ValueError）。
 def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000,
              time_axis="observed", session=None):
     """按时间排序的节点列表。`time_axis` 决定排序依据的时间区间（见 `_interval`）。
@@ -220,11 +262,13 @@ def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000,
       · `"*"` → 同上语义，但把「我要看所有会话做了什么」写成**显式意图**，与
         「忘了传参」区分开，审计里也看得出这是一次跨会话读取；
       · 其它值 → 只取 `frontmatter.session` 精确相等的节点（本会话视图，
-        自动召回用它防串台）。
+        自动召回用它防串台）。**该值先过 `_view_session` 归一**（H2）——
+        写侧落盘时已过 `_normalize_session`，读侧不过同一把尺就会出现
+        「写进去查不出」；返回体 `session` 回带的是**归一后**的生效值。
     `items` 一并回带 `session`：跨会话视图下「这条是哪个会话做的」必须可辨，
     否则「能读到所有会话做了什么」只剩内容、丢了归属。
     """
-    sid = "" if session is None else str(session).strip()
+    sid = _view_session(session)
     cross = sid in ("", "*")            # 跨会话：显式 "*" 与缺省同义
     items = []
     for n in _scan(cg, layer=layer, max_scan=max_scan):