@modusensus/dsh-mneme 0.10.1 → 0.11.0

package/lib/store.js

@@ -2,6 +2,10 @@ import { DatabaseSync } from "node:sqlite";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { contentHashOf } from "./content-hash.js";
+// 质量分回填要的判据与扣分表。只取常量与纯函数：依赖方向 store → quality-filter 单向
+// （quality-filter.js 不 import 任何本包模块，是纯函数模块），不构成环，也不会让存储层
+// 反向依赖服务层。判据只许有一份——回填另写一个 0.7 就会与写入路径悄悄分叉。
+import { REPETITION_THRESHOLD, SIGNAL_DEDUCTIONS, repetitionRatio } from "./quality-filter.js";
 // 政策轴（issue #471）的归一化函数。刻意只取归一化，不取判定：判定（buildPausedIndex /
 // matchPausedScopes / createScopeStateGate）留在 scope-state.js，由 service 侧消费，
 // 存储层只管「一格状态怎么落」。依赖方向 store → scope-state → scope 是单向的
@@ -49,6 +53,20 @@ CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance);
 -- （5k 行实测 all() 231ms → 135ms）。IF NOT EXISTS 幂等，存量库启动即建。
 CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at);
 
+-- 一次性数据迁移的登记表：一条迁移一行，跑过就记下。看起来多余（本文件其余迁移都
+-- 靠「条件式 SQL 恒等幂等」），但存量回填那类迁移的条件在跑完之后**恒不命中、却仍要
+-- 全表扫一遍才能证明不命中**——质量分回填的探测在本机 12,827 行上是 36.7 ms，而
+-- createStore 稳态才 3.3 ms，等于每次打开都白付十倍的开销。登记表把这一步变成一次
+-- 主键 seek。
+-- 为什么不是 PRAGMA user_version：实测它在 BEGIN 里设值**不随 ROLLBACK 回退**，与回填
+-- 放不进同一个事务（先置标记再回填中途失败 = 永久漏跑）；而且它全库只有一个整数，被
+-- 单条迁移占掉之后，日后真需要 schema 版本号就没地方放了。普通表既能跟着事务回退，
+-- 也能一条迁移一行。
+CREATE TABLE IF NOT EXISTS applied_migrations (
+  id          TEXT PRIMARY KEY,
+  applied_at  TEXT NOT NULL
+);
+
 -- autoDream audit trail: one row per consolidation run, capturing the exact
 -- input snapshot digest + the LLM decision list + per-id outcome + a compact
 -- receipt. This makes every decision replayable so silent consolidation errors
