@furongjun1999/dsh-memory 0.7.0 → 0.7.1

package/md_cg/stg.py

@@ -11,9 +11,24 @@
     timeline(...)    按时间排序
     anchors(...)     落在给定时间窗 / 空间范围内的节点
     consistency()    时空字段自洽性检查
+
+**分层（issue #52 线）**：
+  · 第 1/2 层（已收口）：条件先于限额 + 截断可观测——`_scan` 只做「遍历 +
+    layer/可见性过滤」，条件过滤与 `_cap_hits` 截断归各接口。
+  · 第 3 层（本模块本轮）：结构索引直取（`flag MDCG_STG_INDEX`，**默认关**）——
+    条件维（session/layer/time_window）经 `md_cg/stgidx` 的三张内存倒排表直取
+    子集，**只改取数面、不改语义面**；表缺失/代际不符一律回退第 1 层全量遍历
+    并在返回体 `index` 读数里带 reason（禁止静默）。设计稿与签收记录：
+    `docs/plans/stg条件化与结构索引_设计_v0.1.md`。
+  · 条件资格首验（`flag MDCG_STG_QUALIFY`，**默认关**）：对返回条目复用 read 面
+    单点 `MdCG.judge_qualification`，结果随返回体带出（`qualification` 字段）——
+    **只上报不过滤**（契约 §3.4；硬过滤另立裁定）。
 """
 from __future__ import annotations
 
+import os
+
+from . import stgidx
 from . import trust
 
 TIME_RELATIONS = ("before", "after", "equals", "contains", "during", "overlaps")
@@ -115,45 +130,238 @@ def _node(cg, node_id):
             "content": n.get("content") or ""}
 
 
-# 生效条件：cg.index["nodes"] 存在时按 list(...items())[:max_scan] 遍历，layer 为真值时仅保留 e.get("layer")==layer 的条目（layer 为假值不筛层），e 含 "temporal" 或 "spatial" 键时直接以快照字段构造 frontmatter、否则调用 cg._read(e) 且在 fm 为 None 时跳过；返回 out 列表（max_scan=None 切片取全部，0 时为空）；
-def _scan(cg, layer=None, max_scan=5000):
+# 生效条件：nid/e 为一条快照条目、layer 为层过滤值时——layer 为真值且 e.get("layer") != layer 即返回 None；cg 带可调用的 _readable（MdCGSecure）且判不可见即返回 None；e 含 "temporal" 或 "spatial" 键时以快照字段构造 frontmatter，否则调用 cg._read(e) 且在 fm 为 None 时返回 None；返回 {"id","frontmatter","layer","path"}。
+def _scan_one(cg, nid, e, layer=None):
+    """单条目 → 候选条目（`_scan` 的逐条实现**单点**：全量遍历与索引子集共用）。
+
+    第 3 层只换「候选面怎么来」（全量快照 vs 索引子集），逐条的构造与过滤
+    一字不改地留在这一处——等价性（flag 开/关逐位一致）由构造保证，而不是
+    靠两条路径各自对齐。
+    """
+    if layer and e.get("layer") != layer:
+        return None
+    _sec = getattr(cg, "_readable", None)
+    if _sec is not None and not _sec(e):
+        return None
+    if "temporal" in e or "spatial" in e:
+        # 效力轴四键必须一并从快照带出：否则 `time_axis="effective"` 在快照
+        # 路径上永远「不可判定」（静默全空，比报错更难查）。旧索引快照无这些
+        # 键时 `.get` 得 None → 不可判定，是本轴**如实降级**而非误判。
+        fm = {"temporal": e.get("temporal"), "spatial": e.get("spatial"),
+              # 会话归属必须一并从快照带出：timeline 的会话过滤与归属回带都
+              # 走这条快照路径，缺键 → 本会话视图静默全空（比报错更难查）。
+              "session": e.get("session"),
+              trust.EFFECTIVE_FROM_FIELD: e.get(trust.EFFECTIVE_FROM_FIELD),
+              trust.EFFECTIVE_UNTIL_FIELD: e.get(trust.EFFECTIVE_UNTIL_FIELD),
+              trust.FROM_FIELD: e.get(trust.FROM_FIELD),
+              trust.UNTIL_FIELD: e.get(trust.UNTIL_FIELD),
+              "condition_space": {"time_window": e.get("time_window")}}
+    else:
+        fm, _content = cg._read(e)
+        if fm is None:
+            return None
+    return {"id": nid, "frontmatter": fm, "layer": e.get("layer"),
+            "path": e.get("path")}
+
+
+# 生效条件：nodes 为 None 时**逐条**遍历 cg.index["nodes"] 全部条目（不按索引序切片、不读正文）；nodes 为 (nid, entry) 对的序列时只遍历该序列（第 3 层索引子集，序由调用方保证=索引物理序）；两种形态都逐条经 _scan_one（layer 过滤 + 可见性 + 条目化同一单点）；返回 out 列表（全部 layer/可见性命中，**不做截断**——截断由各接口在条件过滤之后经 _cap_hits 执行，issue #52）；
+def _scan(cg, layer=None, nodes=None):
     """遍历节点：时空字段直接读索引快照（不读文件，O(1)/节点）。
 
     索引为旧快照（无 temporal/spatial 键）时回退读文件，保证兼容；
     正文一律不在此加载——预览按需读，避免全库 IO。
     授权单点（issue #35 会话隔离定稿）：cg 带 `_readable`（MdCGSecure）
     时逐条过读可见性——密级 × 会话绑定档在此与 _candidates 同口径，
