@modusensus/dsh-mneme 0.12.0 → 0.14.0-beta.1

package/lib/store.js

@@ -249,6 +249,36 @@ CREATE TABLE IF NOT EXISTS conflict_reviewed (
 );
 CREATE INDEX IF NOT EXISTS idx_conflict_reviewed_judged ON conflict_reviewed(judged_at);
 
+-- conflict_ledger: 冲突分诊账本（issue #641 beta 第一阶段，shadow 档）。conflict
+-- 相位的每一对候选在送进 freeze/LLM 之前先过确定性分诊（dup / cross-scope-dup /
+-- evolution / conflict，判据唯一实现见 src/dream/triage.js），分档结果落在这里。
+-- shadow 档只记账不改任何行为——它存在的目的就是让「分诊分布是否复现真实库的
+-- 46/20/5/27」这件事在真实运行里可测，切 enforce 前先有一周的真实分布可对。
+--
+-- 为什么不复用 conflict_reviewed：那张表的语义是「这一对被机器**裁决**过」，键的
+-- 消费方（alreadyJudged 预筛）拿它挡重送；本表语义是「这一对被分诊**观察**过」，
+-- 挡重送反而错误——同一对每轮都要重新观察（两侧内容变了 tier 可能变），它不是
+-- 处置记录，是测量记录。也不复用 conflict_pending（人工队列，见上表注释）。
+--
+-- 主键归一化后的对，与 conflict_reviewed 同一口径；ON CONFLICT 只刷新 tier/
+-- signals/last_*，first_seen_at/first_run_id 保留首次检出时刻——同召率与「挂账
+-- 时长」这类惰性消解指标都以此为准。status 是 enforce 阶段消解落账的方向
+-- （open → superseded / differentiated / zombied），shadow 期恒为 open。
+CREATE TABLE IF NOT EXISTS conflict_ledger (
+  memory_a      TEXT NOT NULL,
+  memory_b      TEXT NOT NULL,
+  tier          TEXT NOT NULL,          -- dup | cross-scope-dup | evolution | conflict
+  similarity    REAL,
+  signals       TEXT,                   -- JSON: 分诊依据（crossScope/annotated/gapDays/dupMin/similarity）
+  status        TEXT NOT NULL DEFAULT 'open',
+  first_run_id  TEXT,
+  last_run_id   TEXT,
+  first_seen_at TEXT NOT NULL,
+  last_seen_at  TEXT NOT NULL,
+  PRIMARY KEY (memory_a, memory_b)
+);
+CREATE INDEX IF NOT EXISTS idx_conflict_ledger_status ON conflict_ledger(status);
+
 -- scope_changes: v0.8.1 底座（issue #170）scope 归属的人工修正审计。显式声明
 -- （memory_save/memory_update 的 scope 参数、面板编辑）每次改变某条记忆的
 -- agent/workspace 归属都落一行：改动前后值 + 来源 + actor（tool=模型侧 /
@@ -432,7 +462,10 @@ CREATE INDEX IF NOT EXISTS idx_distill_runs_created ON distill_runs(created_at);
 --   · 本表 = 行级，「这条记忆出生自哪一轮」，覆盖没有窗口的铸造路径。
 -- 只填 **create** 一种动作：merge/conflict/update/supersede 对既有行的改动，receipt_chain
 -- 已经按 (run_id, record_id) 记过了——再造一份就是第二套账。create 是那边唯一的洞
--- （buildOutcome 刻意不给 create 派 disposition，receipt_chain 也就不产行）。
+-- （buildRecordReceipts 不给 create/create_merged 产行：新行没有「改动前后的账」可记，
+-- 只有「出生自哪一轮」，那正是本表的事）。#619 起 buildOutcome 会给 create 派
+-- disposition（created / created-refreshed），那是审计面读的结果，与 receipt_chain
+-- 产不产行是两件事；created-refreshed 是原地刷新，没有出生，本表也不记。
 -- run_type / trigger_source 就地冗余：run_id 在 dream_runs 与 distill_runs 两张表里
 -- 各有自己的主键域，读侧不该为了显示一个类型去 union 两张审计表。
 -- ON DELETE CASCADE：记忆行没了，归因没有指代对象；remove() 仍显式清（与
