@modusensus/dsh-mneme 0.10.1 → 0.12.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
@@ -269,6 +287,29 @@ CREATE TABLE IF NOT EXISTS scope_state (
 -- 它同时是 setScopeState 那条 UPSERT 的冲突目标，所以不能省。
 CREATE UNIQUE INDEX IF NOT EXISTS idx_scope_state_key ON scope_state(dimension, scope_value);
 
+-- pinned_memories: #249 第二批，显式 pin。旧口径把「类型是 constraint/preference」
+-- 当成 pin（隐含假设），于是 1163 条自动变「每轮必进」而预算只有 5——池子本身
+-- 就太大，靠相关性排序永远轮不到「署名」「拒绝谄媚」这类稳定偏好。本表把
+-- 「哪些是用户亲手钉的」变成一条显式事实：注入侧只认这张表，不再认类型。
+--
+-- 为什么是独立表而不是 memories 的布尔列：回退只需一条 DROP，不碰 31 列的主表；
+-- 且「pin 是用户与记忆之间的一条关系」天然是关系表——created_at 还能给出
+-- pin 顺序（按 pin 先后注入，而不是按「最近改过」）。外泄面天然为零：
+-- mirror/share 都不 SELECT 本表，pin 标记不会出现在导出物里。
+--
+-- 幂等靠 CREATE TABLE IF NOT EXISTS（本文件其余建表同款），不登记
+-- applied_migrations——那是给「跑完恒不命中却仍要全表扫一遍」的 data migration
+-- 用的，本表没有回填步骤。存量库升级后本表为空，注入侧据此回落到旧的类型口径
+-- （见 service.injectCandidates 的 type-fallback 分支），升级即等价。
+CREATE TABLE IF NOT EXISTS pinned_memories (
+  memory_id  TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL,
+  note       TEXT
+);
+-- 按 pin 顺序注入要读 created_at 全序；本表行数以「人手钉的条数」计（个位到几十），
+-- 索引只为把排序的临时 B 树换成一次有序扫，不承担过滤。
+CREATE INDEX IF NOT EXISTS idx_pinned_created ON pinned_memories(created_at);
+
 -- llm_audit_logs: every background LLM call (autoDream consolidation + summary,
 -- autoSummarize compression) is recorded here — tokens in/out, duration, status
 -- and the trigger that caused it (Bug8). Failures are captured as status='error'
@@ -516,6 +557,155 @@ 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);
+
+-- 向量壳（收尾档 P36/P38 落地）：owner_id 指向 choro_pages（v1 只做页级；
+-- claims 级留待真有精排需求）。向量与记忆向量不共表、不共查询——两边换模型
+-- 版本的节奏不同（V4 的答案在此：model/dim 记行内，**不锁死**——dim 失配 =
+-- 惰性全量重嵌，代价只是几十页重嵌而不是作废记忆向量）。
+-- vector 存 JSON 数组（与 memories.embedding 同款 TEXT 形态）；source_generated_at
+-- 记嵌入时刻页面的 generated_at——页面富化/重建后该值变化，检索侧据此判 staleness。
+CREATE TABLE IF NOT EXISTS choro_vectors (
+  owner_id            INTEGER NOT NULL,
+  dim                 INTEGER NOT NULL,
+  model               TEXT NOT NULL,
+  vector              TEXT,
+  source_generated_at TEXT,
+  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);
+
+-- profile_facts：「Agent 眼中的你」自动事实（2026-11-06 需求，对标 DS Bot 每 bot
+-- 一份 MEMORY.md 事实清单的设计）。与手填画像（user_settings.profile）**物理分离**
+-- ——那是用户的原文，模型只有读权（profile-extract #497 的「只出草稿不落库」口径
+-- 不变）；本表是 agent 侧对用户的独立认知，模型可在 dream 轮里增改、用户可在面板
+-- 上逐条修正。agent_key='' 是 default 卡（解析不到会话身份的会话），非空值是会话
+-- 身份，与 persona byAgent 同一取值域（session.header.agentPreset）。
+-- 输入行严格分区不互串：agent 卡只吃 agent_scope=自己 的记忆行，default 卡只吃
+-- agent_scope IS NULL 的行；外来行（source=imported）整体排除（memory-source.js
+-- 那条「本库不巩固别人导入的原文」延伸到画像事实：导入的包不该改写本库对用户的认知）。
+CREATE TABLE IF NOT EXISTS profile_facts (
+  id                TEXT PRIMARY KEY,
+  agent_key         TEXT NOT NULL DEFAULT '',
+  content           TEXT NOT NULL,
+  status            TEXT NOT NULL DEFAULT 'active',  -- active | archived
+  source_memory_ids TEXT NOT NULL DEFAULT '[]',      -- JSON：这条事实的出处记忆 id
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_profile_facts_card ON profile_facts(agent_key, status);
+
+-- 逐 op 账本（scope_changes 式）：谁（auto 轮 / 面板人工）、何时、把哪条事实从什么
+-- 改成了什么。审计纪律同 dream_runs / llm_audit_logs：只记账，不触发任何 hook。
+CREATE TABLE IF NOT EXISTS profile_fact_journal (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  at        TEXT NOT NULL,
+  agent_key TEXT NOT NULL DEFAULT '',
+  run_id    TEXT,                                -- auto 轮的回执 id；人工操作为 NULL
+  fact_id   TEXT,
+  op        TEXT NOT NULL,                       -- add | update | archive | restore | delete
+  before    TEXT,
+  after     TEXT,
+  actor     TEXT NOT NULL DEFAULT 'auto'         -- auto | manual
+);
+CREATE INDEX IF NOT EXISTS idx_profile_fact_journal_card ON profile_fact_journal(agent_key, id);
+
+-- 每轮回执（dream_runs 式）：游标（该卡消费到 memories.updated_at 的哪一刻）、
+-- 输入条数、落地 op 数。游标从最近一次 ok 轮读取——failed 轮不推进游标，下次
+-- 重跑同一窗口（与蒸馏游标同款纪律：失败不消费）。
+CREATE TABLE IF NOT EXISTS profile_fact_runs (
+  id             TEXT PRIMARY KEY,
+  agent_key      TEXT NOT NULL DEFAULT '',
+  trigger_source TEXT NOT NULL,                   -- auto | manual
+  status         TEXT NOT NULL,                   -- ok | noop | failed
+  cursor         TEXT,                            -- 本轮消费到的 memories.updated_at
+  input_count    INTEGER NOT NULL DEFAULT 0,
+  ops_applied    INTEGER NOT NULL DEFAULT 0,
+  detail         TEXT,
+  started_at     TEXT NOT NULL,
+  finished_at    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_profile_fact_runs_card ON profile_fact_runs(agent_key, started_at);
 `;
 
 // Exported for API-layer type validation (standalone API POST /memories and
@@ -820,6 +1010,17 @@ function toScopeState(row) {
   };
 }
 
+// pinned_memories 行 → 读侧对象（#249 第二批）。NULL note 落 undefined，
+// 与 toScopeState 同口径。
+function toPinned(row) {
+  if (!row) return undefined;
+  return {
+    memory_id: row.memory_id,
+    created_at: row.created_at,
+    note: row.note ?? undefined
+  };
+}
+
 function toRecallRun(row) {
   if (!row) return undefined;
   return {
@@ -1028,6 +1229,14 @@ 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");
+  // chorography 收尾档（P36）：v0.11.0 的 choro_vectors 是空壳表（spec §5 漏了
+  // 向量本体列），存量库经 PRAGMA 检查补列。
+  addColumn("choro_vectors", "vector", "ALTER TABLE choro_vectors ADD COLUMN vector TEXT");
+  addColumn("choro_vectors", "source_generated_at", "ALTER TABLE choro_vectors ADD COLUMN source_generated_at TEXT");
+
   // v0.8.0 A1（issue #17）scope 隔离存储层：四列全部可空、不带 DEFAULT——存量行
   // 零重写，读侧把 NULL 视为未标注（= 全局可见）。是否落值由 scopeEnabled 门控
   // （service/tools 层），存储层只负责归一化（normalizeScopeText/normalizeOccurredAt）。
@@ -1113,6 +1322,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'");
@@ -1170,28 +1514,71 @@ export function createStore(path) {
   // Issue #202：embedding 解析缓存。检索路径此前每次调用都对全部带向量行
   // JSON.parse（993 × 512 维 ≈ 48 ms/次，且 SQL 拖着 10 MB 的 TEXT），余弦本身
   // 只占 3%。向量只经 setEmbedding 写入（单一失效点），把解析结果按 id 缓存，
-  // 命中即零解析；上限 FIFO 驱逐防大库内存无界（4000 × 512 维 double ≈ 16 MB）。
+  // 命中即零解析。
+  //
+  // 上限为什么不能是固定常量（2026-11-05 实测）：上限 4000、活跃带向量行 6685，
+  // 扫到第 4001 条开始驱逐自己刚填的条目，扫完只剩最后 4000 条，下一轮又从第
+  // 一条 miss——四轮实测命中率恒 0.0%，缓存等于不存在，每次检索都全量重解析
+  // （实测 624 ms）。固定调大只是把复发推到下个月（活跃行近 30 天净增 6156 条，
+  // 上限 20000 也只撑到 2027-01-09），所以上限跟工作集自适应：
+  //   · 每次全量扫（searchVector / vectorDimensionState）在循环前把上限抬到
+  //     「本次扫到的行数 ×1.25」，一次扫完不会被自己的驱逐打断；
+  //   · 内存预算封顶（默认 256 MB），超预算的行仍按 FIFO 驱逐——大库退化回
+  //     「部分命中」，不会无界吃内存。
+  // 存储用 Float32Array。同一口径（GC 后 heapUsed + arrayBuffers，6730 条
+  // 1024 维全常驻）实测：number[] 56.4MB → Float32Array 29.7MB（heap 1.9 +
+  // arrayBuffers 27.8），省 26.7MB / 47%。注意 heapUsed 不统计 TypedArray 的
+  // 底层 ArrayBuffer，只看 heapUsed 会读成「省 96%」的假象；旧实现若保持上限
+  // 4000 则装不下工作集（常驻 31.9MB 但命中率 0%），两者不可比，所以对照组是
+  // 把旧上限抬到 20000 让工作集全常驻。cosine 全量 25.4ms → 18.0ms，前 50 条
+  // 排序精度差 0.00e+0。对外契约不变：
+  // getParsedEmbedding / getEmbeddings 仍返回 number[]，只有内部热路径
+  // （readVector）拿 Float32Array。
   const embeddingCache = new Map();
-  const EMBEDDING_CACHE_MAX = 4000;
+  const EMBEDDING_CACHE_FLOOR = 4000;
+  const EMBEDDING_CACHE_BUDGET_BYTES = 256 * 1024 * 1024;
+  let embeddingCacheCap = EMBEDDING_CACHE_FLOOR;
+  let embeddingCacheHits = 0;
+  let embeddingCacheMisses = 0;
+
+  /** Vector-like = number[] or Float32Array (typed). All cosine guards use this
+   *  instead of Array.isArray, which is false for typed arrays — with the old
+   *  guard every cached vector would silently score 0. */
+  function isVectorLike(v) {
+    return Array.isArray(v) || (ArrayBuffer.isView(v) && !(v instanceof DataView));
+  }
 
   function cacheEmbedding(id, vector) {
-    if (embeddingCache.size >= EMBEDDING_CACHE_MAX && !embeddingCache.has(id)) {
+    if (embeddingCache.size >= embeddingCacheCap && !embeddingCache.has(id)) {
       const oldest = embeddingCache.keys().next().value;
       embeddingCache.delete(oldest);
     }
     embeddingCache.set(id, vector);
   }
 
-  /** Parsed embedding for one id (cache-first); undefined when none/parse
-   *  failure. Single read path shared by searchVector / getEmbedding(s). */
-  function getParsedEmbedding(id) {
+  /** Raise the cap to fit a sweep of `rows` rows (×1.25 headroom), clamped by
+   *  the memory budget. Called before a full scan so the scan itself does not
+   *  evict what it just cached. */
+  function noteSweep(rows, avgDim) {
+    if (!rows || !avgDim) return;
+    const perVector = avgDim * Float32Array.BYTES_PER_ELEMENT;
+    const budgetRows = Math.floor(EMBEDDING_CACHE_BUDGET_BYTES / perVector);
+    const want = Math.ceil(rows * 1.25);
+    embeddingCacheCap = Math.max(EMBEDDING_CACHE_FLOOR, Math.min(budgetRows, want));
+  }
+
+  /** Cache-first read returning Float32Array (internal hot path only).
+   *  undefined when none/parse failure. */
+  function readVector(id) {
     const cached = embeddingCache.get(id);
-    if (cached) return cached;
+    if (cached) { embeddingCacheHits += 1; return cached; }
+    embeddingCacheMisses += 1;
     const row = db.prepare("SELECT embedding FROM memories WHERE id = ?").get(id);
     if (!row?.embedding) return undefined;
     try {
-      const v = JSON.parse(row.embedding);
-      if (Array.isArray(v) && v.length) {
+      const parsed = JSON.parse(row.embedding);
+      if (Array.isArray(parsed) && parsed.length) {
+        const v = new Float32Array(parsed);
         cacheEmbedding(id, v);
         return v;
       }
@@ -1199,6 +1586,27 @@ export function createStore(path) {
     return undefined;
   }
 
+  /** Parsed embedding for one id (cache-first); undefined when none/parse
+   *  failure. Single read path shared by searchVector / getEmbedding(s).
+   *  Public contract: returns number[] (callers guard with Array.isArray). */
+  function getParsedEmbedding(id) {
+    const v = readVector(id);
+    return v ? Array.from(v) : undefined;
+  }
+
+  /** Cache instrumentation for the regression lock (hit rate must not collapse
+   *  back to 0 when the working set outgrows a fixed cap). */
+  function embeddingCacheStats() {
+    const total = embeddingCacheHits + embeddingCacheMisses;
+    return {
+      size: embeddingCache.size,
+      cap: embeddingCacheCap,
+      hits: embeddingCacheHits,
+      misses: embeddingCacheMisses,
+      hitRate: total ? embeddingCacheHits / total : 0
+    };
+  }
+
   // all()/list() 的显式列清单：从实际 schema 派生（迁移后），只排除 embedding
   // 列——consolidation/sleep/inject 的消费方都不读向量，而它是全表里最重的一列
   // （5k 行库 ≈ 9.4 MB TEXT），每次全表调用都白搬。经 PRAGMA 派生而非硬编码，
@@ -1634,6 +2042,11 @@ export function createStore(path) {
       db.prepare("DELETE FROM memory_provenance WHERE memory_id = ?").run(id);
       // #512：铸造记录同理——它也只是指着记忆行的索引，行没了索引就没有指代对象。
       db.prepare("DELETE FROM memory_mints WHERE memory_id = ?").run(id);
+      // #249 第二批：pin 行同理，理由与前两条完全一致（本表建表时也没抄
+      // REFERENCES ... ON DELETE CASCADE，清理不挂驱动默认）。注意这一条**只
+      // 防攒垃圾**，不修「回落被卡住」——注入侧判据看的是「有几条能用的」
+      // 而不是「表里有几行」，见 service.js 注入段与 pinnedStats.source 三档。
+      db.prepare("DELETE FROM pinned_memories WHERE memory_id = ?").run(id);
       db.prepare("DELETE FROM memories WHERE id = ?").run(id);
       // Mirror sync must reflect the deletion; bump desired generation so a
       // crash between the delete and syncMirror leaves a recoverable debt.
@@ -1701,6 +2114,8 @@ export function createStore(path) {
         const marks = chunk.map(() => "?").join(", ");
         db.prepare(`DELETE FROM memory_provenance WHERE memory_id IN (${marks})`).run(...chunk);
         db.prepare(`DELETE FROM memory_mints WHERE memory_id IN (${marks})`).run(...chunk);
+        // 同 remove()：pin 行防攒垃圾（不修卡回落的那个判据问题）。
+        db.prepare(`DELETE FROM pinned_memories WHERE memory_id IN (${marks})`).run(...chunk);
         deleted += db.prepare(`DELETE FROM memories WHERE id IN (${marks})`).run(...chunk).changes;
       }
       incrementGeneration();
@@ -2062,7 +2477,10 @@ export function createStore(path) {
    *  name; omitting modelHash leaves the column untouched (callers that
    *  predate the column still work, their rows simply read as unknown). */
   function setEmbedding(id, vector, modelHash) {
-    const json = Array.isArray(vector) && vector.length ? JSON.stringify(vector) : null;
+    // isVectorLike 而非 Array.isArray：调用方可能递进 Float32Array（本模块缓存的
+    // 就是它）。旧守卫对 typed array 返回 false，会把「设置向量」读成「清空向量」，
+    // 静默把行改成 NULL。
+    const json = isVectorLike(vector) && vector.length ? JSON.stringify(Array.from(vector)) : null;
     if (json) {
       if (modelHash !== undefined) {
         db.prepare("UPDATE memories SET embedding = ?, embedding_model = ? WHERE id = ?")
@@ -2075,15 +2493,10 @@ export function createStore(path) {
     }
     // Issue #202：单一写入口即单一失效点——重写缓存条目（向量在手上不必重解析），
     // 清空则移除，删除过的 id 不会被下一次 searchVector 的 id 集合选中。
-    if (json) {
-      try {
-        const parsed = JSON.parse(json);
-        if (Array.isArray(parsed) && parsed.length) cacheEmbedding(id, parsed);
-        else embeddingCache.delete(id);
-      } catch { embeddingCache.delete(id); }
-    } else {
-      embeddingCache.delete(id);
-    }
+    // 缓存里存 Float32Array（与 readVector 同一表示），不存 JSON.parse 出来的
+    // number[]，否则写后第一次读还要再转一次。
+    if (json) cacheEmbedding(id, new Float32Array(vector));
+    else embeddingCache.delete(id);
   }
 
   /** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
@@ -2244,18 +2657,21 @@ export function createStore(path) {
    */
   function vectorDimensionState(dimension) {
     if (!Number.isInteger(dimension) || dimension <= 0) return { state: "invalid" };
-    // 与 searchVector 的 WHERE 谓词逐条相同（顺序不同、语义等价）——同源行集，同步改。
+    // 与 searchVector 的行集逐条相同（顺序不同、语义等价）——同源行集，同步改。
+    // 同样不带 `embedding != ''`：只取 id，读 embedding 列纯属白搬；空串行由
+    // readVector 返回 undefined，落到下面 sawVector 分支（不影响 unreadable 判定）。
     const rows = db.prepare(
       `SELECT id FROM memories
-       WHERE embedding IS NOT NULL AND embedding != ''
+       WHERE embedding IS NOT NULL
          AND forgotten = 0 AND archived = 0`
     ).all();
     if (!rows.length) return { state: "none" };
     let sawVector = false;
+    noteSweep(rows.length, dimension);
     for (const row of rows) {
-      // 走 getParsedEmbedding 的解析缓存，不自己 JSON.parse——与 searchVector /
-      // getEmbedding(s) 同一条读路径，缓存热时零解析。
-      const v = getParsedEmbedding(row.id);
+      // 走同一解析缓存，不自己 JSON.parse——与 searchVector / getEmbedding(s)
+      // 同一条读路径，缓存热时零解析。
+      const v = readVector(row.id);
       if (!v || !v.length) continue;
       sawVector = true;
       if (v.length === dimension) return { state: "match" };
@@ -2289,7 +2705,7 @@ export function createStore(path) {
   // --- vector search ------------------------------------------------------
 
   function cosine(a, b) {
-    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    if (!isVectorLike(a) || !isVectorLike(b) || a.length !== b.length || !a.length) return 0;
     let dot = 0;
     let na = 0;
     let nb = 0;
@@ -2312,13 +2728,22 @@ export function createStore(path) {
     // Issue #202：只取 id 列（~40 KB）而非 SELECT *（~11 MB）——向量从缓存取，
     // 缓存未命中时按 id 点查 embedding 再解析回填。SQL 里保留 embedding 的
     // IS NOT NULL 过滤，保证「有向量的行」集合始终以库为准（删除/清空即时生效）。
+    //
+    // 为什么不带 `embedding != ''`（2026-11-05 实测）：`!= ''` 要读 embedding 列
+    // 才能判定，SQLite 就得把 134MB 向量文本整个从磁盘搬一遍——而这里只 SELECT
+    // id，一条文本都不用。真库副本实测：这条 SQL 单独跑 265ms → 96ms；落到
+    // 一轮完整检索上是 138ms → 47ms（省约 90ms，其余是解析/打分开销）。
+    // 空串行（外部直接 UPDATE 造出来的，setEmbedding 写的是 NULL）由 readVector
+    // 兜住：JSON.parse('') 抛错 → 返回 undefined → 跳过，既不计分也不崩。
     const rows = db.prepare(
       `SELECT id FROM memories
-       WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL AND embedding != ''`
+       WHERE ${archivedFilter}forgotten = 0 AND embedding IS NOT NULL`
     ).all();
     const scored = [];
+    // 自适应上限：本次要扫这么多行，先让缓存装得下，否则会边扫边驱逐自己。
+    noteSweep(rows.length, vector.length);
     for (const row of rows) {
-      const v = getParsedEmbedding(row.id);
+      const v = readVector(row.id);
       if (!v) continue;
       // distill-tx-embed-gap 顺带修：维度不匹配的行按维度分流，直接跳过。旧路径
       // 喂进 cosine 不等长就 return 0，换了模型/维度的旧向量以 0 分混进结果尾部
@@ -2857,6 +3282,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;
@@ -3477,6 +3980,85 @@ export function createStore(path) {
     return rows.map(toScopeState);
   }
 
+  // --- pinned_memories: 显式 pin（#249 第二批） ------------------------------
+  // 四个函数只管「哪条被钉住了」这条事实，不回答「该不该注入」——注入侧的
+  // 越权/暂停作用域/遗忘判定一律留在 service（与 strictScope、scopeStateGate
+  // 同处，见 injectCandidates 的位置纪律）。存储层越薄，越不会被绕过。
+
+  /**
+   * 全部 pin 行，按 pin 先后（created_at ASC）——注入就按这个序前置，**先钉的
+   * 排在最前**。预算不够（钉的条数 > pinnedInjectBudget）时，被 eligible.slice
+   * 取走的是最早钉的那几条，最近才钉的排后面、先被挤掉。
+   *
+   * 这个方向和「稳定偏好」的理由是一致的：pin 表达的是「这条我要长期带着」，
+   * 越早做出这个承诺、越久没被撤回，就越该占住名额；若反过来让新钉的优先，
+   * pin 就退化成「最近关注」清单，和 updated_at DESC 那个错误排序键同病。
+   *
+   * 注意排序键是「什么时候钉的」，不是内容的 updated_at——一条 10 月的老记忆
+   * 今天才钉，它在 pin 序里是新的、在内容上是老的，两个轴不要混。
+   * 次键 rowid：同毫秒连钉两条时 UUID 主键排序是随机的，回执要可复现。
+   */
+  function listPinned() {
+    return db.prepare("SELECT * FROM pinned_memories ORDER BY created_at ASC, rowid ASC").all().map(toPinned);
+  }
+
+  /**
+   * 钉住一条记忆。重复 pin 同一 id 不刷新 created_at（只补 note）——pin 顺序
+   * 是「第一次钉的时间」，重钉不该把老偏好的位置往后推。调用方负责确认目标
+   * 记忆存在；这里不做外键校验（本库其余表同款：关系表不设 FK，删记忆时由
+   * unpinMemory 或下一次读的 forgotten/archived 过滤兜住）。
+   */
+  function pinMemory(memoryId, { note, created_at } = {}) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return undefined;
+    const id = memoryId.trim();
+    const at = normalizeOccurredAt(created_at) ?? nowIso();
+    db.prepare(
+      `INSERT INTO pinned_memories (memory_id, created_at, note) VALUES (?, ?, ?)
+       ON CONFLICT(memory_id) DO UPDATE SET note = COALESCE(excluded.note, pinned_memories.note)`
+    ).run(id, at, normalizeScopeText(note));
+    return toPinned(db.prepare("SELECT * FROM pinned_memories WHERE memory_id = ?").get(id));
+  }
+
+  /** 松开一条 pin。返回实际删掉的行数（0 = 本来就没钉，不是错误）。 */
+  function unpinMemory(memoryId) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return 0;
+    return db.prepare("DELETE FROM pinned_memories WHERE memory_id = ?").run(memoryId.trim()).changes;
+  }
+
+  /** pin 行数。注入侧靠它判「表是空的」——空表要回落到旧的类型口径。 */
+  function countPinned() {
+    return db.prepare("SELECT count(*) AS c FROM pinned_memories").get().c;
+  }
+
+  /**
+   * 这条记忆是否被显式钉住（单行点查，读侧）。
+   *
+   * 存在的理由是 #593 的缺口：升格吸收（document.js 的 evidence 归档）只拿得到
+   * 记忆行、拿不到 pin 表，于是它只能按**类型**猜「谁属于保真池」。显式 pin 落地
+   * 后，一条 pattern / decision 被钉住仍然是 pin，按类型猜就把它当普通行收走了。
+   * 谓词必须来自本表，不能从类型推——这正是 #593 把 pin 从类型推断改成显式存储
+   * 的同一件事，别在第二个地方又推回去。
+   */
+  function isPinned(memoryId) {
+    if (typeof memoryId !== "string" || !memoryId.trim()) return false;
+    return db.prepare("SELECT 1 AS hit FROM pinned_memories WHERE memory_id = ?").get(memoryId.trim()) !== undefined;
+  }
+
+  /**
+   * 按 id 点查注入所需的行（绕开 200 行窗口的唯一通道）。
+   *
+   * 显式列清单复用 memoryColumnList：它经 PRAGMA 派生、已排除 embedding
+   * （1024 维浮点文本 ≈ 34KB/条，5 条就白搬 170KB 而注入渲染根本不用向量）。
+   * 返回顺序不保证（IN 的求值序），调用方按自己的次序（pin created_at）重排。
+   */
+  function listByIdsForInject(ids) {
+    const wanted = Array.isArray(ids) ? ids.filter((id) => typeof id === "string" && id) : [];
+    if (wanted.length === 0) return [];
+    const placeholders = wanted.map(() => "?").join(", ");
+    return db.prepare(`SELECT ${memoryColumnList} FROM memories WHERE id IN (${placeholders})`)
+      .all(...wanted).map(toRow);
+  }
+
   function getFailureStats({ since } = {}) {
     const clause = since ? "WHERE created_at >= ?" : "";
     const params = since ? [since] : [];
@@ -3926,6 +4508,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 +4807,327 @@ 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;
+    });
+  }
+
+  // --- chorography 向量（收尾档 P36–P38）---------------------------------
+  // 一页一行（saveChoroPageVector 先删后插）；dim 失配由检索侧判（查询向量
+  // 的 dim ≠ 行 dim → 该行按 stale 处理，惰性全量重嵌）。
+  function getChoroPageVectors(repoId) {
+    return db.prepare(
+      `SELECT v.owner_id, v.dim, v.model, v.vector, v.source_generated_at,
+              m.slug, m.title, p.generated_at AS page_generated_at
+         FROM choro_vectors v
+         JOIN choro_pages p ON v.owner_id = p.id
+         JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ?`
+    ).all(repoId);
+  }
+
+  function saveChoroPageVector(pageId, { vector, dim, model, sourceGeneratedAt, createdAt }) {
+    return runAtomically(() => {
+      db.prepare("DELETE FROM choro_vectors WHERE owner_id = ?").run(pageId);
+      db.prepare(
+        `INSERT INTO choro_vectors (owner_id, dim, model, vector, source_generated_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(pageId, dim, model, JSON.stringify(vector), sourceGeneratedAt, createdAt);
+      return { owner_id: pageId, dim };
+    });
+  }
+
+  // --- 「Agent 眼中的你」自动事实（2026-11-06，profile-facts 域）---
+  // 三张表只服务本域，写路径全部走 runAtomically：facts 与记忆主表零交叉，不需要
+  // service.transaction 的 pendingEmbed/pendingEntity 截断语义（那层是给写记忆行用的）。
+
+  function parseFactIds(text) {
+    if (!text) return [];
+    try {
+      const v = JSON.parse(text);
+      return Array.isArray(v) ? v.map((x) => String(x)) : [];
+    } catch { return []; }
+  }
+
+  function listProfileFacts(agentKey, { includeArchived = false } = {}) {
+    const rows = db.prepare(
+      `SELECT * FROM profile_facts WHERE agent_key = ? ${includeArchived ? "" : "AND status = 'active'"} ORDER BY updated_at DESC, id DESC`
+    ).all(agentKey);
+    return rows.map((r) => ({ ...r, source_memory_ids: parseFactIds(r.source_memory_ids) }));
+  }
+
+  /** 全库活跃事实按卡分组（注入 provider 的读口，见 src/profile-facts.js）。 */
+  function listActiveFactsGrouped() {
+    const rows = db.prepare(
+      "SELECT agent_key, content FROM profile_facts WHERE status = 'active' ORDER BY updated_at DESC"
+    ).all();
+    const grouped = { default: [], byAgent: {} };
+    for (const r of rows) {
+      if (r.agent_key === "") grouped.default.push(r.content);
+      else (grouped.byAgent[r.agent_key] ??= []).push(r.content);
+    }
+    return grouped;
+  }
+
+  function getProfileFact(id) {
+    const r = db.prepare("SELECT * FROM profile_facts WHERE id = ?").get(id);
+    return r ? { ...r, source_memory_ids: parseFactIds(r.source_memory_ids) } : undefined;
+  }
+
+  function insertProfileFact({ id, agentKey, content, sourceMemoryIds = [], at }) {
+    db.prepare(
+      "INSERT INTO profile_facts (id, agent_key, content, status, source_memory_ids, created_at, updated_at) VALUES (?, ?, ?, 'active', ?, ?, ?)"
+    ).run(id, agentKey, String(content), JSON.stringify(sourceMemoryIds ?? []), at, at);
+  }
+
+  /** 返回更新后的行；id 不存在返回 undefined，由调用方记入 failures。 */
+  function updateProfileFact(id, { content, status, sourceMemoryIds, at }) {
+    const cur = getProfileFact(id);
+    if (!cur) return undefined;
+    const next = {
+      content: content ?? cur.content,
+      status: status ?? cur.status,
+      source_memory_ids: sourceMemoryIds ?? cur.source_memory_ids,
+      updated_at: at
+    };
+    db.prepare("UPDATE profile_facts SET content = ?, status = ?, source_memory_ids = ?, updated_at = ? WHERE id = ?")
+      .run(next.content, next.status, JSON.stringify(next.source_memory_ids), next.updated_at, id);
+    return { ...cur, ...next };
+  }
+
+  function insertProfileFactJournal({ at, agentKey, runId = null, factId = null, op, before = null, after = null, actor = "auto" }) {
+    db.prepare(
+      "INSERT INTO profile_fact_journal (at, agent_key, run_id, fact_id, op, before, after, actor) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    ).run(at, agentKey, runId, factId, op, before, after, actor);
+  }
+
+  function listProfileFactJournal(agentKey, { limit = 20 } = {}) {
+    return db.prepare("SELECT * FROM profile_fact_journal WHERE agent_key = ? ORDER BY id DESC LIMIT ?")
+      .all(agentKey, limit);
+  }
+
+  /** 每卡只留最近 keep 条：账本是审计事实不是检索面，无界增长没有读者。 */
+  function pruneProfileFactJournal(agentKey, keep = 200) {
+    return db.prepare(
+      `DELETE FROM profile_fact_journal WHERE agent_key = ? AND id NOT IN (
+         SELECT id FROM profile_fact_journal WHERE agent_key = ? ORDER BY id DESC LIMIT ?)`
+    ).run(agentKey, agentKey, keep).changes;
+  }
+
+  function insertProfileFactRun({ id, agentKey, triggerSource, status, cursor = null, inputCount = 0, opsApplied = 0, detail = null, startedAt, finishedAt }) {
+    db.prepare(
+      `INSERT INTO profile_fact_runs (id, agent_key, trigger_source, status, cursor, input_count, ops_applied, detail, started_at, finished_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, agentKey, triggerSource, status, cursor, inputCount, opsApplied, detail, startedAt, finishedAt);
+  }
+
+  function listProfileFactRuns(agentKey, { limit = 10 } = {}) {
+    return db.prepare("SELECT * FROM profile_fact_runs WHERE agent_key = ? ORDER BY started_at DESC, id DESC LIMIT ?")
+      .all(agentKey, limit);
+  }
+
+  /** 该卡最近一次 ok 轮的游标。failed 轮不消费——下次重跑同一窗口（蒸馏游标同款纪律）。 */
+  function profileFactsCursor(agentKey) {
+    const row = db.prepare(
+      "SELECT cursor FROM profile_fact_runs WHERE agent_key = ? AND status = 'ok' ORDER BY started_at DESC, id DESC LIMIT 1"
+    ).get(agentKey);
+    return row ? row.cursor : null;
+  }
+
+  /**
+   * 增量输入行：活跃（未归档未遗忘）+ 排除外来行（source IS NULL OR 那一支是三值
+   * 逻辑必填，与 list() 的 excludeImported 同一个坑）+ 严格 scope 分区——agent 卡
+   * 只吃 agent_scope=自己 的行，default 卡只吃 agent_scope IS NULL 的行。
+   * updated_at 是 ISO 串，字典序即时间序，`>` 即「游标之后」（单调时间戳纪律）。
+   */
+  function listFactInputRows(agentKey, { since = null, limit = 120 } = {}) {
+    const scopeClause = agentKey ? "agent_scope = ?" : "agent_scope IS NULL";
+    const params = [IMPORTED_SOURCE, ...(agentKey ? [agentKey] : [])];
+    if (since) params.push(since);
+    params.push(limit);
+    return db.prepare(
+      `SELECT id, type, title, content, importance, updated_at FROM memories
+       WHERE forgotten = 0 AND archived = 0 AND (source IS NULL OR source <> ?)
+         AND ${scopeClause}
+         ${since ? "AND updated_at > ?" : ""}
+       ORDER BY updated_at DESC LIMIT ?`
+    ).all(...params);
+  }
+
+  function countFactInputRows(agentKey, { since = null } = {}) {
+    const scopeClause = agentKey ? "agent_scope = ?" : "agent_scope IS NULL";
+    const params = [IMPORTED_SOURCE, ...(agentKey ? [agentKey] : [])];
+    if (since) params.push(since);
+    return db.prepare(
+      `SELECT COUNT(*) AS n FROM memories
+       WHERE forgotten = 0 AND archived = 0 AND (source IS NULL OR source <> ?)
+         AND ${scopeClause}
+         ${since ? "AND updated_at > ?" : ""}`
+    ).get(...params).n;
+  }
+
+  /**
+   * 自动轮要维护的卡：有 scope 行的记忆身份 ∪ 存量卡片。存量卡即使输入行被清空
+   * 也保留在名单里（手动轮还可能对它做人工修正后的再维护）；'' 由调用方固定追加。
+   */
+  function listFactCardKeys() {
+    return db.prepare(
+      `SELECT DISTINCT agent_scope AS k FROM memories WHERE agent_scope IS NOT NULL
+       UNION
+       SELECT DISTINCT agent_key FROM profile_facts WHERE agent_key <> ''`
+    ).all().map((r) => r.k);
+  }
+
   return {
     db,
     count,
@@ -4257,6 +5170,7 @@ export function createStore(path) {
     setEmbedding,
     getEmbeddings,
     getParsedEmbedding,
+    embeddingCacheStats,
     embeddedCount,
     needsEmbedding,
     needsEmbeddingFor,
@@ -4294,6 +5208,7 @@ export function createStore(path) {
     listLlmAudits,
     countLlmAudits,
     getLlmAuditStats,
+    getConsolidationStats,
     deleteOldLlmAudits,
     // 蒸馏原始记录与记忆级溯源（#399）：窗口凭证的写入/统计/裁剪，链接的读写。
     saveDistillRecords,
@@ -4340,10 +5255,20 @@ export function createStore(path) {
     setScopeState,
     getScopeState,
     listScopeStates,
+    // #249 第二批：显式 pin（独立表，绕开候选池的通道）。注入侧只读这里，
+    // 不再拿 PINNED_MEMORY_TYPES 当 pin 标记（那个常量在 write-admission 里
+    // 另有写入配额豁免的语义，两件事不再叠在同一个名字上）。
+    listPinned,
+    pinMemory,
+    unpinMemory,
+    countPinned,
+    isPinned,
+    listByIdsForInject,
     createEntity,
     findEntityByName,
     findEntityById,
     listEntities,
+    countEntities,
     updateEntity,
     saveAttr,
     invalidateOldAttr,
@@ -4378,6 +5303,32 @@ export function createStore(path) {
     getContinuityProposal,
     listContinuityProposals,
     countContinuityProposals,
+    // chorography（仓库地志）：M0 只写不读，消费面 M1 接（见上面注释块）。
+    choroRepoByRoot,
+    upsertChoroRepo,
+    replaceChoroGraph,
+    choroPageBySlug,
+    recordChoroPageFailure,
+    markChoroPageEnriched,
+    saveChoroPageClaims,
+    getChoroPageVectors,
+    saveChoroPageVector,
+    // 「Agent 眼中的你」自动事实（2026-11-06）：读口与写口都只给 domain 层
+    // （src/profile-facts.js）和 API 层用，记忆主表路径不经此。
+    listProfileFacts,
+    listActiveFactsGrouped,
+    getProfileFact,
+    insertProfileFact,
+    updateProfileFact,
+    insertProfileFactJournal,
+    listProfileFactJournal,
+    pruneProfileFactJournal,
+    insertProfileFactRun,
+    listProfileFactRuns,
+    profileFactsCursor,
+    listFactInputRows,
+    countFactInputRows,
+    listFactCardKeys,
     close() {
       db.close();
     }