-    stg 各 op（timeline/relation/anchors）不得成为绕过路径。
+    stg 各 op（timeline/relation/anchors）不得成为绕过路径。可见性判定
+    **先于一切**（含截断）：不可见节点既不进候选、也不占 kept 名额。
+
+    issue #52（条件先行于限额）：旧实现在此处 `list(index["nodes"].items())[:max_scan]`
+    ——按 id 字典序在**条件过滤之前**砍尾巴，库超 max_scan 后（a）本会话记忆等条件
+    命中若落在切片外即被永久排除（新写入节点恰在索引尾部）、（b）选面是无意义的 id
+    序、（c）截断完全静默、「读不全」与「读不到」不可区分、（d）被排除集合随索引
+    重排漂移。现改为：本函数只做「遍历 + layer/可见性过滤」，条件过滤与截断都归
+    各接口（条件先行，截断经 `_cap_hits` 只作用于条件命中集）。
+    全量快照遍历是 O(N) 内存操作（历代实测 1.7 万节点 ≈0.04s），是本修正的既定代价。
+    迭代仍取 `list(...)` 快照（H-4(a) 并发纪律：裸迭代在并写索引下会
+    RuntimeError）——去掉的只是切片，不是快照。
+
+    第 3 层（本批）：`nodes` 非 None 时只遍历**索引直取的子集**（条件维由
+    `stgidx` 三张表先收窄），逐条仍走 `_scan_one` 同一单点——取数面收窄、
+    语义面（layer/可见性/条目化）逐位不变。
     """
     out = []
-    _sec = getattr(cg, "_readable", None)
-    for nid, e in list(cg.index["nodes"].items())[:max_scan]:
-        if layer and e.get("layer") != layer:
-            continue
-        if _sec is not None and not _sec(e):
-            continue
-        if "temporal" in e or "spatial" in e:
-            # 效力轴四键必须一并从快照带出：否则 `time_axis="effective"` 在快照
-            # 路径上永远「不可判定」（静默全空，比报错更难查）。旧索引快照无这些
-            # 键时 `.get` 得 None → 不可判定，是本轴**如实降级**而非误判。
-            fm = {"temporal": e.get("temporal"), "spatial": e.get("spatial"),
-                  # 会话归属必须一并从快照带出：timeline 的会话过滤与归属回带都
-                  # 走这条快照路径，缺键 → 本会话视图静默全空（比报错更难查）。
-                  "session": e.get("session"),
-                  trust.EFFECTIVE_FROM_FIELD: e.get(trust.EFFECTIVE_FROM_FIELD),
-                  trust.EFFECTIVE_UNTIL_FIELD: e.get(trust.EFFECTIVE_UNTIL_FIELD),
-                  trust.FROM_FIELD: e.get(trust.FROM_FIELD),
-                  trust.UNTIL_FIELD: e.get(trust.UNTIL_FIELD),
-                  "condition_space": {"time_window": e.get("time_window")}}
-        else:
-            fm, _content = cg._read(e)
-            if fm is None:
-                continue
-        out.append({"id": nid, "frontmatter": fm, "layer": e.get("layer"),
-                    "path": e.get("path")})
+    if nodes is not None:
+        for nid, e in list(nodes):
+            n = _scan_one(cg, nid, e, layer)
+            if n is not None:
+                out.append(n)
+        return out
+    for nid, e in list(cg.index["nodes"].items()):
+        n = _scan_one(cg, nid, e, layer)
+        if n is not None:
+            out.append(n)
+    return out
+
+
+# 生效条件：hits 为条件命中序列、max_scan 为 None 或可 int 化的单次扫描限额（None 视同不截断）、recency_key 为把单条命中映射到「越大越近期」可比较键的可调用对象时——len(hits) <= cap（cap = max_scan 为 None 时取 len(hits)，否则 int(max_scan)，负数归 0）返回 (hits 原序, False)；超限返回 (sorted(hits, key=recency_key, reverse=True)[:cap], True)。recency_key 由各接口按自己的时间轴构造且须含 id 稳定终键（同一批键下结果与索引物理序无关）。
+def _cap_hits(hits, max_scan, recency_key):
+    """条件命中集截断（issue #52 第 1/2 层）：只作用于**条件命中集**。
+
+    调用点恒在条件过滤之后（条件先行）；不过限时不改序、不标记（逐位兼容）。
+    兜底选序＝时间倒序优先保留近期——**不是**主修法：主修法是明确检索条件
+    与建立条件索引（docs/plans/stg条件化与结构索引_设计_v0.1.md）；选序只保证
+    截断真的发生时，先抛掉的是最久远/最不可判定者，而不是索引尾部。
+    """
+    n = len(hits)
+    cap = n if max_scan is None else int(max_scan)
+    if cap < 0:
+        cap = 0
+    if n <= cap:
+        return hits, False
+    return sorted(hits, key=recency_key, reverse=True)[:cap], True
+
+
+# 生效条件：h 为 timeline 命中元组 (start, end, id, layer, session)；返回 (start, end, id)——「越大越近期」，id 终键保证与索引物理序无关。
+def _tl_recent(h):
+    return (h[0], h[1], h[2])
+
+
+# 生效条件：h 为 anchors 命中 dict（含 "time" 区间或 None）时返回 (时间可判定否, start, end, id)——时间不可判定者键最小（倒序保留时最先被截），id 终键保证与索引物理序无关。
+def _an_recent(h):
+    iv = h.get("time")
+    if iv is None:
+        return (False, 0.0, 0.0, str(h.get("id")))
+    return (True, iv[0], iv[1], str(h.get("id")))
+
+
+# 生效条件：n 为 _scan 条目、time_axis 为时间轴名时返回 (时间可判定否, start, end, id)（口径同 _an_recent，区间按 time_axis 轴经 _interval 取；非法轴由 _interval 抛 ValueError，不吞错）。
+def _co_recent(n, time_axis):
+    iv = _interval(n["frontmatter"], time_axis)
+    if iv is None:
+        return (False, 0.0, 0.0, str(n["id"]))
+    return (True, iv[0], iv[1], str(n["id"]))
+
+
+# 截断可操作提示（issue #52 第 2 层：禁止静默）——文案必须含「细化生效条件/不适用条件」与「建立条件索引」语义；数值放大（调 max_scan）不是修法，故明文劝阻。
+_CAP_HINT = ("条件命中 %s 条超过单次扫描限额 max_scan=%s，已按时间倒序保留近期 %s 条"
+             "（截断不静默）：请细化生效条件/不适用条件（如 session/layer/time_window）"
+             "收窄命中集，或按设计稿建立条件索引（docs/plans/stg条件化与结构索引_设计_v0.1.md）"
+             "——不要调大 max_scan 数值。")
+
+
+# 生效条件：out 为接口返回体（dict）、scanned 为候选遍历数（layer/可见性过滤后、截断前）、hits 为条件命中总数（截断前）、kept 为截断后保留数、truncated 为其布尔标记、max_scan 为本次限额——恒把 scanned/kept/truncated 三键并入 out；truncated 为真时再并入 hint（_CAP_HINT 插值 hits/max_scan/kept）；index_meta 非 None 时把其并入 out["index"]（第 3 层读数；**flag 关时为 None、不落键**——关臂返回体与第 1/2 层逐位一致）；返回 out。
+def _with_scan_reads(out, *, scanned, hits, kept, truncated, max_scan,
+                     index_meta=None):
+    """读数与截断标记的统一出口（timeline/anchors/consistency 同一口径）。"""
+    out.update({"scanned": scanned, "kept": kept, "truncated": truncated})
+    if truncated:
+        out["hint"] = _CAP_HINT % (hits, max_scan, kept)
+    if index_meta is not None:
+        out["index"] = index_meta
     return out
 
 
+# ---------------------------------------------------------------------------
+# 第 3 层：结构索引（flag MDCG_STG_INDEX，默认关）——只改取数面
+# ---------------------------------------------------------------------------
+
+#: 条件索引开关（契约 §4：先 flag 化、逐项验证、再讨论默认开启）。
+_INDEX_ENV = "MDCG_STG_INDEX"
+#: 条件资格首验开关（只上报不过滤）。
+_QUALIFY_ENV = "MDCG_STG_QUALIFY"
+
+
+# 生效条件：环境变量 name 取值属 ("1","true","True") 时返回 True，其余（含未设/其它值）返回 False——默认关的开关一律走本判据（与 MDCG_LEGACY_ENV_AUTH 同形）。
+def _flag_on(name):
+    return os.environ.get(name) in ("1", "true", "True")
+
+
+# 生效条件：cg._stg_index 为已构建的 StgIndex 且其 index_obj is cg.index、not broken、len(pos) == len(cg.index["nodes"]) 时返回 (bundle, None)；否则返回 (None, reason)——reason ∈ tables_missing（快照不可用/构建失败）/generation_mismatch（表绑的是**另一份**快照：陈旧表当场丢弃，下次访问按新快照重建）/table_snapshot_mismatch（表与快照键数不等：同上丢弃）；未构建时按 cg.index 惰性构建一次并挂回 cg._stg_index（首次 stg 需要时构建，写路径零成本）。
+def _index_bundle(cg):
+    """取（或首次构建）结构索引；任何不可用情形都带 reason 返回，**恒不静默**。"""
+    ix = getattr(cg, "_stg_index", None)
+    nodes = (getattr(cg, "index", None) or {}).get("nodes")
+    if not isinstance(nodes, dict):
+        return None, "tables_missing"
+    if ix is not None:
+        if getattr(ix, "index_obj", None) is not cg.index:
+            # 代际不符（整体换过快照却没走失效点）：本次**回退**第 1 层并在
+            # meta 上报；陈旧表当场丢弃 ⇒ 下次访问按新快照重建（自愈）。
+            cg._stg_index = None
+            return None, "generation_mismatch"
+        if ix.broken or len(ix.pos) != len(nodes):
+            cg._stg_index = None
+            return None, "table_snapshot_mismatch"
+        return ix, None
+    try:
+        ix = stgidx.build(cg.index)
+    except Exception:                        # noqa: BLE001  构建失败即回退
+        return None, "build_failed"
+    if ix is None:
+        return None, "tables_missing"
+    cg._stg_index = ix
+    return ix, None
+
+
+# 生效条件：ix 为已校验的 StgIndex、served 为其实际服务的维名元组、full 为快照节点总数——恒返回 meta dict（path=index、index_hit=len(served)、index_miss=0、fallback=None、size=表规模、full_nodes=full）。
+def _index_meta_hit(ix, served, full):
+    return {"enabled": True, "path": "index", "index_hit": len(served),
+            "index_miss": 0, "fallback": None, "full_nodes": full,
+            "size": ix.size()}
+
+
+# 生效条件：reason 为非空回退原因字符串、want 为本次查询**想要**索引服务的维数、full 为快照节点总数（未知时 None）、ix 为可用/不可用的 StgIndex（未知时 None）——恒返回 meta dict（path=full、index_hit=0、index_miss=want、fallback=reason、size=表规模或 None、full_nodes=full）。
+def _index_meta_full(reason, want, full, ix=None):
+    return {"enabled": True, "path": "full", "index_hit": 0,
+            "index_miss": want, "fallback": reason, "full_nodes": full,
+            "size": ix.size() if ix is not None else None}
+
+
+# 生效条件：session/layer 为维值或 stgidx.MISSING（**MISSING 表示该维不参与；None 是合法维值**=unassigned 桶）、time_range 为 (lo,hi) 或 None、blocked 为「有条件下但该维不可索引」时的回退原因（无则 None）；flag 关闭时返回 (None, None)（关臂不落 index 键、不碰索引）；否则按 表缺失/代际不符/表-快照不符/迭代期旧快照条目/无条件维 逐一回退并回报 reason，可服务时返回 (pairs（索引物理序的 (nid, entry) 序列）, meta(path=index))。
+def _index_pairs(cg, *, session=stgidx.MISSING, layer=stgidx.MISSING,
+                 time_range=None, blocked=None):
+    """条件维 → 索引子集；返回 (pairs | None, meta | None)。
+
+    **回退即回报**（契约：表缺失/代际不符 ⇒ 回退第 1 层全量遍历，安全降级且
+    可观测，禁止静默）：本函数返回 None 的每一条路径都带非空 reason。
+    """
+    if not _flag_on(_INDEX_ENV):
+        return None, None
+    want = ((session is not stgidx.MISSING) + (layer is not stgidx.MISSING)
+            + (time_range is not None) + (1 if blocked else 0))
+    nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
+    full = len(nodes)
+    ix, reason = _index_bundle(cg)
+    if ix is None:
+        return None, _index_meta_full(reason, want, full)
+    ids, served = ix.subset(session=session, layer=layer,
+                            time_range=time_range)
+    if not served:
+        return None, _index_meta_full(blocked or "no_condition_dimension",
+                                      want, full, ix)
+    if len(ids) >= full:
+        # 子集 == 全量：索引**未收窄**任何面（如层条件恰好覆盖全库）——走索引臂
+        # 只会多付一次候选拷贝与逐条取件（5320 节点实测约 +20%），不如直接走
+        # 第 1 层全量（设计稿 §3.1「触碰数降到子集」的诚实版：没收窄就别绕）。
+        return None, _index_meta_full("no_convergence", want, full, ix)
+    pairs = []
+    for nid in ids:
+        e = nodes.get(nid)
+        if e is None:
+            # 表里有 id、快照里没有（长度校验放行不了的残余不一致）：
+            # 宁慢不丢召回——整查询回退，并丢表待重建。
+            cg._stg_index = None
+            return None, _index_meta_full("table_snapshot_mismatch", want,
+                                          full)
+        if "temporal" not in e and "spatial" not in e:
+            # 迭代期旧快照条目：`_scan` 会**读文件**取 fm，该节点的 session/
+            # layer/时间口径来自盘面而非条目——条目键的分类不保证与之一致
+            # （会话视图下会漏召回）。故整查询回退（宁慢不丢召回，可观测）。
+            return None, _index_meta_full("entry_file_read", want, full, ix)
+        pairs.append((nid, e))
+    return pairs, _index_meta_hit(ix, served, full)
+
+
 # 生效条件：cg.index["nodes"].get(node_id) 缺失或为假值时返回 ""；否则 cg._readable 可调用且对其返回假值或抛异常时返回 PLACEHOLDER_DENIED；cg._read(e) 的 frontmatter 为 None 时返回 ""；content 非密文时返回 content[:n]（n 默认 200）；content 为密文时，cg._open_content 可调用且取到非 None 且非密文的 opened 才返回 opened[:n]，opened 为 None、抛异常或仍为密文时返回 PLACEHOLDER_LOCKED。
 def _preview(cg, node_id, n=200):
     """按需读单个节点正文做预览（只发生在最终返回的条目上）。
