@furongjun1999/dsh-memory 0.4.4 → 0.4.6

package/md_cg/fsutil.py

@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""md 认知图 · 文件系统原语（原子写 / 跨进程锁 / append-only 日志）
+
+纯标准库（D-005）。三个原语都直接对应竞品踩过的坑：
+
+1. 原子写：临时名必须唯一。deja-vu 的 atomicfile 记录了固定临时名的后果——
+   两个写者共享同一临时文件，第二个截断第一个还在写的内容，第一个把半截文件
+   rename 到位（18049 次读里 180 次读到不可解析的记录）。
+2. Windows rename：另一个进程持有打开句柄时 os.replace 会被拒绝。deja-vu 在
+   windows CI 上实测「四个并发写者有三个被拒」，解法是短重试。
+3. 跨进程锁：threading.Lock 只管本进程；灵枢是多进程共享库，必须用 OS 级锁。
+"""
+import os
+import sys
+import time
+import uuid
+import errno
+import json
+import tempfile
+
+IS_WIN = sys.platform == "win32"
+if IS_WIN:
+    import msvcrt
+else:
+    import fcntl
+
+_RENAME_TRIES = 20
+_RENAME_WAIT = 0.005
+
+
+def _publish(tmp: str, path: str):
+    """把临时文件 rename 到位，Windows 上短重试。"""
+    for i in range(_RENAME_TRIES):
+        try:
+            os.replace(tmp, path)
+            return
+        except PermissionError:
+            if i == _RENAME_TRIES - 1:
+                raise
+            time.sleep(_RENAME_WAIT)
+
+
+def atomic_write(path: str, data: str, encoding: str = "utf-8", durable: bool = False):
+    """整文件替换。临时文件与目标同目录（保证同一文件系统，rename 才原子），
+    临时名唯一（并发写者不共享），失败即清理而不是留在可能刚写满的磁盘上。
+
+    durable=False（默认）：不做 fsync。
+      崩溃一致性由「临时文件 + rename」保证——读者要么看到旧内容、要么看到
+      新内容，永远看不到半截文件；fsync 多保证的只是"断电后新内容不丢"。
+      实测每次 fsync 让写入从 ~2000 节点/秒掉到 17 节点/秒（3048 节点迁移
+      要 3 分钟），而节点 .md 丢失的代价只是丢那一个节点，且索引可重建。
+      deja-vu 的 atomicfile 同样只做 Close + Rename，不 fsync。
+    durable=True：留给确实需要断电存活的调用方。
+    """
+    d = os.path.dirname(os.path.abspath(path)) or "."
+    os.makedirs(d, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix="." + os.path.basename(path) + ".tmp-", dir=d)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline="\n") as f:
+            f.write(data)
+            if durable:
+                f.flush()
+                os.fsync(f.fileno())
+        _publish(tmp, path)
+        tmp = None
+    finally:
+        if tmp and os.path.exists(tmp):
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+
+
+def sweep_stale_temps(d: str, older_than: float = 3600):
+    """清理被杀死的进程留下的唯一命名临时文件（它们不会被下一个写者复用清掉）。"""
+    if not os.path.isdir(d):
+        return
+    now = time.time()
+    for name in os.listdir(d):
+        if ".tmp-" not in name or not name.startswith("."):
+            continue
+        p = os.path.join(d, name)
+        try:
+            if now - os.path.getmtime(p) > older_than:
+                os.remove(p)
+        except OSError:
+            pass
+
+
+class FileLock:
+    """跨进程排它锁（OS 级）。
+
+    Windows 用 msvcrt.locking 锁首字节，Unix 用 fcntl.flock。两者语义不同
+    （前者是强制字节范围锁、后者是建议性文件锁），但对「同一把锁文件、所有
+    写者都主动获取」这个用法是等价的。
+
+    超时后放弃并放行（best-effort）：写被拒绝的代价大于一次竞态——这与
+    deja-vu 对 usage 日志锁的取舍一致（"a racing write beats a lost injection"）。
+    """
+
+    def __init__(self, path: str, timeout: float = 10.0, poll: float = 0.01):
+        self.path = path + ".lock"
+        self.timeout = timeout
+        self.poll = poll
+        self._f = None
+        self.acquired = False
+
+    def __enter__(self):
+        os.makedirs(os.path.dirname(os.path.abspath(self.path)) or ".", exist_ok=True)
+        self._f = open(self.path, "a+b")
+        deadline = time.time() + self.timeout
+        while True:
+            try:
+                if IS_WIN:
+                    self._f.seek(0)
+                    msvcrt.locking(self._f.fileno(), msvcrt.LK_NBLCK, 1)
+                else:
+                    fcntl.flock(self._f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                self.acquired = True
+                return self
+            except OSError as e:
+                if e.errno not in (errno.EACCES, errno.EAGAIN, errno.EDEADLK):
+                    raise
+                if time.time() > deadline:
+                    return self          # 放行，不阻断写路径
+                time.sleep(self.poll)
+
+    def __exit__(self, *exc):
+        try:
+            if self.acquired:
+                if IS_WIN:
+                    self._f.seek(0)
+                    msvcrt.locking(self._f.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(self._f.fileno(), fcntl.LOCK_UN)
+        except OSError:
+            pass
+        finally:
+            if self._f:
+                self._f.close()
+            self._f = None
+            self.acquired = False
+
+
+def ends_mid_line(path: str) -> bool:
+    """行式日志的最后一字节是否不是换行——即上一个写者被杀死留下的半截记录。
+    追加者若不先补一个换行，新记录会粘在这行上，两条都解析不出来。"""
+    try:
+        size = os.path.getsize(path)
+        if size == 0:
+            return False
+        with open(path, "rb") as f:
+            f.seek(size - 1)
+            return f.read(1) != b"\n"
+    except OSError:
+        return False
+
+
+def append_jsonl(path: str, record: dict):
+    """向 append-only 日志追加一条记录（best-effort 语义）。
+
+    注意 O_APPEND 的原子性是**平台相关**的：POSIX 保证「定位到末尾 + 写入」是
+    一个原子操作，Windows CRT 的 _O_APPEND 则是 lseek(END) + write 两步，并发下
+    会偶发交错丢记录（实测 6 进程 × 40 条，每轮丢 ~1 条）。
+
+    因此本函数只用于**丢一条无所谓**的簿记（访问计数）。任何不能丢的东西
+    （比如索引增量）必须用 ShardedLog——每个写者独占一个分片，不共享写入点。
+    """
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    if ends_mid_line(path):
+        line = "\n" + line
+    d = os.path.dirname(os.path.abspath(path)) or "."
+    os.makedirs(d, exist_ok=True)
+    fd = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_APPEND, 0o600)
+    try:
+        os.write(fd, line.encode("utf-8"))
+    finally:
+        os.close(fd)
+
+
+def read_jsonl(path: str):
+    """读 append-only 日志，跳过被截断/粘连的坏行（不因自身簿记而失败）。"""
+    if not os.path.exists(path):
+        return
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except ValueError:
+                continue
+
+
+class ShardedLog:
+    """每写者独占一个分片的 append-only 日志——不能丢记录时用它。
+
+    单文件 append 要靠 O_APPEND 的原子性，而那在 Windows 上不成立。分片则连
+    「共享写入点」都没有：进程 A 写 A 的文件，进程 B 写 B 的文件，物理上无从冲突。
+    代价是读取要合并 N 个分片，靠记录里的单调序号 (t, seq) 恢复全局写入顺序。
+    """
+
+    def __init__(self, directory: str):
+        self.dir = os.path.abspath(directory)
+        os.makedirs(self.dir, exist_ok=True)
+        self.path = os.path.join(
+            self.dir, f"{os.getpid()}-{uuid.uuid4().hex[:8]}.log")
+        self._seq = 0
+        self._fh = None
+
+    def append(self, record: dict):
+        self._seq += 1
+        record = dict(record, _t=time.time(), _s=self._seq)
+        if self._fh is None:
+            self._fh = open(self.path, "a", encoding="utf-8", newline="\n")
+        self._fh.write(json.dumps(record, ensure_ascii=False,
+                                  separators=(",", ":")) + "\n")
+        self._fh.flush()
+
+    def close(self):
+        if self._fh:
+            self._fh.close()
+            self._fh = None
+
+    @staticmethod
+    def read_all(directory: str):
+        """按全局写入顺序回放所有分片。"""
+        if not os.path.isdir(directory):
+            return []
+        recs = []
+        for fn in sorted(os.listdir(directory)):
+            if not fn.endswith(".log"):
+                continue
+            recs.extend(read_jsonl(os.path.join(directory, fn)))
+        recs.sort(key=lambda r: (r.get("_t", 0), r.get("_s", 0)))
+        return recs
+
+    @staticmethod
+    def clear(directory: str, keep: str = None):
+        """合并进快照后清理分片。keep 用于保留当前进程正在写的那个。"""
+        if not os.path.isdir(directory):
+            return
+        for fn in os.listdir(directory):
+            p = os.path.join(directory, fn)
+            if not fn.endswith(".log") or (keep and os.path.abspath(p) == keep):
+                continue
+            try:
+                os.remove(p)
+            except OSError:
+                pass

package/md_cg/identity.py

@@ -0,0 +1,374 @@
+# -*- coding: utf-8 -*-
+"""身份特征识别（Identity Traits）——不止「用户画像」，而是「主体身份 × 位置效应 × 条件特征」。
+
+理论出处
+--------
+· 智能论 v3.4 §十三「五大单元」·位置效应（`docs/智能的公理化基石.md:540-556`）：
+
+      单元        位置效应   核心职责
+      记录单元     全        保存观测、过程、结果和误差
+      反思单元     新        发现差异、遗漏条件和新路径
+      验证单元     稳        判断规则、执行结果和结构是否有效
+      输出单元     通        与外部系统协作并表达边界
+      维生系统     存        维护存在、预算、回滚和整体结构
+
+  「位置效应」= 主体处在系统什么位置，就承担什么职责、表现出什么特征。
+  所以「画像」不该只刻画用户，而应识别**每个主体的身份锚点 + 位置 + 特征**，
+  其中也包括智能体自身（self）。
+
+· 扮演论 v3.3（`README.md:231-271`、`docs/tool_table_v0.3.0.md:86-92`）：
+  智能即扮演；角色卡 = 条件空间声明起点；三接口 =
+      memory（历史 → 知识层）/
+      anchor（自我锚点 → SELF 层，不可遗忘）/
+      values（特化价值观 → STRUCTURE 层，带条件空间，条件空间即触发时机）。
+  边界：角色人设 ≠ 灵枢自身锚点（后者在 self 层，需设计者验证）。
+
+模型
+----
+    subject = {subject_id, kind, position, anchor, traits}
+      subject_id : "self:lingshu" / "user:alice" / "role:whale" / "agent:coder"
+      kind       : self | user | role | agent
+      position   : record | reflect | verify | output | sustain | unknown
+      anchor     : 身份锚点（不可遗忘；kind≠self 一律落 anchor 层）
+      traits     : 条件触发的特征条目（条件空间 = 触发时机，带重要度）
+
+诚实边界
+--------
+· position 是**推断**（`infer_position` 按行为证据投票），返回 confidence / votes /
+  证据数，可审计「为什么判成这个位置」，不是事实断言。
+· 平票时 position 取 `POSITION_ORDER` 中的首个并置 `tie` 字段提示歧义，不假装唯一。
+· 复用 `protect` 写保护：self/anchor 层锚点不可遗忘；
+  `role` 主体的锚点不得写入 self 层（扮演论边界）。
+"""
+
+import hashlib
+import json
+import os
+import time
+
+from .fsutil import append_jsonl
+
+# 主体类型（扮演论：self=智能体自身 / role=扮演角色 / user=协作者 / agent=其他智能体）
+SUBJECT_KIND = ("self", "user", "role", "agent")
+
+# 位置效应（智能论 v3.4 §十三 五大单元）：顺序即平票裁决优先级
+POSITIONS = {
+    "record": {"unit": "记录单元", "effect": "全",
+               "duty": "保存观测、过程、结果和误差"},
+    "reflect": {"unit": "反思单元", "effect": "新",
+                "duty": "发现差异、遗漏条件和新的路径"},
+    "verify": {"unit": "验证单元", "effect": "稳",
+                "duty": "判断规则、执行结果和结构是否有效"},
+    "output": {"unit": "输出单元", "effect": "通",
+               "duty": "与外部系统协作并表达边界"},
+    "sustain": {"unit": "维生系统", "effect": "存",
+                "duty": "维护存在、预算、回滚和整体结构"},
+}
+POSITION_ORDER = tuple(POSITIONS)
+
+# 扮演论三接口 → 落层
+INTERFACES = {
+    "memory": {"layer": "knowledge",
+               "meaning": "历史经验 / 交互证据 → 知识层"},
+    "anchor": {"layer": "self|anchor",
+               "meaning": "身份锚点 → 自我层(self) / 锚点层(其他主体)，不可遗忘"},
+    "values": {"layer": "structural",
+               "meaning": "特化特征 / 价值观 → 结构层，条件空间即触发时机"},
+}
+
+PROFILE_PREFIX = "identity_"
+AUDIT_FILE = "_identity.jsonl"
+
+TAG_ANCHOR = "identity_anchor"
+TAG_TRAIT = "identity_trait"
+TAG_OBS = "identity_observation"
+
+# 位置投票的标签证据（每条都能追溯到五大单元职责）
+_POSITION_TAGS = {
+    "reflect": {"reflect", "candidate", "hypothesis", "反题", "遗漏条件"},
+    "verify": {"verify", "verdict", "裁决", "验证"},
+    "output": {"output", "表达", "协作"},
+    "sustain": {"goal", "budget", "rollback", "health", "维生"},
+}
+
+
+def split_subject(subject_id):
+    """`"self:lingshu"` → `("self", "lingshu")`；无前缀按 `user` 处理。"""
+    s = (subject_id or "").strip()
+    if ":" in s:
+        kind, name = s.split(":", 1)
+        kind = kind.strip().lower()
+        if kind not in SUBJECT_KIND:
+            kind = "user"
+        return kind, name.strip()
+    return "user", s
+
+
+def _slug(s):
+    return "".join(ch if (ch.isalnum() or ch in "_-") else "_" for ch in str(s))
+
+
+def subject_node_id(subject_id):
+    """主体的档案节点 id（锚点载体）：`identity_<kind>_<name>`。"""
+    kind, name = split_subject(subject_id)
+    return f"{PROFILE_PREFIX}{_slug(kind)}_{_slug(name)}"
+
+
+def _nid(prefix, subject_id, seed=""):
+    h = hashlib.sha256(f"{subject_id}|{seed}|{time.time()}".encode("utf-8"))
+    return f"{PROFILE_PREFIX}{prefix}_{_slug(subject_id)}_{h.hexdigest()[:10]}"
+
+
+def log(cg, rec):
+    rec = dict(rec)
+    rec.setdefault("ts", time.time())
+    try:
+        append_jsonl(os.path.join(cg.root, AUDIT_FILE), rec)
+    except OSError:
+        pass
+
+
+def history(cg, limit=100):
+    p = os.path.join(cg.root, AUDIT_FILE)
+    out = []
+    if not os.path.exists(p):
+        return out
+    try:
+        with open(p, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    out.append(json.loads(line))
+                except ValueError:
+                    continue
+    except OSError:
+        return out
+    return out[-int(limit or 100):]
+
+
+# --------------------------------------------------------------------------
+# 扮演论三接口：memory / anchor / values
+# --------------------------------------------------------------------------
+
+def observe(cg, subject_id, text, *, kind=None, role=None, layer=None, tags=None,
+            condition_space=None, importance=0.5, verification_basis=None,
+            evidence=None, node_id=None, override=False):
+    """memory 接口：记录一条关于主体的**行为证据**（用于位置推断）。
+
+    写入知识层，自动带 `subject:<id>` 标签，使 `infer_position` 定位到该主体。
+    role 兼作来源证据：user=外部协作、command/tool-output=内部执行。
+    """
+    k, _ = split_subject(subject_id)
+    k = (kind or k).strip().lower()
+    nid = node_id or _nid("obs", subject_id, text[:32])
+    tg = list(tags or []) + [f"subject:{subject_id}", TAG_OBS, f"kind:{k}"]
+    if evidence:
+        tg.append(f"evidence:{evidence}")
+    cs = dict(condition_space or {})
+    cs.setdefault("subject", subject_id)
+    cs.setdefault("kind", k)
+    extra = {"role": role} if role else {}
+    cg.add(nid, text, layer=layer or "knowledge", tags=tg, condition_space=cs,
+           importance=importance, verification_basis=verification_basis,
+           override=override, **extra)
+    log(cg, {"op": "observe", "subject": subject_id, "node_id": nid, "role": role,
+             "layer": layer or "knowledge"})
+    return {"ok": True, "node_id": nid, "subject_id": subject_id, "kind": k}
+
+
+def set_anchor(cg, subject_id, text, *, kind=None, condition_space=None,
+               importance=0.9, override=False, requested_layer=None):
+    """anchor 接口：写入身份锚点（不可遗忘）。
+
+    落层规则（扮演论边界）：
+      · kind=self  → self 层（智能体自身的自我锚点，需设计者验证）
+      · 其他 kind  → anchor 层（角色/用户锚点，仍不可遗忘）
+    requested_layer="self" 但 kind≠self → 拒绝（角色人设 ≠ 灵枢自身锚点）。
+    """
+    k, _ = split_subject(subject_id)
+    k = (kind or k).strip().lower()
+    if k not in SUBJECT_KIND:
+        raise ValueError(f"未知主体类型：{k}（允许：{SUBJECT_KIND}）")
+    if requested_layer == "self" and k != "self":
+        raise ValueError(
+            "扮演论边界：角色/用户锚点不得写入 self 层"
+            "（self 层是灵枢自身锚点，需设计者验证）")
+    layer = "self" if k == "self" else "anchor"
+    nid = subject_node_id(subject_id)
+    cs = dict(condition_space or {})
+    cs.setdefault("subject", subject_id)
+    cs.setdefault("kind", k)
+    tg = [f"subject:{subject_id}", TAG_ANCHOR, f"kind:{k}"]
+    cg.add(nid, text, layer=layer, tags=tg, condition_space=cs,
+           importance=importance, verification_basis="data", override=override)
+    log(cg, {"op": "anchor", "subject": subject_id, "node_id": nid,
+             "kind": k, "layer": layer, "override": bool(override)})
+    return {"ok": True, "node_id": nid, "subject_id": subject_id, "kind": k,
+            "layer": layer, "protected": True}
+
+
+def add_trait(cg, subject_id, trait, *, condition_space=None, importance=0.6,
+              position=None, kind=None, verification_basis="data",
+              override=False, node_id=None):
+    """values 接口：写入条件触发的特征/特化价值观。
+
+    落 STRUCTURE 层；`condition_space` 即触发时机（扮演论：条件空间 = 触发条件）。
+    """
+    k, _ = split_subject(subject_id)
+    k = (kind or k).strip().lower()
+    nid = node_id or _nid("trait", subject_id, trait[:24])
+    cs = dict(condition_space or {})
+    cs.setdefault("subject", subject_id)
+    cs.setdefault("kind", k)
+    tg = [f"subject:{subject_id}", TAG_TRAIT, f"kind:{k}"]
+    if position:
+        tg.append(f"position:{position}")
+    cg.add(nid, trait, layer="structural", tags=tg, condition_space=cs,
+           importance=importance, verification_basis=verification_basis,
+           override=override)
+    log(cg, {"op": "trait", "subject": subject_id, "node_id": nid,
+             "position": position})
+    return {"ok": True, "node_id": nid, "subject_id": subject_id, "kind": k,
+            "layer": "structural", "condition_space": cs}
+
+
+# --------------------------------------------------------------------------
+# 位置效应推断（智能论 v3.4 §十三）
+# --------------------------------------------------------------------------
+
+def _votes(role, layer, tags, vb, ev_pos, ev_neg):
+    """把一条行为证据映射到位置效应候选（可多面）。规则可审计、可扩展。"""
+    tags = set(tags or [])
+    v = set()
+    if role in ("command", "tool-output") or layer == "contextual":
+        v.add("record")
+    for pos, marks in _POSITION_TAGS.items():
+        if tags & marks:
+            v.add(pos)
+    if ev_pos or ev_neg:
+        v.add("verify")
+    if role in ("user", "assistant") or any(
+            isinstance(t, str) and t.startswith("cap:") for t in tags):
+        v.add("output")
+    if layer == "goals":
+        v.add("sustain")
+    return v
+
+
+def infer_position(cg, subject_id):
+    """按该主体的行为证据投票推断位置效应（带 confidence / votes，可审计）。
+
+    只统计带 `subject:<id>` 标签、且**非档案节点**（锚点/特征）的证据节点，
+    避免档案自证。返回 position=unknown 表示证据不足。
+    """
+    tag = f"subject:{subject_id}"
+    nodes = cg.index.get("nodes") or {}
+    votes, n = {}, 0
+    for nid, e in nodes.items():
+        tg = set(e.get("tags") or [])
+        if tag not in tg or (tg & {TAG_ANCHOR, TAG_TRAIT}):
+            continue
+        node = cg.get(nid) or {}
+        fm = node.get("frontmatter") or {}
+        n += 1
+        for pos in _votes(fm.get("role"), e.get("layer"), e.get("tags"),
+                          e.get("verification_basis"), fm.get("positive_evidence"),
+                          fm.get("negative_evidence")):
+            votes[pos] = votes.get(pos, 0) + 1
+    if not votes:
+        return {"position": "unknown", "confidence": 0.0, "votes": {},
+                "evidence_count": n, "tie": []}
+    top = max(votes.values())
+    winners = [p for p in POSITION_ORDER if votes.get(p) == top]
+    total = sum(votes.values())
+    return {"position": winners[0], "confidence": round(top / total, 3),
+            "votes": votes, "evidence_count": n,
+            "tie": winners if len(winners) > 1 else []}
+
+
+def _position_view(pos):
+    meta = POSITIONS.get(pos) or {}
+    return {"position": pos, "unit": meta.get("unit"),
+            "effect": meta.get("effect"), "duty": meta.get("duty")}
+
+
+def profile(cg, subject_id):
+    """主体画像 = 身份锚点 + 位置效应 + 条件特征（取代单一「用户画像」）。"""
+    k, name = split_subject(subject_id)
+    tag = f"subject:{subject_id}"
+    nodes = cg.index.get("nodes") or {}
+    anchors, traits = [], []
+    for nid, e in nodes.items():
+        tg = set(e.get("tags") or [])
+        if tag not in tg:
+            continue
+        node = cg.get(nid) or {}
+        fm = node.get("frontmatter") or {}
+        if TAG_ANCHOR in tg:
+            anchors.append({"node_id": nid, "layer": e.get("layer"),
+                            "content": (node.get("content") or "")[:400]})
+        elif TAG_TRAIT in tg:
+            traits.append({"node_id": nid, "layer": e.get("layer"),
+                           "content": (node.get("content") or "")[:200],
+                           "condition_space": fm.get("condition_space"),
+                           "importance": fm.get("importance")})
+    pos = infer_position(cg, subject_id)
+    out = {"subject_id": subject_id, "kind": k, "name": name,
+           "anchor": anchors[0] if anchors else None, "anchors": anchors,
+           "traits": traits, "traits_count": len(traits)}
+    out.update(_position_view(pos["position"]))
+    out.update({"position_confidence": pos["confidence"], "votes": pos["votes"],
+                "evidence_count": pos["evidence_count"], "tie": pos["tie"]})
+    return out
+
+
+def positions(cg, limit=0):
+    """所有主体的位置效应分布（OS 视角：谁在记录/反思/验证/输出/维生）。"""
+    nodes = cg.index.get("nodes") or {}
+    counts = {}
+    for _nid_, e in nodes.items():
+        for t in (e.get("tags") or []):
+            if isinstance(t, str) and t.startswith("subject:"):
+                sid = t[len("subject:"):]
+                counts[sid] = counts.get(sid, 0) + 1
+    out = []
+    for sid, cnt in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        p = infer_position(cg, sid)
+        out.append({"subject_id": sid, "kind": split_subject(sid)[0],
+                    "nodes": cnt, "position": p["position"],
+                    "confidence": p["confidence"], "evidence_count": p["evidence_count"]})
+    return out[:int(limit)] if limit and int(limit) > 0 else out
+
+
+def _audit_count(cg):
+    p = os.path.join(cg.root, AUDIT_FILE)
+    if not os.path.exists(p):
+        return 0
+    n = 0
+    try:
+        with open(p, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    n += 1
+    except OSError:
+        return n
+    return n
+
+
+def summary(cg):
+    """身份面汇总：主体数 + 位置分布（供 health / 运维审计，流式计数不载全量）。"""
+    ps = positions(cg)
+    dist = {}
+    for s in ps:
+        dist[s["position"]] = dist.get(s["position"], 0) + 1
+    return {"subjects": len(ps), "by_position": dist,
+            "audit_records": _audit_count(cg)}
+
+
+def catalog():
+    """自描述：位置效应表 + 三接口（供 MCP / 文档对照协议验证）。"""
+    return {"positions": {p: dict(POSITIONS[p]) for p in POSITION_ORDER},
+            "interfaces": {k: dict(v) for k, v in INTERFACES.items()},
+            "kinds": list(SUBJECT_KIND)}