@@ -607,7 +640,12 @@ CREATE TABLE IF NOT EXISTS choro_pages (
   git_baseline      TEXT,
   template_version  TEXT,
   generated_at      TEXT,
-  human_block_count INTEGER NOT NULL DEFAULT 0
+  human_block_count INTEGER NOT NULL DEFAULT 0,
+  -- 语义段的「对着哪个提交验证的」（openwiki/deepwiki-rs 式的锚点溯源）：只有 T1 写，
+  -- T0 重建整页时随 T1 正文一起归 NULL。全仓 git_baseline 是 T0 的时点，拿它当 claims
+  -- 的比对起点会把「T1 之前就发生、claim 早已算进去」的改动误报成 touched。
+  verified_baseline TEXT,
+  verified_at       TEXT
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_pages_module ON choro_pages(module_id);
 
@@ -706,6 +744,59 @@ CREATE TABLE IF NOT EXISTS profile_fact_runs (
   finished_at    TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_profile_fact_runs_card ON profile_fact_runs(agent_key, started_at);
+
+-- ============================================================
+-- knowledge base（知识库第二层，spec: docs/plans/2026-11-08-kb-qoder-parity.md §3.3）。
+-- 与记忆行物理隔离的硬边界同 choro 那组表：kb 的行永不进 memories /
+-- saveWithDedupe / dream / 质量过滤的任何池子。这里存的是「用户/agent 主动
+-- 收进知识库的资料」——文件、网页、仓库地志页的**副本**与索引，天生属于外来
+-- 原文，让巩固流程够得着它就会把用户刚存的手册自己归档掉。
+-- 幂等键是 (collection_id, rel_key)：同一来源重入库按 sha256 判 no-op，
+-- 变了才替换 chunks（替换语义在 replaceKbDoc 里，事务包住删除与插入）。
+-- rel_key 是来源的稳定相对键（本地文件=绝对路径、网页=URL、地志页=repo#slug），
+-- 不是展示名——展示名在 kb_docs.title。
+CREATE TABLE IF NOT EXISTS kb_collections (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  key         TEXT NOT NULL,
+  title       TEXT NOT NULL,
+  description TEXT,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_kb_collections_key ON kb_collections(key);
+
+-- kind 限定三类（§3.3）：file | url | choro_page。sha256 是**正文内容**的哈希，
+-- 不是文件 stat 的指纹——文件 mtime 变了内容没变时重入库必须是 no-op，
+-- 否则每次保存键盘敲一下都全量重切块。
+CREATE TABLE IF NOT EXISTS kb_docs (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  collection_id INTEGER NOT NULL,
+  rel_key       TEXT NOT NULL,
+  kind          TEXT NOT NULL,
+  source_path   TEXT,
+  title         TEXT NOT NULL,
+  bytes         INTEGER NOT NULL DEFAULT 0,
+  sha256        TEXT,
+  indexed_at    TEXT NOT NULL,
+  status        TEXT NOT NULL DEFAULT 'ok',
+  error         TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_kb_docs_collection_relkey ON kb_docs(collection_id, rel_key);
+
+-- 分块正文。heading 是块所属的二级标题节（无节则空串），ordinal 是块在
+-- 文档内的序号——检索命中要能回指「第几块、哪一节」，面板/工具靠它跳段落。
+-- text 存原文切片（含分块时带的标题行？不含：标题在 heading 里，text 只放正文，
+-- 免得同一条命中把标题算两遍）。
+CREATE TABLE IF NOT EXISTS kb_chunks (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id     INTEGER NOT NULL,
+  ordinal    INTEGER NOT NULL,
+  heading    TEXT NOT NULL DEFAULT '',
+  text       TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_kb_chunks_doc_ordinal ON kb_chunks(doc_id, ordinal);
+
 `;
 
 // Exported for API-layer type validation (standalone API POST /memories and
@@ -864,6 +955,10 @@ function toRow(row) {
     // isImportedRow）——这两格只回答「来自哪个包 / 幂等键是什么」，不回答身份。
     share_pack_id: row.share_pack_id ?? undefined,
     share_external_id: row.share_external_id ?? undefined,
+    // Issue #641 取代链：NULL 读作 undefined（未被取代），与 archived_at 同款
+    // 「时刻不可知就不编值」。
+    superseded_by: row.superseded_by ?? undefined,
+    superseded_at: row.superseded_at ?? undefined,
     content_history: parseJsonArray(row.content_history),
     evidence: parseJsonArray(row.evidence),
     doc_path: row.doc_path ?? undefined,
@@ -960,6 +1055,10 @@ function toConflictPending(row) {
     memory_a: row.memory_a,
     memory_b: row.memory_b,
     reason: row.reason ?? undefined,
+    // Issue #603 第 2 层：入队时的相似度。存量行与调用方没给的行是 NULL，
+    // 这里如实透出 undefined（条件展开：带 undefined 键会让 in-process schema
+    // 校验判违规，同 toApiList 的处理）。
+    ...(typeof row.similarity === "number" ? { similarity: row.similarity } : {}),
     created_at: row.created_at,
     resolved_at: row.resolved_at ?? undefined,
     resolved_winner: row.resolved_winner ?? undefined
@@ -1232,6 +1331,10 @@ export function createStore(path) {
   // chorography（M2，实现计划 P17）：T1 生成轮的页级失败计数。T0 建的表没有它
   // （M0 只写 skeleton），存量库经 PRAGMA 检查后补列，幂等。
   addColumn("choro_pages", "fail_count", "ALTER TABLE choro_pages ADD COLUMN fail_count INTEGER NOT NULL DEFAULT 0");
+  // chorography ①（语义段 provenance）：页级验证基线 + 验证时刻。可空不带 DEFAULT——
+  // 存量行的 NULL 就是事实（那批页富化时还没记这个），不要伪造一个提交号。
+  addColumn("choro_pages", "verified_baseline", "ALTER TABLE choro_pages ADD COLUMN verified_baseline TEXT");
+  addColumn("choro_pages", "verified_at", "ALTER TABLE choro_pages ADD COLUMN verified_at TEXT");
   // chorography 收尾档（P36）：v0.11.0 的 choro_vectors 是空壳表（spec §5 漏了
   // 向量本体列），存量库经 PRAGMA 检查补列。
   addColumn("choro_vectors", "vector", "ALTER TABLE choro_vectors ADD COLUMN vector TEXT");
@@ -1274,6 +1377,15 @@ export function createStore(path) {
   // 唯一性（第二条本地行就撞响），而存量行零重写、读侧 undefined = 「不是外来行」。
   addColumn("memories", "share_pack_id", "ALTER TABLE memories ADD COLUMN share_pack_id TEXT");
   addColumn("memories", "share_external_id", "ALTER TABLE memories ADD COLUMN share_external_id TEXT");
+  // Issue #641（beta 第三阶段，取代链）：T3（时序演进）的处置不归档——旧行写
+  // superseded_by 指向取代它的新行，检索侧降权、注入不再选中，但行本身保持
+  // 活跃、随时可人工恢复。存量行两列皆 NULL：历史裁决走的是「归档」路径，
+  // 反推不出该指给谁（receipt_chain 有 winner/loser，但那是另一套语义），宁可
+  // 不填也不猜。superseded_at 是裁决时刻（服务器单调时钟），与内容时间无关。
+  addColumn("memories", "superseded_by", "ALTER TABLE memories ADD COLUMN superseded_by TEXT");
+  addColumn("memories", "superseded_at", "ALTER TABLE memories ADD COLUMN superseded_at TEXT");
+  // 部分索引：降权查询只关心「已被取代」的行；未取代行（绝大多数）不进索引。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_superseded ON memories(superseded_by) WHERE superseded_by IS NOT NULL;");
   // 索引建在加列之后而非写进 SCHEMA（本文件 content_hash 那段：存量库打开时 CREATE TABLE
   // 是 no-op，列还不存在就建索引会直接 no such column）。
   // 部分索引（WHERE ... IS NOT NULL）是刻意的，但它承重的地方要说准：SQLite 的 UNIQUE
@@ -1493,6 +1605,18 @@ export function createStore(path) {
   addColumn("memory_provenance", "distill_run_id", "ALTER TABLE memory_provenance ADD COLUMN distill_run_id TEXT");
   db.exec("CREATE INDEX IF NOT EXISTS idx_memory_provenance_run ON memory_provenance(distill_run_id);");
 
+  // Issue #603 第 2 层：冲突待审队列此前只能按 created_at 倒序排。一次 sleep 轮次
+  // 里产出的对全部落在同一毫秒（实测 60 条挤在 60ms 内），排序键全同，队列在面板
+  // 上看起来是随机的——而「哪一对最该先看」的唯一客观信号是相似度，此前只存在
+  // reason 文本里（「相似度 0.87」），前端靠正则回收。落成列之后排序键是数据，
+  // 不是解析结果。
+  //
+  // 可空且不带 DEFAULT：存量行没有这个信息，NULL = 「入队时没记」（比填 0 诚实——
+  // 0 会被排到最后，等于替用户断言「这两条毫不相似」）。排序用 NULLS LAST。
+  addColumn("conflict_pending", "similarity", "ALTER TABLE conflict_pending ADD COLUMN similarity REAL");
+  // 索引建在加列之后（同 idx_memory_provenance_run 的理由）：老库打开时列才刚加上。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_conflict_pending_similarity ON conflict_pending(similarity DESC, created_at DESC);");
+
   // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
   // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
   // enforced >= 0). Such a value is ambiguous — it cannot map to a real applied
@@ -1714,13 +1838,12 @@ export function createStore(path) {
     return db.prepare("DELETE FROM distill_parse_failures WHERE session_id = ?").run(sessionId).changes;
   }
 
-  function count(type, { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
-    const clauses = [];
-    const params = [];
-    if (type !== undefined) {
-      clauses.push("type = ?");
-      params.push(type);
-    }
+  // #597：count() 与 countByType() 共用的 WHERE 构造——两张 HTTP 面（宿主内 /list
+  // 与 Bearer /memories）的 total 与 typeCounts 必须同口径，分布的合计才等于总数。
+  // type 刻意不在这里：count() 按调用方带，countByType() 刻意不带（它要的就是
+  // 同一份筛选下、**不带类型**的全库分布——面板分类栏被 type 筛过的页上数不出它）。
+  function pushCountFilters(opts, clauses, params) {
+    const { minImportance = null, source = null, includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = opts ?? {};
     // Same filters as list() so a paged caller's total matches its rows.
     if (minImportance != null) {
       clauses.push("importance >= ?");
@@ -1786,10 +1909,32 @@ export function createStore(path) {
         "(id IN (SELECT record_id FROM receipt_chain WHERE kind IN ('merge', 'update') AND verdict = 'live') OR source = 'dream')"
       );
     }
+  }
+
+  function count(type, opts = {}) {
+    const clauses = [];
+    const params = [];
+    if (type !== undefined) {
+      clauses.push("type = ?");
+      params.push(type);
+    }
+    pushCountFilters(opts, clauses, params);
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     return db.prepare(`SELECT count(*) AS c FROM memories ${where}`).get(...params).c;
   }
 
+  // #597（/list 的 typeCounts）：同一份筛选、不带 type，一次 GROUP BY 拿全库分布。
+  // 面板分类栏的数字源：被 type 筛过又分过页的已加载行上数不出真分布。GROUP BY
+  // 只回存在的类，缺类即 0；分布合计恒等于同筛选的 count(undefined)。
+  function countByType(opts = {}) {
+    const clauses = [];
+    const params = [];
+    pushCountFilters(opts, clauses, params);
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT type, count(*) AS c FROM memories ${where} GROUP BY type`).all(...params);
+    return Object.fromEntries(rows.map((r) => [r.type, r.c]));
+  }
+
   function getById(id) {
     const row = db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
     return toRow(row);
@@ -2575,6 +2720,30 @@ export function createStore(path) {
     return needsEmbeddingFor(modelHash, 1).length > 0;
   }
 
+  /**
+   * How many rows needsEmbeddingFor() would pick in total.
+   *
+   * A re-index run is bounded by a limit, so "indexed: 0" and "indexed: 3 of
+   * 300" looked identical to the caller. Counting is cheap (no content is
+   * materialised) and is what lets the caller say how much work is left.
+   */
+  function countNeedsEmbeddingFor(modelHash) {
+    if (!modelHash) {
+      return db.prepare(
+        `SELECT count(*) AS c FROM memories
+         WHERE (embedding IS NULL OR embedding = '')
+           AND forgotten = 0 AND archived = 0`
+      ).get().c;
+    }
+    return db.prepare(
+      `SELECT count(*) AS c FROM memories
+       WHERE ((embedding IS NULL OR embedding = '')
+              OR embedding_model IS NULL
+              OR embedding_model != ?)
+         AND forgotten = 0 AND archived = 0`
+    ).get(String(modelHash)).c;
+  }
+
   /** Per-model provenance counts over active rows ('' = unknown origin). */
   function embeddingModelBreakdown() {
     return db.prepare(
@@ -3650,6 +3819,18 @@ export function createStore(path) {
     return { path: typeof path === "string" ? path : null, pageSize, pageCount, freelistCount, fileBytes };
   }
 
+  /**
+   * 容量预警的行数口径（#275 空间维度）：活跃 / 归档各一格。体积与空闲页在
+   * storageStats()，这里只补行数——两条 COUNT 的成本，挂在 /health 的按需读上，
+   * 没有周期性消费者。归档增速（净增速率）是 recall-stats 的 archive 块（第五
+   * 指标，按精确 archived_at 算），这里刻意不算速率：同一个数字长两处就会分叉。
+   */
+  function capacityStats() {
+    const active = db.prepare("SELECT COUNT(*) AS n FROM memories WHERE archived = 0").get().n;
+    const archived = db.prepare("SELECT COUNT(*) AS n FROM memories WHERE archived = 1").get().n;
+    return { active, archived };
+  }
+
   /**
    * 整库 VACUUM（#275 的手动步骤）：代价 O(库大小) 且需要排他写锁，所以只在显式
    * 入口里跑，绝不挂启动路径、也不开 auto_vacuum。
@@ -3712,7 +3893,10 @@ export function createStore(path) {
    * pending once — a re-detection in a later dream run is a no-op, never a
    * duplicate queue entry. Returns the pending row (freshly inserted, or the
    * existing unresolved row when the pair is already pending), or undefined
-   * when the re-detection is suppressed.
+   * when the re-detection is suppressed. The returned row carries `fresh`:
+   * true only when this call actually inserted a row, false when the pair was
+   * already pending (issue #603 — callers used to read "non-null" as "parked",
+   * so a re-detection re-reported the same pair as a new freeze every run).
    *
    * v0.8.1（issue #170 复核项 4）：人工已裁决过的对（resolved_at 非空）不再
    * 反复入队——除非任一侧在裁决之后又被改过（updated_at 晚于 resolved_at）。
@@ -3720,12 +3904,12 @@ export function createStore(path) {
    * updated_at 是宽松代理（任何字段更新都会触发重新评审）——宁可多看一眼，
    * 不静音真冲突。
    */
-  function saveConflictPending({ run_id, memory_a, memory_b, reason }) {
+  function saveConflictPending({ run_id, memory_a, memory_b, reason, similarity }) {
     const [a, b] = [memory_a, memory_b].sort();
     const existing = db.prepare(
       "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NULL LIMIT 1"
     ).get(a, b);
-    if (existing) return toConflictPending(existing);
+    if (existing) return { ...toConflictPending(existing), fresh: false };
     const reviewed = db.prepare(
       "SELECT * FROM conflict_pending WHERE memory_a = ? AND memory_b = ? AND resolved_at IS NOT NULL ORDER BY resolved_at DESC, rowid DESC LIMIT 1"
     ).get(a, b);
@@ -3737,16 +3921,29 @@ export function createStore(path) {
     }
     const id = randomUUID();
     const now = nowIso();
+    // Issue #603 第 2 层：相似度落列。调用方拿不到（LLM 裁决路径只有理由文本）
+    // 就写 NULL，不猜——面板与排序都按「未知」处理，而不是当成 0。
+    const sim = typeof similarity === "number" && Number.isFinite(similarity)
+      && similarity >= 0 && similarity <= 1 ? similarity : null;
     db.prepare(
-      `INSERT INTO conflict_pending (id, run_id, memory_a, memory_b, reason, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`
-    ).run(id, run_id ?? null, a, b, reason ?? null, now);
-    return toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id));
+      `INSERT INTO conflict_pending (id, run_id, memory_a, memory_b, reason, similarity, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, run_id ?? null, a, b, reason ?? null, sim, now);
+    return { ...toConflictPending(db.prepare("SELECT * FROM conflict_pending WHERE id = ?").get(id)), fresh: true };
   }
 
   /**
-   * List pending conflicts, newest first. Unresolved rows only by default;
-   * pass includeResolved to include resolved ones (audit view).
+   * List pending conflicts, most-similar first. Unresolved rows only by
+   * default; pass includeResolved to include resolved ones (audit view).
+   *
+   * Issue #603 第 2 层：排序键从「created_at DESC」改成「相似度 DESC → created_at
+   * DESC」。原键在同一次 sleep 轮次里全同（实测 60 条落在 60ms 内），队列在面板
+   * 上等于随机；相似度是「该先看哪对」的唯一客观信号，现在它是一列而不是 reason
+   * 文本里的正则。
+   *
+   * NULL 排最后而不是当 0：存量行与 LLM 裁决路径没记相似度，把它们混进「低相似
+   * 度」会把「未知」伪装成「已测量」。`(similarity IS NULL)` 前缀让这条不依赖
+   * SQLite 的 NULL 排序约定，两个方向都稳。
    */
   function listConflictPending({ limit = 50, offset = 0, includeResolved = false } = {}) {
     const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
@@ -3755,7 +3952,9 @@ export function createStore(path) {
     if (!includeResolved) clauses.push("resolved_at IS NULL");
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     const rows = db.prepare(
-      `SELECT * FROM conflict_pending ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`
+      `SELECT * FROM conflict_pending ${where}
+       ORDER BY (similarity IS NULL), similarity DESC, created_at DESC, id
+       LIMIT ? OFFSET ?`
     ).all(...params, lim, off);
     return rows.map(toConflictPending);
   }
@@ -3882,6 +4081,137 @@ export function createStore(path) {
     ).all(Math.max(1, Math.min(5000, limit | 0)));
   }
 
+  // --- conflict triage ledger（issue #641，shadow 档）-----------------------
+
+  // 四态里 superseded（已被取代）与 open 有写入点；differentiated（人审判为不同事、
+  // 不必再问）与 zombied（两条都已退场、无从消解）是预留位，当前没有任何代码路径
+  // 会写它们——留着是为了状态机与面板筛选口径完整，别当成「已实现但没数据」。
+  const LEDGER_STATUSES = new Set(["open", "superseded", "differentiated", "zombied"]);
+  const LEDGER_TIERS = new Set(["dup", "cross-scope-dup", "evolution", "conflict"]);
+
+  /**
+   * Record one triage observation. Upsert on the normalized pair: tier/
+   * signals/last_* refresh (the pair's classification may legitimately change
+   * after an edit), while first_seen_at/first_run_id stay put — 挂账时长与
+   * 消解路径统计都锚在首次检出，刷新它们等于重写历史。
+   */
+  function saveConflictLedgerEntry({ run_id, memory_a, memory_b, tier, similarity, signals }) {
+    const [a, b] = [memory_a, memory_b].sort();
+    if (!LEDGER_TIERS.has(tier)) {
+      throw new Error(`conflict_ledger: unknown tier ${String(tier)}`);
+    }
+    const now = nowIso();
+    db.prepare(
+      `INSERT INTO conflict_ledger (memory_a, memory_b, tier, similarity, signals, status, first_run_id, last_run_id, first_seen_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, 'open', ?, ?, ?, ?)
+       ON CONFLICT(memory_a, memory_b) DO UPDATE SET
+         tier         = excluded.tier,
+         similarity   = excluded.similarity,
+         signals      = excluded.signals,
+         last_run_id  = excluded.last_run_id,
+         last_seen_at = excluded.last_seen_at`
+    ).run(
+      a, b, tier,
+      typeof similarity === "number" ? similarity : null,
+      // 与 differentiated_pairs.distinctions 同一条约定：没有就落 NULL，不落 "[]"。
+      signals == null ? null : JSON.stringify(signals),
+      run_id ?? null, run_id ?? null, now, now
+    );
+  }
+
+  /** Status transition for the lazy-resolution stages (enforce-phase wiring). */
+  function setConflictLedgerStatus(memory_a, memory_b, status) {
+    const [a, b] = [memory_a, memory_b].sort();
+    if (!LEDGER_STATUSES.has(status)) {
+      throw new Error(`conflict_ledger: unknown status ${String(status)}`);
+    }
+    const res = db.prepare(
+      "UPDATE conflict_ledger SET status = ? WHERE memory_a = ? AND memory_b = ?"
+    ).run(status, a, b);
+    return res.changes > 0;
+  }
+
+  /**
+   * 取代链落笔（issue #641，T3 时序演进的处置）：旧行 superseded_by → 新行。
+   * 只动这两列，刻意不走 updateMemory 的完整写路径——syncMirror/notifyWrite/
+   * updated_at 都不该被一个纯元数据标注触发（正文一个字节没变，镜像无 diff
+   * 可同步；bump updated_at 反而会误导「已审过」的宽松代理判定）。已归档/
+   * 已遗忘的行不落链（它们已经退场，再标注是给幽灵记账）；重复写同一指向
+   * 是无害的幂等 no-op，换指向以最后一次为准。
+   *
+   * 幂等守卫（#650 评审）：上面那句「无害的 no-op」只对指向成立——superseded_at
+   * 每次都会刷成新的 nowIso()，返回值又按 changes > 0 判，于是同一对每轮都报
+   * 「刚处理过」：t3Chained 虚增，取代时刻被改写成最近一次巩固的时间（挂账时长
+   * 一类指标随之失真）。先读当前指向，已指向同一 winner 就直接返回 false 且不
+   * 写库，只有首次落链或换指向才真正落笔。
+   */
+  function supersedeChain(loserId, winnerId) {
+    const current = db.prepare("SELECT superseded_by FROM memories WHERE id = ?").get(loserId);
+    // 行不存在 / 已指向同一继任者：no-op，不刷时间戳、不计入变更数。
+    if (!current || current.superseded_by === winnerId) return false;
+    const res = db.prepare(
+      "UPDATE memories SET superseded_by = ?, superseded_at = ? WHERE id = ? AND archived = 0 AND forgotten = 0"
+    ).run(winnerId, nowIso(), loserId);
+    return res.changes > 0;
+  }
+
+  /**
+   * 已被取代行的 id 清单（issue #641，T3 检索侧降权用）。走部分索引，未落链
+   * 的库上是空查询。返回数组而非 Set——集合语义由调用方决定。
+   *
+   * 只认「继任者仍活着」的旧行（#650 评审）：链是一次性写下的指向，而继任者
+   * 之后仍可能被归档/遗忘/删除。若只判 superseded_by IS NOT NULL，那种情况下
+   * 旧行会被当成「已有新版本」从注入里摘掉，可它自己明明是活的、且它指向的
+   * 那条已经退场——数据在库里却永远不再出现，是一种沉默的不可逆失效。JOIN 到
+   * 继任者上要求 archived=0 且 forgotten=0，继任者退场即自动恢复旧行可见性。
+   */
+  function supersededIds() {
+    return db.prepare(
+      `SELECT m.id AS id
+         FROM memories m
+         JOIN memories w ON w.id = m.superseded_by
+        WHERE m.superseded_by IS NOT NULL
+          AND w.archived = 0
+          AND w.forgotten = 0`
+    ).all().map((r) => r.id);
+  }
+
+  /**
+   * 仍未消解的真矛盾对（issue #641，T4 注入侧感知用）。只取 tier=conflict 且
+   * status=open 的行——superseded/differentiated 已消解，zombied 已被 heat 兜底；
+   * shadow 档记下的观察对也在其中（注入侧标注以 enforce 档为门，见 injectCandidates）。
+   * 按最近观察排序，上限 2000：账本对的量级是个位数到几十，上限只为防御性兜底。
+   */
+  function openConflictPairs(limit = 2000) {
+    return db.prepare(
+      "SELECT memory_a, memory_b, first_seen_at AS detected FROM conflict_ledger WHERE tier = 'conflict' AND status = 'open' ORDER BY last_seen_at DESC LIMIT ?"
+    ).all(Math.max(1, Math.min(2000, limit | 0)));
+  }
+
+  /** Triage rows for the panel/analysis views, newest detection first. */
+  function listConflictLedger({ limit = 200, offset = 0, tier, status } = {}) {
+    const lim = Math.max(1, Math.min(5000, limit | 0));
+    const off = Math.max(0, offset | 0);
+    const where = [];
+    const args = [];
+    if (tier != null) { where.push("tier = ?"); args.push(String(tier)); }
+    if (status != null) { where.push("status = ?"); args.push(String(status)); }
+    const clause = where.length ? ` WHERE ${where.join(" AND ")}` : "";
+    args.push(lim, off);
+    return db.prepare(
+      `SELECT * FROM conflict_ledger${clause} ORDER BY last_seen_at DESC, rowid DESC LIMIT ? OFFSET ?`
+    ).all(...args);
+  }
+
+  function countConflictLedger({ tier, status } = {}) {
+    const where = [];
+    const args = [];
+    if (tier != null) { where.push("tier = ?"); args.push(String(tier)); }
+    if (status != null) { where.push("status = ?"); args.push(String(status)); }
+    const clause = where.length ? ` WHERE ${where.join(" AND ")}` : "";
+    return db.prepare(`SELECT COUNT(*) AS n FROM conflict_ledger${clause}`).get(...args).n;
+  }
+
   /**
    * v0.8.1 底座（issue #170）：scope 归属人工修正的审计行。record 描述「一次
    * 决策后的完整状态」（prev_* 为改前、next_* 为改后，NULL=global/未标注），
@@ -4265,6 +4595,26 @@ export function createStore(path) {
     return result.changes > 0;
   }
 
+  /**
+   * 覆盖一条关系行的 metadata（#619）。关系本身仍按 saveRelation 追加，
+   * 这条只给「同一条边被后续观察补充证据」用——情感相位判重命中时要把
+   * evidence 并集与 sessionCount 写回既有边，否则边上的场合数会永远停在
+   * 第一次写入那一刻。只改 metadata，不动 weight/source/created_at：这条边的
+   * 来源与权重反映的是它第一次被建立时的事实。
+   * 幂等（缺行 changes=0 → false）。
+   */
+  function updateRelationMetadata(id, metadata) {
+    const metaStr = metadata === undefined
+      ? null
+      : typeof metadata === "string"
+        ? metadata
+        : JSON.stringify(metadata);
+    const result = db.prepare(
+      "UPDATE entity_relations SET metadata = ? WHERE id = ?"
+    ).run(metaStr, id);
+    return result.changes > 0;
+  }
+
   /**
    * Re-point every attr row whose memory_id is fromMemoryId to toMemoryId
    * (autoDream merge migration, v0.3.0 Phase 4 / 4.3.2). When the keeper
@@ -4498,13 +4848,58 @@ export function createStore(path) {
     ).all(memoryId).map(toRelation);
   }
 
+  /**
+   * 按关系类型取全部边（#619 可见化 C）。情感边散在 23k 个实体之间，`ego` 端点
+   * 是「从某个实体往外看」，天然不适合回答「这库里一共记了哪些情绪」——那要的
+   * 是反向的、全局的一眼。所以单开一条按类型全表取，一次 SQL，不做 N 次往返。
+   *
+   * 只按类型过滤，不在 SQL 里碰 metadata：情绪/归属/场合数都由调用方从 metadata
+   * 里读，SQL 里拼 JSON 提取会把「字段名」焊进查询，下一版改字段名就得改 SQL。
+   * 按 created_at DESC 排，最近记的更靠前；limit 兜底防止面板把整表拖进内存。
+   */
+  function relationsByType(relationType, limit = 500) {
+    if (!relationType) return [];
+    const lim = Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : 500;
+    if (lim === 0) return [];
+    // 端点名字一并取回：面板要显示「谁对谁」，让调用方拿 id 再逐条查实体
+    // 就是 N 次往返，而这个列表本来就是给「一眼看全」用的。
+    const rows = db.prepare(
+      `SELECT r.*, f.name AS from_name, f.type AS from_type,
+              t.name AS to_name, t.type AS to_type
+         FROM entity_relations r
+         LEFT JOIN entities f ON f.id = r.from_entity
+         LEFT JOIN entities t ON t.id = r.to_entity
+        WHERE r.relation_type = ?
+        ORDER BY r.created_at DESC
+        LIMIT ?`
+    ).all(relationType, lim);
+    return rows.map((row) => ({
+      ...toRelation(row),
+      from_name: row.from_name ?? null,
+      from_type: row.from_type ?? null,
+      to_name: row.to_name ?? null,
+      to_type: row.to_type ?? null
+    }));
+  }
+
   /** All entities (optionally name-filtered, newest first). Used by sleep phase 4
    *  orphan detection: an entity with zero relations is a candidate for relation
    *  completion. */
-  function listEntities({ limit = 1000 } = {}) {
+  function listEntities({ limit = 1000, q } = {}) {
+    const needle = typeof q === "string" ? q.trim() : "";
+    if (needle === "") {
+      const rows = db.prepare(
+        "SELECT * FROM entities ORDER BY last_seen DESC, name ASC LIMIT ?"
+      ).all(limit);
+      return rows.map(toEntity);
+    }
+    // 名字过滤放在 SQL 侧：调用方若在 LIMIT 之后过滤，排在 limit 之外的实体
+    // 就永远搜不到（面板按 limit=200 取回再本地过滤，1.6 万实体时命中率约 1%）。
+    // LIKE 的 % / _ 用 ESCAPE 转义，否则用户输入一个 "%" 就会把整库匹配出来。
+    const escaped = needle.replace(/[\\%_]/g, (ch) => `\\${ch}`);
     const rows = db.prepare(
-      "SELECT * FROM entities ORDER BY last_seen DESC, name ASC LIMIT ?"
-    ).all(limit);
+      "SELECT * FROM entities WHERE name LIKE ? ESCAPE '\\' ORDER BY last_seen DESC, name ASC LIMIT ?"
+    ).all(`%${escaped}%`, limit);
     return rows.map(toEntity);
   }
 
@@ -4914,7 +5309,8 @@ export function createStore(path) {
   function choroPageBySlug(repoId, slug) {
     return db.prepare(
       `SELECT p.id, p.module_id, p.rel_path, p.status, p.git_baseline, p.template_version,
-              p.generated_at, p.human_block_count, p.fail_count, m.slug
+              p.generated_at, p.human_block_count, p.fail_count,
+              p.verified_baseline, p.verified_at, m.slug
          FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
         WHERE m.repo_id = ? AND m.slug = ?`
     ).get(repoId, String(slug));
@@ -4935,10 +5331,17 @@ export function createStore(path) {
 
   // 富化成功：skeleton → enriched，generatedAt 推进、失败计数清零（成功重置的是
   // 「连续失败」的连续性，不是历史）。
-  function markChoroPageEnriched(pageId, generatedAt) {
+  //
+  // verifiedBaseline 是 T1 那一刻的 HEAD：claims 的行号取自那个提交的代码，之后判失效
+  // 只能从它起算（传 null 表示拿不到 HEAD——那时 diff 判不了，面板要说「不知道」，
+  // 而不是退回全仓 git_baseline 假装知道）。
+  function markChoroPageEnriched(pageId, generatedAt, verifiedBaseline = null) {
     db.prepare(
-      "UPDATE choro_pages SET status = 'enriched', generated_at = ?, fail_count = 0 WHERE id = ?"
-    ).run(generatedAt, pageId);
+      `UPDATE choro_pages
+          SET status = 'enriched', generated_at = ?, fail_count = 0,
+              verified_baseline = ?, verified_at = ?
+        WHERE id = ?`
+    ).run(generatedAt, verifiedBaseline, generatedAt, pageId);
   }
 
   // 单页 claims 整页替换（P20 的表侧）：T1 一轮产出的 claims 删旧插新；evidence/
@@ -5128,9 +5531,143 @@ export function createStore(path) {
     ).all().map((r) => r.k);
   }
 
+  /* --------------------- knowledge base（知识库第二层，§3.3） --------------------- */
+  // 与 choro 那组表同一套纪律：本域只读写 kb_* 三张表，绝不进 memories /
+  // saveWithDedupe / dream / 质量过滤的任何池子。时间戳由调用方传（一次 ingest
+  // 的所有行共用一个时刻），store 不自取 now()——两处时钟会把「同一次入库」拆成
+  // 两个版本，sha256 幂等判据也会跟着抖。
+
+  function kbCollectionByKey(key) {
+    return db.prepare("SELECT * FROM kb_collections WHERE key = ?").get(String(key)) ?? undefined;
+  }
+
+  /** 集合列表带计数：面板左栏要的不是空壳 key 列表，docs/chunks 是它的主信息。 */
+  function listKbCollections() {
+    return db.prepare(
+      `SELECT c.*,
+              (SELECT COUNT(*) FROM kb_docs d WHERE d.collection_id = c.id) AS doc_count,
+              (SELECT COUNT(*) FROM kb_chunks k JOIN kb_docs d2 ON k.doc_id = d2.id
+                 WHERE d2.collection_id = c.id) AS chunk_count
+         FROM kb_collections c ORDER BY c.key`
+    ).all();
+  }
+
+  // key 是外部键（面板/工具用它寻址），title 是展示名。ON CONFLICT 不动 created_at：
+  // 「这个集合哪天建的」是事实，重命名不该改写它。
+  function upsertKbCollection({ key, title, description = null, at }) {
+    db.prepare(
+      `INSERT INTO kb_collections (key, title, description, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(key) DO UPDATE SET
+         title = excluded.title,
+         description = excluded.description,
+         updated_at = excluded.updated_at`
+    ).run(String(key), String(title), description ?? null, at, at);
+    return kbCollectionByKey(key);
+  }
+
+  /** 删集合连带删它的文档与分块（三张表是一个整体，留孤儿行等于悄悄占空间）。 */
+  function deleteKbCollection(key) {
+    const row = kbCollectionByKey(key);
+    if (!row) return false;
+    return runAtomically(() => {
+      db.prepare(
+        "DELETE FROM kb_chunks WHERE doc_id IN (SELECT id FROM kb_docs WHERE collection_id = ?)"
+      ).run(row.id);
+      db.prepare("DELETE FROM kb_docs WHERE collection_id = ?").run(row.id);
+      db.prepare("DELETE FROM kb_collections WHERE id = ?").run(row.id);
+      return true;
+    });
+  }
+
+  function listKbDocs(collectionId) {
+    return db.prepare(
+      "SELECT * FROM kb_docs WHERE collection_id = ? ORDER BY rel_key"
+    ).all(collectionId);
+  }
+
+  function kbDocByRelKey(collectionId, relKey) {
+    return db.prepare(
+      "SELECT * FROM kb_docs WHERE collection_id = ? AND rel_key = ?"
+    ).get(collectionId, String(relKey)) ?? undefined;
+  }
+
+  function kbChunksByDoc(docId) {
+    return db.prepare(
+      "SELECT * FROM kb_chunks WHERE doc_id = ? ORDER BY ordinal"
+    ).all(docId);
+  }
+
+  /**
+   * 入库落库的唯一写口。幂等判据是 **正文 sha256**（不是文件 stat）：同 rel_key +
+   * 同 sha256 = 整件事 no-op，回执 skipped 且不动 chunks——否则编辑器保存一次
+   * （mtime 变、内容没变）就要全量重切块，库和索引一起白忙。
+   *
+   * 变了才替换：删旧 chunks 再插新的，事务包住，半截失败整体回滚，库里保持上一版
+   * 完整文档。上一版 status=error 的行不算命中（它没有可分块的正文，重来必须真跑）。
+   */
+  function replaceKbDoc({ collectionId, relKey, kind, sourcePath = null, title, bytes = 0, sha256 = null, at, chunks = [] }) {
+    return runAtomically(() => {
+      const prev = kbDocByRelKey(collectionId, relKey);
+      if (prev && prev.status === "ok" && sha256 && prev.sha256 === sha256) {
+        return { docId: prev.id, chunks: kbChunksByDoc(prev.id).length, skipped: true };
+      }
+      db.prepare("DELETE FROM kb_chunks WHERE doc_id IN (SELECT id FROM kb_docs WHERE collection_id = ? AND rel_key = ?)")
+        .run(collectionId, String(relKey));
+      let docId;
+      if (prev) {
+        db.prepare(
+          `UPDATE kb_docs SET kind = ?, source_path = ?, title = ?, bytes = ?, sha256 = ?,
+                  indexed_at = ?, status = 'ok', error = NULL WHERE id = ?`
+        ).run(kind, sourcePath, String(title), bytes, sha256, at, prev.id);
+        docId = prev.id;
+      } else {
+        const info = db.prepare(
+          `INSERT INTO kb_docs (collection_id, rel_key, kind, source_path, title, bytes, sha256, indexed_at, status, error)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'ok', NULL)`
+        ).run(collectionId, String(relKey), kind, sourcePath, String(title), bytes, sha256, at);
+        docId = Number(info.lastInsertRowid);
+      }
+      const ins = db.prepare(
+        "INSERT INTO kb_chunks (doc_id, ordinal, heading, text, created_at) VALUES (?, ?, ?, ?, ?)"
+      );
+      for (const c of chunks) ins.run(docId, c.ordinal, c.heading ?? "", c.text ?? "", at);
+      return { docId, chunks: chunks.length, skipped: false };
+    });
+  }
+
+  /** 入库失败也要留痕：面板要能显示「这份文档上次为什么没进来」，静默丢来源等于假成功。 */
+  function markKbDocError({ collectionId, relKey, kind, sourcePath = null, title, error, at }) {
+    const prev = kbDocByRelKey(collectionId, relKey);
+    if (prev) {
+      db.prepare(
+        "UPDATE kb_docs SET status = 'error', error = ?, indexed_at = ?, source_path = ?, kind = ?, title = ? WHERE id = ?"
+      ).run(String(error ?? ""), at, sourcePath, kind, String(title ?? prev.title), prev.id);
+      return prev.id;
+    }
+    const info = db.prepare(
+      `INSERT INTO kb_docs (collection_id, rel_key, kind, source_path, title, bytes, sha256, indexed_at, status, error)
+       VALUES (?, ?, ?, ?, ?, 0, NULL, ?, 'error', ?)`
+    ).run(collectionId, String(relKey), kind, sourcePath, String(title ?? relKey), at, String(error ?? ""));
+    return Number(info.lastInsertRowid);
+  }
+
+  /** 检索候选集：跨集合或单集合，一次取全（BM25 需要全语料算 df，不能分页取）。 */
+  function kbChunksForSearch(collectionId = null) {
+    return db.prepare(
+      `SELECT k.id, k.doc_id, k.ordinal, k.heading, k.text,
+              d.rel_key, d.title, d.kind, c.key AS collection_key
+         FROM kb_chunks k
+         JOIN kb_docs d ON k.doc_id = d.id
+         JOIN kb_collections c ON d.collection_id = c.id
+        WHERE d.status = 'ok' AND (? IS NULL OR d.collection_id = ?)`
+    ).all(collectionId, collectionId);
+  }
+
   return {
     db,
     count,
+    countByType,
     getById,
     // 车道 C：外来行身份的两个读口（幂等键 / 整包清点）。
     getByShareExternalId,
@@ -5174,6 +5711,7 @@ export function createStore(path) {
     embeddedCount,
     needsEmbedding,
     needsEmbeddingFor,
+    countNeedsEmbeddingFor,
     hasStaleEmbedding,
     embeddingModelBreakdown,
     embeddingDimensionBreakdown,
@@ -5232,6 +5770,7 @@ export function createStore(path) {
     archivedEmbeddingStats,
     clearArchivedEmbeddings,
     storageStats,
+    capacityStats,
     vacuum,
     saveFailure,
     listFailures,
@@ -5248,6 +5787,13 @@ export function createStore(path) {
     saveConflictReviewed,
     loadConflictReviewed,
     listConflictReviewed,
+    saveConflictLedgerEntry,
+    setConflictLedgerStatus,
+    supersedeChain,
+    supersededIds,
+    openConflictPairs,
+    listConflictLedger,
+    countConflictLedger,
     saveScopeChange,
     listScopeChanges,
     // 政策轴（issue #471）：按下/松开一个作用域。纯 bookkeeping，不调
@@ -5284,9 +5830,11 @@ export function createStore(path) {
     listBoostedRelations,
     getLinkedMemoryIds,
     saveRelation,
+    updateRelationMetadata,
     bumpRelationWeight,
     migrateAttrsToMemory,
     getRelations,
+    relationsByType,
     getEntityNeighbors,
     getRelationsByMemory,
     setMirrorState,
@@ -5303,6 +5851,17 @@ export function createStore(path) {
     getContinuityProposal,
     listContinuityProposals,
     countContinuityProposals,
+    // knowledge base（知识库第二层，§3.3）：三张 kb_* 表，与记忆行物理隔离。
+    kbCollectionByKey,
+    listKbCollections,
+    upsertKbCollection,
+    deleteKbCollection,
+    listKbDocs,
+    kbDocByRelKey,
+    kbChunksByDoc,
+    replaceKbDoc,
+    markKbDocError,
+    kbChunksForSearch,
     // chorography（仓库地志）：M0 只写不读，消费面 M1 接（见上面注释块）。
     choroRepoByRoot,
     upsertChoroRepo,