@@ -193,6 +401,69 @@ def _preview(cg, node_id, n=200):
     return opened[:n]
 
 
+# 生效条件：cg 有 index["nodes"][node_id] 且（cg._readable 可调用时）该条目过可见性判定、cg._read 取回 fm 非 None 时返回 {"frontmatter": fm, "content": content}——content 为密文且 cg._open_content 可解出非密文时才用解出的明文，仍为密文/解不开亦返回 None；条目不存在、被读隔离拦下、fm 取不回一律返回 None（**拿不到可判定的正文就不做判定**，不猜测）。
+def _qual_node_dict(cg, node_id):
+    """资格判定的 node_dict——取件与脱敏口径与 `_preview` **同一份**（判定不越权）。
+
+    密文不可解 ⇒ 返回 None ⇒ 该条不附 qualification：**不伪造状态**（若照密文
+    判 CCG 完整性，会把「无密钥」误报成「要素不全」，那是拿不到证据时的假话）。
+    """
+    from . import crypto
+    e = cg.index["nodes"].get(node_id)
+    if not e:
+        return None
+    guard = getattr(cg, "_readable", None)
+    if callable(guard):
+        try:
+            if not guard(e):
+                return None
+        except Exception:                      # noqa: BLE001
+            return None
+    fm, content = cg._read(e)
+    if fm is None:
+        return None
+    content = content or ""
+    if crypto.is_encrypted(content):
+        opener = getattr(cg, "_open_content", None)
+        opened = None
+        if callable(opener):
+            try:
+                opened = opener(node_id, fm, content)
+            except Exception:                  # noqa: BLE001
+                opened = None
+        if opened is None or crypto.is_encrypted(opened):
+            return None
+        content = opened
+    return {"frontmatter": fm, "content": content}
+
+
+# 生效条件：items 为接口最终返回条目序列、context 为情境 dict、query 为情境问句（stg 无自由问句，恒传入 ""）时——_QUALIFY_ENV 未启用或 items 为空即原样返回 items；启用时逐条取 _qual_node_dict（None 即该条**不附** qualification，不伪造状态），取到则调 read 面单点 MdCG.judge_qualification(node_dict, query, context) 并把其返回原样挂到 entry["qualification"]（判定抛异常该条亦不附）；返回 items。**只上报不过滤**：不动成员、不动次序、不动截断面。
+def _attach_qualification(cg, items, context, query=""):
+    """条件资格首验（设计稿 §3.4，`MDCG_STG_QUALIFY=1` 显式开）。
+
+    语义与 read 面**同口径**：直接复用 `MdCG.judge_qualification` 单点，本模块
+    不另写一份资格判据（契约 §五：不引入第二套条件解析）。stg 无自由问句，
+    情境取自**本次 stg 调用自身的条件面**（op/session/layer/time_window/bbox/
+    time_axis），故 query 恒为 ""。
+
+    契约红线：**只上报不过滤**——硬过滤（与 read 面同权）另立裁定；本函数的
+    调用点在各接口返回体成型**之后**，任何筛选/截断都不经过它。
+    """
+    if not items or not _flag_on(_QUALIFY_ENV):
+        return items
+    from .mdcg import MdCG
+    for it in items:
+        nid = it.get("id")
+        nd = _qual_node_dict(cg, nid) if nid else None
+        if nd is None:
+            continue
+        try:
+            it["qualification"] = MdCG.judge_qualification(nd, query, context)
+        except Exception:                      # noqa: BLE001  判定异常不伪状态
+            continue
+    return items
+
+
 # 生效条件：cg 上 _node(cg, a_id) 与 _node(cg, b_id) 均返回真值时返回含 a_id/b_id、时间关系、空间关系和 time_known/space_known 的 dict（两侧时间区间均按 time_axis 轴取，见 _interval；time_axis 非法经 trust.time_axis_of 抛 ValueError）；任一 _node 结果为假值时返回 {"error":"node_not_found","missing":[...]}；
 def relation(cg, a_id, b_id, time_axis="observed"):
     """两节点间的时空关系（a 相对 b）。`time_axis` 决定时间区间取哪条轴（见 `_interval`）。"""