@@ -516,6 +534,98 @@ CREATE TABLE IF NOT EXISTS continuity_proposals (
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_continuity_session_kind ON continuity_proposals(session_id, kind);
 CREATE INDEX IF NOT EXISTS idx_continuity_status ON continuity_proposals(status, updated_at);
+
+-- ============================================================
+-- chorography（仓库地志，spec: docs/specs/2026-11-04-chorography-design.md）。
+-- 与记忆行物理隔离的硬边界落在这组表上：wiki 的行永不进 memories /
+-- saveWithDedupe / dream / 质量过滤的任何池子（spec §3）——autoDream 的
+-- 「对核心知识库长期参考价值较低」归档理由一旦够得着 wiki 行，机器生成页就会
+-- 被巩固流程自己归档掉（dream-archive-guardrail 测的正是这个语义）。
+-- M0 只有 T0 确定性骨架（零模型）；choro_claims / choro_vectors 此时是空壳，
+-- 分别在 M2（T1 生成轮出 claims）与 M1/M2（embedder 接入）开始灌数据。
+--
+-- 仓库登记（实现计划 P2 补口）：spec §5 的 choro_modules.repo_id 指向这里；
+-- 消费面「按工作目录匹配已登记仓库」（spec §7）也要求登记行。root_path 存
+-- realpath——Windows 上大小写不同的两条路径指向同一目录，登记表按 realpath
+-- 收敛成一行。唯一性照本仓惯例走独立索引，不进 CREATE TABLE。
+CREATE TABLE IF NOT EXISTS choro_repos (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  root_path        TEXT NOT NULL,
+  name             TEXT NOT NULL,
+  plan_fingerprint TEXT,              -- 上次成功 run 的 plan.yaml 内容 sha256
+  git_baseline     TEXT,              -- 上次成功 run 的 HEAD
+  created_at       TEXT NOT NULL,
+  updated_at       TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_repos_root ON choro_repos(root_path);
+
+-- 模块划分与依赖边。fingerprint = 模块文件集 + 边集的内容 sha256：幂等语义靠
+-- replaceChoroGraph 的整仓替换，不靠逐行 diff，所以本表没有「上次见过的划分」
+-- 之外的账要记。
+CREATE TABLE IF NOT EXISTS choro_modules (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_id     INTEGER NOT NULL,
+  slug        TEXT NOT NULL,
+  title       TEXT NOT NULL,
+  parent_id   INTEGER,                -- 最近祖先模块（目录包含关系），无则 NULL
+  file_count  INTEGER NOT NULL DEFAULT 0,
+  fingerprint TEXT,
+  updated_at  TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_modules_repo_slug ON choro_modules(repo_id, slug);
+
+-- 页面 ↔ baseline ↔ 状态。rel_path 是仓库相对路径（.chorography/modules/<slug>.md）：
+-- 真源在仓库磁盘的 MD 里（spec §4），本表只做索引与状态账，删了可以整表重算。
+CREATE TABLE IF NOT EXISTS choro_pages (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  module_id         INTEGER NOT NULL,
+  rel_path          TEXT NOT NULL,
+  status            TEXT NOT NULL DEFAULT 'skeleton',  -- skeleton | enriched | stale | failed
+  git_baseline      TEXT,
+  template_version  TEXT,
+  generated_at      TEXT,
+  human_block_count INTEGER NOT NULL DEFAULT 0
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_pages_module ON choro_pages(module_id);
+
+-- 溯源知识卡（M2 起写）：陈述 + 出处锚点（相对路径#Lx-Ly）。kind 限定五类
+-- （spec §5），不在别处发明第六类。
+CREATE TABLE IF NOT EXISTS choro_claims (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  page_id     INTEGER NOT NULL,
+  statement   TEXT NOT NULL,
+  kind        TEXT NOT NULL,          -- architecture | convention | tech-stack | setup | unknown
+  source_path TEXT,
+  start_line  INTEGER,
+  end_line    INTEGER,
+  confidence  TEXT,
+  created_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_choro_claims_page ON choro_claims(page_id);
+
+-- 向量壳（M1/M2 接 embedder 后灌）：owner_id 指向 choro_claims 或 choro_pages
+-- （spec §5 的多态指向）。向量与记忆向量不共表、不共查询——两边换模型版本的
+-- 节奏不同（V4 待实测项），混表会让其中一边被另一边的模型版本绑死。
+CREATE TABLE IF NOT EXISTS choro_vectors (
+  owner_id   INTEGER NOT NULL,
+  dim        INTEGER NOT NULL,
+  model      TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_vectors_owner_model ON choro_vectors(owner_id, model);
+
+-- 模块间依赖边（M1 补口，实现计划 P8）：spec §7 的 choro_module_map 要画依赖图，
+-- M0 schema 漏了这张。只记跨模块边（from_slug ≠ to_slug），模块内部边不进库——
+-- 模块页正文里已经有完整文件级清单，库只存图需要的那一层。
+CREATE TABLE IF NOT EXISTS choro_edges (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_id   INTEGER NOT NULL,
+  from_slug TEXT NOT NULL,
+  to_slug   TEXT NOT NULL,
+  weight    INTEGER NOT NULL DEFAULT 1
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_choro_edges_triple ON choro_edges(repo_id, from_slug, to_slug);
+CREATE INDEX IF NOT EXISTS idx_choro_edges_to ON choro_edges(repo_id, to_slug);
 `;
 
 // Exported for API-layer type validation (standalone API POST /memories and
@@ -1028,6 +1138,10 @@ export function createStore(path) {
   addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
   addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
 
+  // 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");
+
   // v0.8.0 A1（issue #17）scope 隔离存储层：四列全部可空、不带 DEFAULT——存量行
   // 零重写，读侧把 NULL 视为未标注（= 全局可见）。是否落值由 scopeEnabled 门控
   // （service/tools 层），存储层只负责归一化（normalizeScopeText/normalizeOccurredAt）。
@@ -1113,6 +1227,141 @@ export function createStore(path) {
     }
   }
 
+  // 一次性数据迁移 #1：撤回旧重复度度量的误判（#560 的收尾）。
+  //
+  // v0.7.12 起 repetitive 用的是「唯一字符数 ÷ 总长度 < 0.3」，这个比率随长度单调下降，
+  // 于是长中文记忆被系统性判成重复：本机 12,827 条里 800–2000 字的 94.3%、2000 字以上的
+  // 100% 命中。0.11.0 把度量换成 trigram 重复率（> 0.7），那只管住了**新写入**——
+  // evaluateMemoryQuality 全仓只有 service 的写路径一处调用，更新路径不重算 quality_score，
+  // 所以库里那批标签与扣分原封不动。
+  //
+  // 口径是「手术式撤销」，不是「整列重算」：整列重算会顺手重新裁一遍别人的分——实测会
+  // 新命中 90 条 meta 与 98 条 self_referential（判据没变、但评分当时没跑到这些行），
+  // 那是双向改写，越过了「只撤除被修掉的那个误判」的范围。这里只动带 repetitive 的行，
+  // 且必须**用新度量复算仍然不重复**才动；新度量下依旧 > 0.7 的是真重复，标签有效，保持原样。
+  //
+  // 分数据「只升不降」：重建值来自存活标签的扣分表，取 max(存量, 重建) 而不是直接取重建——
+  // 存量分不是纯标签函数（实测有 3 行与任何标签组合都对不上，历史上有信号被改路径抹掉过），
+  // 直接用重建值会把这批行往下压。这次迁移的理由是「它被误扣了 50」，只有加回去才对得上。
+  //
+  // 不碰 archived / archived_at / updated_at / content_hash / embedding，也不 bump
+  // generation：归档位是另一个决定（撤销归档 = 把 300 条重新放进注入池），不夹带在
+  // 「修分数」里；不刷 updated_at 则代表镜像不重排——代价是镜像文件里这些行的 tags 行
+  // 会显示已删掉的 repetitive，而 parseHumanEdits 不解析 tags，陈旧只停留在显示层、不回灌。
+  // 这层陈旧还会自己收敛：镜像每次 syncMirror 都是全量重渲染（store.list limit:null），
+  // 所以启动后第一次业务写就把这批行刷对了——为这几分钟专门接一条「打开库即全量重绘」
+  // 的路径，代价（新导出 syncMirror + createStore 回传标记 + 两个启动点各改一行）大于收益。
+  //
+  // 用 applied_migrations 登记而不是条件式恒等幂等：这批条件在跑完之后**恒不命中**，
+  // 但要全表扫一遍才能证明不命中（本机实测 36.7 ms，而 createStore 稳态只有 3.3 ms）——
+  // 每次打开都白付十倍开销。登记表把它变成一次主键 seek（PRAGMA user_version 做不到：
+  // 实测它在 BEGIN 里设值不随 ROLLBACK 回退，先置标记再回填会永久漏跑）。
+  //
+  // 回填分批提交、登记行最后单独提交，不做「一个大事务包住全部」：逐批提交才不会把
+  // 「候选行数 × 全文长度」攒在内存与一次 WAL 里；而这样拆之所以仍然安全，是因为
+  // **修过的行就不再是候选**（repetitive 已撤），中途崩掉重跑只会从断点接着走，不会
+  // 重复加回分数。登记行只认「全部批次都跑完、且没有一条被 CAS 挡下」，半截进度不落地。
+  {
+    const MIGRATION_ID = "2026-11-quality-repetitive-backfill";
+    const applied = db.prepare("SELECT 1 FROM applied_migrations WHERE id = ?").get(MIGRATION_ID);
+    if (!applied) {
+      // LIKE 只负责候选裁剪，真正的判据是下一段的 tags.includes("repetitive")——把
+      // LIKE 放松成 %repetitive% 也筛不出错误结果（变异自证里它是等价变异）。用带引号
+      // 的形态是为了缩小候选集、少解析几条将来可能出现的坏 JSON，不是为了防误伤。
+      // 按 rowid 键集翻页，每批独立提交：候选行带全文，一次 .all() 会把「行数 × 正文
+      // 长度」全攒在内存里（本机 1,476 条合计 726 KB，大库不是这个量级）。分批之所以
+      // 仍然安全，是因为候选集自己会收缩——修过的行撤掉 repetitive 就不再命中；
+      // 中途崩掉重跑只会从断点接着走，不会把已经加回去的分再加一遍。
+      const BATCH = 200;
+      const selectBatch = db.prepare(
+        `SELECT rowid AS rid, id, content, _full_content, tags, quality_score
+           FROM memories
+          WHERE tags LIKE '%"repetitive"%' AND rowid > ?
+          ORDER BY rowid
+          LIMIT ?`
+      );
+      // CAS：带上读到的旧 tags、旧 quality_score 与两列正文作为条件。多宿主共用一个库是
+      // 支持形态（busy_timeout + WAL），SELECT 到 UPDATE 之间别的进程可能刚改过这一行——
+      // 那就以它为准、跳过这一条，不拿这次读到的旧判断覆盖它。正文两列也要带：判据读的是
+      // 正文，只校验 tags/quality_score 时，正文被换成重复文本而另两列未变仍会 CAS 通过，
+      // 于是把本该保留的 repetitive 撤掉。
+      const stmt = db.prepare(
+        `UPDATE memories SET tags = ?, quality_score = ?
+          WHERE id = ? AND tags = ? AND quality_score IS ?
+            AND content IS ? AND _full_content IS ?
+            AND tags LIKE '%"repetitive"%'`
+      );
+      // CAS 落空的行这一趟没修到，它们仍是候选——那就别登记「已完成」，下次打开整条重跑
+      // （修过的行已不是候选，重跑天然幂等）。否则一条被别处同时改写而保留 repetitive 的行
+      // 会带着旧分与旧标签一直留在库里。
+      let casMisses = 0;
+      let cursor = 0;
+      for (;;) {
+        const rows = selectBatch.all(cursor, BATCH);
+        if (rows.length === 0) break;
+        cursor = rows[rows.length - 1].rid;
+        const updates = [];
+        for (const row of rows) {
+          let tags;
+          try {
+            tags = JSON.parse(row.tags);
+          } catch {
+            continue; // 坏 tags 不动：这条迁移不该顺手重写一个解析不了的值
+          }
+          if (!Array.isArray(tags) || !tags.includes("repetitive")) continue;
+          // 含非字符串元素的行整条放过：下面 Object.hasOwn 对对象元素会先做属性键转换，
+          // 抛 TypeError（JSON.parse('{"toString":1}') 这类值可达），而这里没有任何 catch，
+          // 异常会直接让 createStore 中止、迁移永远登不上记，下次打开原地再撞同一行。
+          if (!tags.every((t) => typeof t === "string")) continue;
+          // 判据落在**原文**上：已降级的行 content 只剩前 120 字摘要（demoteToSummary
+          // 把正文挪进 _full_content，且它不重算 quality_score），拿摘要判重复会把
+          // 「前缀不重复、后段大量重复」的原文放过去——而那恰好是旧度量最容易误判的
+          // 那一类。未降级的行 _full_content 为 NULL，退回 content，与原判据一致。
+          const body = String(row._full_content ?? row.content ?? "");
+          // 新度量下仍然重复 → 标签是对的，保持原样（不重算分数：那会变成整列重算）
+          if (repetitionRatio(body.trim()) > REPETITION_THRESHOLD) continue;
+          const kept = tags.filter((t) => t !== "repetitive");
+          let rebuilt = 100;
+          // 只减自有键：SIGNAL_DEDUCTIONS 是普通对象字面量，查「constructor」命中的
+          // 是原型链上的函数，`?? 0` 挡不住，会把分数算成 NaN 再写进列里。
+          for (const tag of kept) {
+            if (Object.hasOwn(SIGNAL_DEDUCTIONS, tag)) rebuilt -= SIGNAL_DEDUCTIONS[tag];
+          }
+          rebuilt = Math.max(0, Math.min(100, Math.round(rebuilt)));
+          const stored = Number.isFinite(row.quality_score) ? row.quality_score : null;
+          const score = stored === null ? rebuilt : Math.max(stored, rebuilt);
+          // low_quality 是分数的派生态（< 30 必须有、≥ 30 必须没有），分数动了它就跟着动。
+          // 显式同步而不是留给下次写入：不重算的路径不会自己把它修好。
+          const next = kept.filter((t) => t !== "low_quality");
+          if (score < 30) next.push("low_quality");
+          updates.push([
+            JSON.stringify(next),
+            score,
+            row.id,
+            row.tags,
+            row.quality_score,
+            row.content,
+            row._full_content
+          ]);
+        }
+        if (updates.length === 0) continue;
+        const batch = updates;
+        // 一批一个事务：逐条自动提交是每行一次 WAL 提交（与 content_hash 回填同一个教训）。
+        runAtomically(() => {
+          for (const u of batch) {
+            if (stmt.run(u[0], u[1], u[2], u[3], u[4], u[5], u[6]).changes === 0) casMisses += 1;
+          }
+        });
+      }
+      // 登记行单独提交，且只在**所有批次都跑完、且没有一条 CAS 落空**之后：它是「这条迁移
+      // 已完成」的证据，半截进度不能落地，否则重跑会被自己挡住、剩下的行再也修不回来。
+      const mark = db.prepare("INSERT OR IGNORE INTO applied_migrations (id, applied_at) VALUES (?, ?)");
+      // 时间戳这里直接用 new Date()：nowIso 的单调守卫是给 memories.updated_at 用的，
+      // 而且它依赖的 lastTs 此刻还没初始化（TDZ），调它会在打开库时直接抛。
+      if (casMisses === 0) runAtomically(() => mark.run(MIGRATION_ID, new Date().toISOString()));
+    }
+  }
+
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
   addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
@@ -2857,6 +3106,84 @@ export function createStore(path) {
     };
   }
 
+  /**
+   * 沉淀曲线（面板「8 周沉淀」图）：按天给出「进来的」与「真沉淀的」两条序列，
+   * 用来一眼看出库到底在巩固还是在膨胀——只看新增会以为一直在长，只看总量
+   * 看不出巩固停摆（2026-10-25~10-31 那段新增照旧、合并归零，就是这张图要
+   * 暴露的形态）。
+   *
+   * added    = 当天新建记忆。排除外来导入行（本库不为别人导入的原文记账，
+   *            见 memory-source.js）；`source IS NULL OR` 那一支是必填——
+   *            SQL 三值逻辑让 `NULL <> 'imported'` 求值为 NULL 而非 true，
+   *            只写后者的版本会让本方行（source 恒为 NULL）整批消失。
+   * merged   = 当天 receipt_chain 里 kind∈(merge,update) 且 verdict='live' 的
+   *            **去重 record_id 数**，不是行数。同一条记录被多轮巩固重复记账
+   *            是常态（活库实测 2412 行只对应 1796 个记录，见 #559 期间的
+   *            核对），按行数会把「又记了一遍」算成「又沉淀了一条」。口径与
+   *            store 里「已巩固」的既有子查询同源（kind IN ('merge','update')
+   *            AND verdict='live'），不另立一套。
+   * archived = 当天进入归档面的条数（archived_at 幂等，见其注释：已归档再
+   *            归档不刷新，取消归档置 NULL），所以日聚合 = 当天新归档条数。
+   *
+   * 三列都按 UTC 日期切分，与 getLlmAuditStats 的 by_day 同一套日期口径，
+   * 前端补零/对齐逻辑因此可以复用。
+   *
+   * 只返回有数据的日期（GROUP BY 不补零），与 by_day 同形——补零是展示层的事，
+   * 后端补零会让「未知」和「已知为空」在响应里长得一样。
+   */
+  function getConsolidationStats({ days = 56 } = {}) {
+    const span = Math.max(1, Math.min(365, Math.floor(Number(days)) || 56));
+    const since = new Date(Date.now() - span * 86400000).toISOString();
+    const added = db.prepare(
+      `SELECT date(created_at) AS day, count(*) AS c
+         FROM memories
+        WHERE created_at >= ? AND (source IS NULL OR source <> ?)
+        GROUP BY date(created_at) ORDER BY day ASC`
+    ).all(since, IMPORTED_SOURCE);
+    const merged = db.prepare(
+      `SELECT day, count(*) AS c FROM (
+         SELECT date(created_at) AS day, record_id
+           FROM receipt_chain
+          WHERE created_at >= ? AND kind IN ('merge', 'update') AND verdict = 'live'
+          GROUP BY day, record_id
+       ) GROUP BY day ORDER BY day ASC`
+    ).all(since);
+    const archived = db.prepare(
+      `SELECT date(archived_at) AS day, count(*) AS c
+         FROM memories
+        WHERE archived_at IS NOT NULL AND archived_at >= ? AND (source IS NULL OR source <> ?)
+        GROUP BY date(archived_at) ORDER BY day ASC`
+    ).all(since, IMPORTED_SOURCE);
+    // 三串按天并进一张表：三条 SQL 各扫各的索引，比一次 UNION + 外层聚合好读，
+    // 也让某一段全 0 时不会因为缺行而丢掉这一天（缺的是 0，不是不存在）。
+    const byDay = new Map();
+    const bump = (rows, key) => {
+      for (const r of rows) {
+        const day = String(r.day ?? "");
+        if (!day) continue;
+        const cur = byDay.get(day) ?? { day, added: 0, merged: 0, archived: 0 };
+        cur[key] = Number(r.c) || 0;
+        byDay.set(day, cur);
+      }
+    };
+    bump(added, "added");
+    bump(merged, "merged");
+    bump(archived, "archived");
+    const list = [...byDay.values()].sort((a, b) => (a.day < b.day ? -1 : a.day > b.day ? 1 : 0));
+    const sum = list.reduce(
+      (acc, r) => ({ added: acc.added + r.added, merged: acc.merged + r.merged, archived: acc.archived + r.archived }),
+      { added: 0, merged: 0, archived: 0 }
+    );
+    return {
+      days: span,
+      since,
+      by_day: list,
+      total_added: sum.added,
+      total_merged: sum.merged,
+      total_archived: sum.archived
+    };
+  }
+
   /** Delete audit rows older than `before` (ISO string). Returns count removed. */
   function deleteOldLlmAudits(before) {
     return db.prepare("DELETE FROM llm_audit_logs WHERE timestamp < ?").run(before).changes;
@@ -3926,6 +4253,16 @@ export function createStore(path) {
     return rows.map(toEntity);
   }
 
+  /**
+   * 实体总行数（全库，不受 limit 影响）。目录路由的 `total` 必须走这里：
+   * 它此前填的是 `entities.length`（本次切片长度），于是库里一万六千个实体
+   * 在面板上永远显示 500 —— 数字看着像"实体太少"，其实是被上限截断了。
+   * 与 listEntities 同源同表，只差一个 COUNT。
+   */
+  function countEntities() {
+    return db.prepare("SELECT COUNT(*) AS n FROM entities").get().n;
+  }
+
   // --- 图召回轴（issue #219）-------------------------------------------------
 
   /**
@@ -4215,6 +4552,161 @@ export function createStore(path) {
     });
   }
 
+  /* --------------------- chorography（仓库地志，M0 只写不读） --------------------- */
+  // 消费面（检索 / 注入）在 M1 才接，这里只落写入口。时间戳由调用方传：一次 run
+  // 的所有行共用同一个时刻（生成的页正文里也引用它），由 t0.js 的单一时钟保证，
+  // store 不自取 now()——两处时钟会把「同一 run」拆成两个版本。
+
+  function choroRepoByRoot(rootPath) {
+    return db.prepare("SELECT * FROM choro_repos WHERE root_path = ?").get(rootPath) ?? undefined;
+  }
+
+  // 登记或刷新仓库行。created_at 只在首次插入时落（ON CONFLICT 不碰它）；
+  // plan_fingerprint / git_baseline 永远反映上次成功 run——失败 run 不写这两格
+  // （红线 5「失败不推进 state」，库侧与 state.json 同一口径）。
+  function upsertChoroRepo(rootPath, name, planFingerprint, gitBaseline, updatedAt) {
+    db.prepare(
+      `INSERT INTO choro_repos (root_path, name, plan_fingerprint, git_baseline, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(root_path) DO UPDATE SET
+         name = excluded.name,
+         plan_fingerprint = excluded.plan_fingerprint,
+         git_baseline = excluded.git_baseline,
+         updated_at = excluded.updated_at`
+    ).run(rootPath, name, planFingerprint, gitBaseline, updatedAt, updatedAt);
+    return choroRepoByRoot(rootPath);
+  }
+
+  // 整仓替换（实现计划 P7）：一次成功 run 的模块/页面/claims 全量重写。幂等语义
+  // 在这里成型：重跑同一划分 = 删了重插同样内容，行不翻倍；划分变了也不会留孤儿行
+  // （旧模块的页面与 claims 随模块一起删）。事务包住删除与插入，半截失败整体回滚，
+  // 库里保持上一次成功 run 的完整图。
+  // 父链两段式落（先全插再补 parent_id）：父模块的行号在插入前不存在，按 slug 排序
+  // 的单遍插入会遇到「父在后」的顺序问题，两段式与顺序无关。
+  function replaceChoroGraph(repoId, snapshot) {
+    return runAtomically(() => {
+      db.prepare(
+        `DELETE FROM choro_claims WHERE page_id IN (
+           SELECT p.id FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+           WHERE m.repo_id = ?)`
+      ).run(repoId);
+      db.prepare(
+        "DELETE FROM choro_pages WHERE module_id IN (SELECT id FROM choro_modules WHERE repo_id = ?)"
+      ).run(repoId);
+      db.prepare("DELETE FROM choro_edges WHERE repo_id = ?").run(repoId);
+      db.prepare("DELETE FROM choro_modules WHERE repo_id = ?").run(repoId);
+
+      const insModule = db.prepare(
+        `INSERT INTO choro_modules (repo_id, slug, title, parent_id, file_count, fingerprint, updated_at)
+         VALUES (?, ?, ?, NULL, ?, ?, ?)`
+      );
+      const ids = new Map();
+      for (const mod of snapshot.modules) {
+        const info = insModule.run(
+          repoId, mod.slug, mod.title, mod.fileCount, mod.fingerprint, snapshot.updatedAt
+        );
+        ids.set(mod.slug, Number(info.lastInsertRowid));
+      }
+      const setParent = db.prepare("UPDATE choro_modules SET parent_id = ? WHERE id = ?");
+      for (const mod of snapshot.modules) {
+        if (mod.parentSlug == null) continue;
+        const parentId = ids.get(mod.parentSlug);
+        if (parentId != null) setParent.run(parentId, ids.get(mod.slug));
+      }
+
+      const insPage = db.prepare(
+        `INSERT INTO choro_pages
+           (module_id, rel_path, status, git_baseline, template_version, generated_at, human_block_count)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      );
+      const insClaim = db.prepare(
+        `INSERT INTO choro_claims
+           (page_id, statement, kind, source_path, start_line, end_line, confidence, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      );
+      for (const page of snapshot.pages) {
+        const moduleId = ids.get(page.moduleSlug);
+        if (moduleId == null) continue; // 划分与页面同源生成，走到这里说明调用方组装错了
+        const pageInfo = insPage.run(
+          moduleId, page.relPath, page.status, page.gitBaseline,
+          page.templateVersion, page.generatedAt, page.humanBlockCount
+        );
+        for (const claim of page.claims ?? []) {
+          insClaim.run(
+            Number(pageInfo.lastInsertRowid), claim.statement, claim.kind,
+            claim.sourcePath ?? null, claim.startLine ?? null, claim.endLine ?? null,
+            claim.confidence ?? null, snapshot.updatedAt
+          );
+        }
+      }
+      // 跨模块边（P8）：from/to 都是模块 slug，只存 from≠to 的；同向多条文件级
+      // 边聚合为一条带 weight 的模块级边。
+      const insEdge = db.prepare(
+        "INSERT INTO choro_edges (repo_id, from_slug, to_slug, weight) VALUES (?, ?, ?, ?)"
+      );
+      let edgeCount = 0;
+      for (const edge of snapshot.edges ?? []) {
+        if (edge.fromSlug === edge.toSlug) continue;
+        insEdge.run(repoId, edge.fromSlug, edge.toSlug, edge.weight ?? 1);
+        edgeCount++;
+      }
+      return { modules: snapshot.modules.length, pages: snapshot.pages.length, edges: edgeCount };
+    });
+  }
+
+  // T1 的页级读写（实现计划 P16–P18）：与 replaceChoroGraph 的整仓替换并存——
+  // T1 是逐模块的（一轮只动一页），整仓替换会把其他页的富化状态抹掉。
+  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
+         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));
+  }
+
+  // 单页失败记账（spec 步 12「失败两次即记 failed」）：首次失败只计数、状态不动
+  // （骨架仍是当前有效产物），第二次到阈值才把 status 推成 failed。generatedAt
+  // 不动——失败不推进 state（红线 5）的页级口径。
+  function recordChoroPageFailure(pageId, failThreshold = 2) {
+    db.prepare("UPDATE choro_pages SET fail_count = fail_count + 1 WHERE id = ?").run(pageId);
+    const row = db.prepare("SELECT fail_count, status FROM choro_pages WHERE id = ?").get(pageId);
+    if (row.fail_count >= failThreshold) {
+      db.prepare("UPDATE choro_pages SET status = 'failed' WHERE id = ?").run(pageId);
+      row.status = "failed";
+    }
+    return row;
+  }
+
+  // 富化成功：skeleton → enriched，generatedAt 推进、失败计数清零（成功重置的是
+  // 「连续失败」的连续性，不是历史）。
+  function markChoroPageEnriched(pageId, generatedAt) {
+    db.prepare(
+      "UPDATE choro_pages SET status = 'enriched', generated_at = ?, fail_count = 0 WHERE id = ?"
+    ).run(generatedAt, pageId);
+  }
+
+  // 单页 claims 整页替换（P20 的表侧）：T1 一轮产出的 claims 删旧插新；evidence/
+  // JSON 由 t1.js 同步写盘（两处同源同写）。
+  function saveChoroPageClaims(pageId, claims) {
+    return runAtomically(() => {
+      db.prepare("DELETE FROM choro_claims WHERE page_id = ?").run(pageId);
+      const ins = db.prepare(
+        `INSERT INTO choro_claims
+           (page_id, statement, kind, source_path, start_line, end_line, confidence, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+      );
+      for (const claim of claims) {
+        ins.run(
+          pageId, claim.statement, claim.kind,
+          claim.sourcePath ?? null, claim.startLine ?? null, claim.endLine ?? null,
+          claim.confidence ?? null, claim.createdAt
+        );
+      }
+      return claims.length;
+    });
+  }
+
   return {
     db,
     count,
@@ -4294,6 +4786,7 @@ export function createStore(path) {
     listLlmAudits,
     countLlmAudits,
     getLlmAuditStats,
+    getConsolidationStats,
     deleteOldLlmAudits,
     // 蒸馏原始记录与记忆级溯源（#399）：窗口凭证的写入/统计/裁剪，链接的读写。
     saveDistillRecords,
@@ -4344,6 +4837,7 @@ export function createStore(path) {
     findEntityByName,
     findEntityById,
     listEntities,
+    countEntities,
     updateEntity,
     saveAttr,
     invalidateOldAttr,
@@ -4378,6 +4872,14 @@ export function createStore(path) {
     getContinuityProposal,
     listContinuityProposals,
     countContinuityProposals,
+    // chorography（仓库地志）：M0 只写不读，消费面 M1 接（见上面注释块）。
+    choroRepoByRoot,
+    upsertChoroRepo,
+    replaceChoroGraph,
+    choroPageBySlug,
+    recordChoroPageFailure,
+    markChoroPageEnriched,
+    saveChoroPageClaims,
     close() {
       db.close();
     }