@@ -252,7 +523,7 @@ def _view_session(session):
     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）。
+# 生效条件：以 _scan(cg,layer=layer) 为候选（全部 layer/可见性命中），session 经 _view_session 归一后（None/空/"*"=跨会话不过滤，其它值=归一后的具体会话）非跨会话时仅保留 frontmatter.session 精确相等的节点，_interval(n["frontmatter"], time_axis) 为 None 的节点被跳过——**条件命中集到此确定**；随后才截断：命中集超过 max_scan（默认 5000 不变）时按 (start,end,id) 时间倒序保留近期 max_scan 条并标记 truncated；保留集按 (start,end,id) 以 reverse=bool(desc) 排序，返回 count=条件命中总数（截断前，**不再受索引切片影响**）、limit=传入 limit、session=生效的会话过滤值（跨会话时为 None）、scanned=候选遍历数、kept=截断后保留数、truncated=截断标记（截断时另有 hint）、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`）。
@@ -267,11 +538,24 @@ def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000,
         「写进去查不出」；返回体 `session` 回带的是**归一后**的生效值。
     `items` 一并回带 `session`：跨会话视图下「这条是哪个会话做的」必须可辨，
     否则「能读到所有会话做了什么」只剩内容、丢了归属。
+
+    issue #52（条件先行 + 截断可观测）：`max_scan`（默认 5000，数值不变）
+    **只在条件命中集上生效**——旧实现把它当索引序切片（在 session/时间条件
+    过滤**之前**砍尾巴），本会话记忆因落在切片外而整片消失且没有任何标记；
+    现在 `count` 恒为条件命中总数（不受切片影响），命中集超限才按时间倒序
+    保留近期，并在返回体上报 `truncated`/`scanned`/`kept`/`hint`。
     """
     sid = _view_session(session)
     cross = sid in ("", "*")            # 跨会话：显式 "*" 与缺省同义
+    # 第 3 层：会话/层两维由结构索引直取（跨会话视图下会话维不参与——它本就
+    # 「不过滤」；具体会话值走 by_session[归一后 sid]，与基线等值比较同一把尺）。
+    pairs, imeta = _index_pairs(
+        cg, session=stgidx.MISSING if cross else sid,
+        layer=layer if layer else stgidx.MISSING)
+    scanned = 0
     items = []
-    for n in _scan(cg, layer=layer, max_scan=max_scan):
+    for n in _scan(cg, layer=layer, nodes=pairs):
+        scanned += 1
         fm = n["frontmatter"] or {}
         if not cross and fm.get("session") != sid:
             continue
@@ -279,18 +563,34 @@ def timeline(cg, layer=None, limit=50, desc=True, max_scan=5000,
         if iv is None:
             continue
         items.append((iv[0], iv[1], n["id"], n["layer"], fm.get("session")))
+    hits = len(items)                    # 条件命中总数（截断前，count 的口径）
+    items, truncated = _cap_hits(items, max_scan, _tl_recent)
+    kept = len(items)
     items.sort(key=lambda x: (x[0], x[1], x[2]), reverse=bool(desc))
-    return {"count": len(items), "limit": limit,
-            "session": None if cross else sid,
-            "items": [{"id": i, "layer": l, "start": s, "end": e,
-                       "session": sn, "preview": _preview(cg, i)}
-                      for s, e, i, l, sn in items[:limit]]}
-
-
-# 生效条件：time_window 为长度 2 的 list/tuple 时 q_t=(float(time_window[0]),float(time_window[1]))（元素不可转 float 会直接抛异常，源码未捕获），bbox 为长度 4 的 list/tuple 时同理构造 q_b；q_t 与 q_b 均为 None 时返回 {"error":"need_time_window_or_bbox"}；否则扫描节点、每节点时间区间按 _interval(fm, time_axis) 取（time_axis 缺省 observed 与旧行为逐位一致，非法轴抛 ValueError），并要求时间关系在 during/contains/overlaps/equals、空间关系在 inside/contains/overlaps/equals（提供查询侧才检查），返回 hits[:limit]（limit=None 取全部，0/False 取空）；
+    out_items = _attach_qualification(
+        cg, [{"id": i, "layer": l, "start": s, "end": e,
+              "session": sn, "preview": _preview(cg, i)}
+             for s, e, i, l, sn in items[:limit]],
+        {"stg": "timeline", "session": None if cross else sid,
+         "layer": layer, "time_axis": time_axis})
+    return _with_scan_reads(
+        {"count": hits, "limit": limit,
+         "session": None if cross else sid, "items": out_items},
+        scanned=scanned, hits=hits, kept=kept, truncated=truncated,
+        max_scan=max_scan, index_meta=imeta)
+
+
+# 生效条件：time_window 为长度 2 的 list/tuple 时 q_t=(float(time_window[0]),float(time_window[1]))（元素不可转 float 会直接抛异常，源码未捕获），bbox 为长度 4 的 list/tuple 时同理构造 q_b；q_t 与 q_b 均为 None 时返回 {"error":"need_time_window_or_bbox"}；否则以 _scan(cg,layer=layer) 为候选逐节点取 _interval(fm, time_axis)（time_axis 缺省 observed 与旧行为逐位一致，非法轴抛 ValueError）与 _bbox，要求时间关系在 during/contains/overlaps/equals、空间关系在 inside/contains/overlaps/equals（提供查询侧才检查）——**条件命中集到此确定**；随后才截断：命中集超过 max_scan（默认 5000 不变）时按 (时间可判定否,start,end,id) 倒序保留近期 max_scan 条并标记 truncated（无时间区间者最先被截）；返回 count=条件命中总数（截断前）、query、scanned=候选遍历数、kept=截断后保留数、truncated=截断标记（截断时另有 hint）、items=hits[:limit]（limit=None 取全部，0/False 取空）且每条附 preview；
 def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000,
             time_axis="observed"):
-    """落在给定时间窗 / 空间范围内的节点。`time_axis` 决定候选时间区间（见 `_interval`）。"""
+    """落在给定时间窗 / 空间范围内的节点。`time_axis` 决定候选时间区间（见 `_interval`）。
+
+    issue #52（条件先行 + 截断可观测）：时间窗/空间范围的条件命中集先于
+    `max_scan`（默认 5000，数值不变）确定——`count` 恒为条件命中总数，
+    命中集超限才按时间倒序保留近期（无时间区间者先被截），并上报
+    `truncated`/`scanned`/`kept`/`hint`；旧实现按索引序切片在条件**之前**，
+    命中项落在切片外即静默消失。
+    """
     q_t = None
     if isinstance(time_window, (list, tuple)) and len(time_window) == 2:
         q_t = (float(time_window[0]), float(time_window[1]))
@@ -300,8 +600,32 @@ def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000
     if q_t is None and q_b is None:
         return {"error": "need_time_window_or_bbox"}
 
+    # 第 3 层：时间维经 by_time 区间直取（层维同 timeline）。三条回退条件都在
+    # 索引面**如实上报**（禁止静默）：
+    #   · 非观察轴（effective 等）：表按观察轴建，换轴即无法预筛 ⇒ 不索引该维；
+    #   · 倒置查询窗（qs > qe）：`equals` 命中可要求 a1 = qs > qe，「t ≤ qe」的
+    #     预筛会漏 ⇒ 不索引该维（宁慢不丢召回）；
+    #   · 非法轴：不索引 ⇒ 回退后由 `_interval` 在**与基线同一处**抛 ValueError。
+    time_range, blocked = None, None
+    if q_t is not None:
+        try:
+            _observed = trust.time_axis_of(time_axis) == "observed"
+        except ValueError:
+            _observed = False
+        if not _observed:
+            blocked = "time_axis_not_indexed"
+        elif q_t[0] <= q_t[1]:
+            time_range = (q_t[0], q_t[1])
+        else:
+            blocked = "inverted_query_window"
+    pairs, imeta = _index_pairs(
+        cg, layer=layer if layer else stgidx.MISSING,
+        time_range=time_range, blocked=blocked)
+
+    scanned = 0
     hits = []
-    for n in _scan(cg, layer=layer, max_scan=max_scan):
+    for n in _scan(cg, layer=layer, nodes=pairs):
+        scanned += 1
         fm = n["frontmatter"]
         iv, bb = _interval(fm, time_axis), _bbox(fm)
         t_rel = time_relation(iv, q_t) if (q_t and iv) else None
@@ -312,13 +636,24 @@ def anchors(cg, time_window=None, bbox=None, layer=None, limit=50, max_scan=5000
             continue
         hits.append({"id": n["id"], "layer": n["layer"], "time": iv, "bbox": bb,
                      "time_relation": t_rel, "space_relation": s_rel})
+    total = len(hits)                    # 条件命中总数（截断前，count 的口径）
+    hits, truncated = _cap_hits(hits, max_scan, _an_recent)
+    kept = len(hits)
     for h in hits[:limit]:
         h["preview"] = _preview(cg, h["id"])
-    return {"count": len(hits), "query": {"time_window": q_t, "bbox": q_b},
-            "items": hits[:limit]}
-
-
-# 生效条件：遍历 _scan(cg,layer=layer,max_scan=max_scan) 每条 frontmatter，bb 非 None 且不满足 bb[0]<=bb[2] and bb[1]<=bb[3] 记 invalid_bbox、iv（由 _interval(fm, time_axis) 取，time_axis 缺省 observed 与旧行为逐位一致、非法轴抛 ValueError）非 None 且 iv[0]>iv[1] 记 inverted_time_window、temporal 与 time_window 均经 trust.epoch_seconds 归一后可比且不满足 tw[0]<=t<=tw[1] 记 temporal_outside_window（该检查恒按观察轴内部口径、不随 time_axis 漂移；任一端不可转数值则忽略），返回 scanned 计数、issues 总数与 issues[:limit]（limit 默认 50）。
+    _attach_qualification(
+        cg, hits[:limit],
+        {"stg": "anchors", "time_window": list(q_t) if q_t else None,
+         "bbox": list(q_b) if q_b else None, "layer": layer,
+         "time_axis": time_axis})
+    return _with_scan_reads(
+        {"count": total, "query": {"time_window": q_t, "bbox": q_b},
+         "items": hits[:limit]},
+        scanned=scanned, hits=total, kept=kept, truncated=truncated,
+        max_scan=max_scan, index_meta=imeta)
+
+
+# 生效条件：以 cand=list(_scan(cg,layer=layer)) 为候选（scanned=len(cand) 为遍历读数，layer/可见性即其条件面），**先**按 (时间可判定否,start,end,id) 时间倒序截断到 max_scan（默认 5000 不变，截断时 kept=保留数、truncated=True 并附 hint）——随后逐条检查：bb 非 None 且不满足 bb[0]<=bb[2] and bb[1]<=bb[3] 记 invalid_bbox、iv（由 _interval(fm, time_axis) 取，time_axis 缺省 observed 与旧行为逐位一致、非法轴抛 ValueError）非 None 且 iv[0]>iv[1] 记 inverted_time_window、temporal 与 time_window 均经 trust.epoch_seconds 归一后可比且不满足 tw[0]<=t<=tw[1] 记 temporal_outside_window（该检查恒按观察轴内部口径、不随 time_axis 漂移；任一端不可转数值则忽略）；返回 issues 总数与 issues[:limit]（limit 默认 50）、scanned=遍历读数、kept=实际检查节点数、truncated=截断标记（截断时另有 hint）。
 def consistency(cg, layer=None, limit=50, max_scan=5000, time_axis="observed"):
     """时空字段自洽性检查：非法 bbox / 时间倒置 / 窗口与时刻冲突。
 
@@ -329,11 +664,21 @@ def consistency(cg, layer=None, limit=50, max_scan=5000, time_axis="observed"):
     两端比较前统一经 `trust.epoch_seconds` 归一：旧实现裸 `float` 比较，历史毫秒
     节点的 `1.7e12` 与秒级 `temporal` 永不落入区间 → 该检查在真实库中**静默失效**
     （issue #23 同根因）。返回体的 `temporal` / `time_window` 也随之为归一后的秒值。
+
+    issue #52（条件先行 + 截断可观测）：候选/条件命中集（layer × 可见性）
+    **先于** `max_scan`（默认 5000，数值不变）确定；超限时按时间倒序保留近期
+    再检查——`kept` 为实际检查数、`truncated` 显式上报（旧实现按索引序切片
+    且无任何标记，「读不全」与「读不到」不可区分）。
     """
+    # 第 3 层：候选/条件面就是「层 × 可见性」，层维由 by_layer 直取（层缺省时
+    # 无维可索引 ⇒ 回退全量并上报 no_condition_dimension）。
+    pairs, imeta = _index_pairs(cg, layer=layer if layer else stgidx.MISSING)
+    cand = list(_scan(cg, layer=layer, nodes=pairs))
+    scanned = len(cand)
+    cand, truncated = _cap_hits(cand, max_scan, lambda n: _co_recent(n, time_axis))
+    kept = len(cand)
     issues = []
-    scanned = 0
-    for n in _scan(cg, layer=layer, max_scan=max_scan):
-        scanned += 1
+    for n in cand:
         fm = n["frontmatter"]
         bb, iv = _bbox(fm), _interval(fm, time_axis)
         if bb and not (bb[0] <= bb[2] and bb[1] <= bb[3]):
@@ -348,5 +693,10 @@ def consistency(cg, layer=None, limit=50, max_scan=5000, time_axis="observed"):
             if lo is not None and hi is not None and not (lo <= t <= hi):
                 issues.append({"id": n["id"], "issue": "temporal_outside_window",
                                "temporal": t, "time_window": [lo, hi]})
-    return {"scanned": scanned, "issues": len(issues), "limit": limit,
-            "items": issues[:limit]}
+    _attach_qualification(
+        cg, issues[:limit],
+        {"stg": "consistency", "layer": layer, "time_axis": time_axis})
+    return _with_scan_reads(
+        {"issues": len(issues), "limit": limit, "items": issues[:limit]},
+        scanned=scanned, hits=scanned, kept=kept, truncated=truncated,
+        max_scan=max_scan, index_meta=imeta)