@modusensus/dsh-mneme 0.9.3 → 0.9.5

package/lib/store.js

@@ -11,6 +11,11 @@ import {
   normalizeScopeStateState,
   normalizeScopeStateValue
 } from "./scope-state.js";
+// 外来行的**唯一**定义住在 memory-source.js，这里只取那个常量：store 的查询口径与
+// service/sleep 的 isImportedRow 必须是同一个字符串，自己再拼一份字面量就是第二个口径，
+// 而「本库不巩固别人导入的原文」这条契约正靠它只有一个人说得出口。
+// 依赖方向 store → memory-source 单向（该模块不 import 任何东西），不构成环。
+import { IMPORTED_SOURCE } from "./memory-source.js";
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS memories (
@@ -275,10 +280,12 @@ CREATE INDEX IF NOT EXISTS idx_distill_records_distilled_at ON distill_records(d
 -- 不该因删掉其中一条派生记忆而消失。
 -- memory_id 是 TEXT 而非 issue 草稿里的 INTEGER：memories.id 是 TEXT 主键，
 -- 类型必须与父表一致（否则 join 恒空）。
--- ON DELETE CASCADE 在本库**不生效**——store.js 从不打开 PRAGMA foreign_keys，
--- 全库唯一那条 REFERENCES 也一直是惰性的。与其为一个新表翻转全局 pragma
--- （会同时改变既有 recall_events 的写入行为），不如在 remove() 里显式清链接：
--- 语义相同、影响面只在本表。见 remove() 的注释。
+-- ON DELETE CASCADE 在本库是**生效的**：createStore 走 new DatabaseSync(path) 不带选项，
+-- 而 node:sqlite 的 enableForeignKeyConstraints 默认为真（实测：新库上 PRAGMA foreign_keys
+-- 返回 1，删父行确实级联清掉本表）。本库两条 FK 都因此一直是活的——这一条，以及
+-- recall_evals(recall_run_id) → recall_runs(id)。级联在兜底，remove() 仍然显式清链接，
+-- 理由不是「FK 没开」，而是这份清理不该挂在一条没人钉过的驱动默认上：连接哪天被以
+-- enableForeignKeyConstraints:false 打开，悬空链接只有那条 DELETE 挡得住。见 remove() 的注释。
 CREATE TABLE IF NOT EXISTS memory_provenance (
   memory_id  TEXT    NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
   session_id TEXT    NOT NULL,
@@ -536,6 +543,11 @@ function toRow(row) {
     // 顺手 `?? updated_at` 把代理口径捡回来。
     archived_at: row.archived_at ?? undefined,
     source: row.source ?? undefined,
+    // 车道 C：外来行身份两格。NULL 读作 undefined（与 archived_at 同款「不可知就不编
+    // 值」）。注意「这行是不是外来行」的判据仍是 source（memory-source.js 的
+    // isImportedRow）——这两格只回答「来自哪个包 / 幂等键是什么」，不回答身份。
+    share_pack_id: row.share_pack_id ?? undefined,
+    share_external_id: row.share_external_id ?? undefined,
     content_history: parseJsonArray(row.content_history),
     evidence: parseJsonArray(row.evidence),
     doc_path: row.doc_path ?? undefined,
@@ -886,6 +898,32 @@ export function createStore(path) {
   // 存量行的值是 NULL，且**不推断**：按 updated_at 猜出的模型名会变成日后审计信
   // 以为真的证据。NULL 一律读作「出身未知」，等价的补法是重算，不是猜。
   addColumn("memories", "embedding_model", "ALTER TABLE memories ADD COLUMN embedding_model TEXT");
+  // 车道 C：外来行的身份两件套。share_pack_id 是「整包退出」的寻址键，share_external_id
+  // 是导入的幂等键。它们只对自己铸造的行有意义，所以缺省是 NULL 而不是 ''：空串会参与
+  // 唯一性（第二条本地行就撞响），而存量行零重写、读侧 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");
+  // 索引建在加列之后而非写进 SCHEMA（本文件 content_hash 那段：存量库打开时 CREATE TABLE
+  // 是 no-op，列还不存在就建索引会直接 no such column）。
+  // 部分索引（WHERE ... IS NOT NULL）是刻意的，但它承重的地方要说准：SQLite 的 UNIQUE
+  // 本就把 NULL 视为互不相等，本地行（这一格恒 NULL）挂在普通 UNIQUE 上也不撞——变异检验
+  // 证实摘掉 WHERE 五个用例照绿。它承的是另外两件事：①约束的适用范围写进索引本身，
+  // 「只有导入路径铸造的 id 参与唯一性」这条语义没有别的表达渠道，读代码的人不必再去猜
+  // NULL 在这里算什么；②本地行不进这棵 b 树——普通 UNIQUE 要给每一条本地记忆插一个永不
+  // 生效的空键，而库里绝大多数是本地行，每次写都白付一次索引维护。
+  // 「NULL 必须自由共享」那条用例锁的是行为而非实现：它防的是将来有人把空串当缺省值写
+  // 进来（'' 参与唯一性，第二条 '' 直接撞响），不是防 WHERE 子句消失。
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_share_external ON memories(share_external_id) WHERE share_external_id IS NOT NULL");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_share_pack ON memories(share_pack_id)");
+  // Issue #505：saveWithDedupe 的定向候选是 `type = ? AND TRIM(title) = ?`。只有
+  // idx_memories_type 时这条语句等于「把该类型的行全读一遍、逐行 TRIM」，代价随最大
+  // 类型的行数线性长（本机 node:sqlite 实测同类型 1000 / 5000 / 20000 行 = 0.13 /
+  // 0.68 / 4.63 ms，而它是每存一条都要付一次的写路径）。TRIM 本身不是瓶颈——同句去掉
+  // TRIM 只差 0.07 ms，缺的是能把整个条件当 seek 用的索引；建好之后同一查询在同一批
+  // 数据上 ~0.00 ms。索引表达式必须与 SQL 里的写法逐字相同（TRIM(title)，不是 title），
+  // 差一点优化器就静默不认，而所有行为用例照样全绿——所以 dedupe-candidate-window
+  // 那条用例用 EXPLAIN QUERY PLAN 钉住它真的被选中。改 service 的 WHERE 必须同时改这里。
+  db.exec("CREATE INDEX IF NOT EXISTS idx_memories_type_trimmed_title ON memories(type, TRIM(title))");
   // issue #24 块2（权重演化）：entity_relations 加 weight + source。存量关系
   // 行缺列 → 默认 manual 1.0（最保守：既有语义不因迁移而变弱）。
   addColumn("entity_relations", "weight", "ALTER TABLE entity_relations ADD COLUMN weight REAL NOT NULL DEFAULT 1.0");
@@ -1123,6 +1161,30 @@ export function createStore(path) {
     return toRow(row);
   }
 
+  /**
+   * 车道 C 导入的幂等读：按包内那条记忆的铸造 id 找本库的行。
+   * 走 idx_memories_share_external（部分索引，非 NULL 那一侧），等值 seek。
+   * 本地行这一格恒 NULL，因此本函数永远不会误命中本地记忆。
+   */
+  function getByShareExternalId(externalId) {
+    if (typeof externalId !== "string" || !externalId) return undefined;
+    return toRow(db.prepare("SELECT * FROM memories WHERE share_external_id = ?").get(externalId));
+  }
+
+  /**
+   * 一个包在本库落下的全部行（撤回前的清点 / 面板「外来区」列表）。
+   *
+   * 不过滤 archived / forgotten：整包退出要连归档面与遗忘面一起收走，否则撤回后库里
+   * 还剩几条「来自那个已经收起的包」的行，身份与包对不上。
+   * 读显式列清单而非 SELECT *（#430 的口径）：一个包可以有几百行，每行 9.4 MB 级别
+   * 的 embedding 拖进来没有任何消费方会读。
+   */
+  function listBySharePackId(packId) {
+    if (typeof packId !== "string" || !packId) return [];
+    return db.prepare(`SELECT ${memoryColumnList} FROM memories WHERE share_pack_id = ? ORDER BY updated_at DESC, id DESC`)
+      .all(packId).map(toRow);
+  }
+
   // #230 写入权分离（存储层唯一铸造口，CodeRabbit 复核最终形态）：document
   // 行只能经 saveDocument 铸造，通用 save 整类拒绝。doc_path 是任意调用方
   // 都能捏造的字符串——「必带 doc_path」挡不住绕过注册校验（flag 闸 / 文件
@@ -1168,8 +1230,8 @@ export function createStore(path) {
       : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, archived_at, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, content_hash, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, archived_at, source, content_history, quality_score, embedding, epistemic_status, agent_scope, workspace_scope, agent_scope_source, workspace_scope_source, scope_decided_at, sensitivity, occurred_at, evidence, doc_path, content_hash, share_pack_id, share_external_id, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
       ).run(
         id,
         type,
@@ -1197,6 +1259,11 @@ export function createStore(path) {
         evidence,
         docPath,
         contentHash,
+        // 车道 C：外来行身份。空串一律落 NULL——空串会占住 UNIQUE 索引的一格，第二条
+        // 空串外来行就撞响；这两格只由导入路径铸造，其余写入恒 NULL。
+        // created_at / updated_at / content_hash 仍由本函数铸造，不接受调用方传值。
+        typeof memory.share_pack_id === "string" && memory.share_pack_id.trim() ? memory.share_pack_id.trim() : null,
+        typeof memory.share_external_id === "string" && memory.share_external_id.trim() ? memory.share_external_id.trim() : null,
         now,
         now
       );
@@ -1332,10 +1399,11 @@ export function createStore(path) {
 
   function remove(id) {
     runAtomically(() => {
-      // #399：memory_provenance 的 ON DELETE CASCADE 在本库是惰性的（createStore
-      // 从不打开 PRAGMA foreign_keys），所以链接在这里显式清。不用翻转全局 pragma
-      // 换这一条级联：那会同时激活 recall_events 那条既有的 REFERENCES，改变一个
-      // 与 #399 无关的写入路径。记录本身（distill_records）不删——删掉一条派生记忆
+      // #399：memory_provenance 挂着 ON DELETE CASCADE，而 node:sqlite 默认就把
+      // foreign_keys 开成 1（实测 PRAGMA foreign_keys = 1），所以级联今天确实在兜底。
+      // 这条显式 DELETE 不是冗余、也不是「FK 没开才需要」：它是不把清理挂在一份没人
+      // 钉过的驱动默认上——连接哪天以 enableForeignKeyConstraints:false 打开，悬空链接
+      // 只有这一条挡得住。记录本身（distill_records）不删——删掉一条派生记忆
       // 不该让整个窗口的原文凭证消失。
       db.prepare("DELETE FROM memory_provenance WHERE memory_id = ?").run(id);
       db.prepare("DELETE FROM memories WHERE id = ?").run(id);
@@ -1345,6 +1413,66 @@ export function createStore(path) {
     });
   }
 
+  // 一条 DELETE ... WHERE id IN (...) 最多绑多少个 `?`。SQLite 的上限是 32766
+  // （SQLITE_MAX_VARIABLE_NUMBER），取 500 后离上限还有六十多倍余量：这条语句一行一个参数，
+  // 而包的大小按字节不按条数封顶（见 deleteBySharePackId 的分块理由），500 让单条语句的
+  // 解析成本可以忽略、又永远够不到那格上限，块数只随包条数线性增长。
+  const DELETE_ID_CHUNK = 500;
+
+  /**
+   * 整包退出（车道 C）。删空一个不存在的包是幂等的 0，不是错误——对方点第二次「收起
+   * 这个包」与「收起一个从来没导入过的包」都该是这个答案；早退也不 bump generation：
+   * 什么都没删就别记一笔镜像债（remove() 每次必 bump，那是它的既有行为，不在这里扩大）。
+   *
+   * side table 清理口径 = remove() 的口径（#399）：显式同事务清 memory_provenance。
+   * 这条是双保险，不是「FK 没开所以必须手写」：memory_provenance 挂着 ON DELETE CASCADE，
+   * 而 node:sqlite 默认就把 foreign_keys 开成 1（实测 PRAGMA foreign_keys = 1），今天删行
+   * 确实另有级联兜底；显式清理的存在是为了不依赖这份没人钉过的驱动默认，同时跟 remove()
+   * 保持一致的口径（连接哪天以 enableForeignKeyConstraints:false 打开，悬空链接只有它挡得住）。
+   *
+   * remove() 不碰的（entity_attrs / entity_relations 的 memory_id 反查、conflict_pending、
+   * scope_changes、embedding 解析缓存）这里也不碰——批删不是新的清理语义。
+   *
+   * 向量索引这一格 C4 实测过，把 C1 留下的那句「由 C4 在 service 侧处理」改对：service
+   * 侧没有活儿要接。`vector-index.js` 是 memories.embedding 那一列的薄层，余弦检索
+   * (`searchVector`) 每次调用都从 SQL 现取「带向量的行」的 id 集合，行被物理删掉即从集合
+   * 里消失——向量跟着行一起走，一列残值都留不下；事后落到的 embed 也只是
+   * `UPDATE ... WHERE id = ?` 命中 0 行，不会把僵尸行写回来。唯一的残留是 #202 那个
+   * 进程内的解析缓存（id → 已解析向量），它与 remove() 同处置且读不出僵尸：每个调用方
+   * （searchVector / getEmbeddings / document.js / organize.js）的 id 集合都来自活行的
+   * SQL 读，未命中缓存时按 id 点查库，行没了就返回 undefined——最坏是一条等 FIFO 驱逐的
+   * 内存，不是一条搜得到的鬼行。要在这里清它等于给批删加一份 remove() 没有的新语义，
+   * 与本方法的口径声明相反，所以不动（C4 的报告记了这一格，remove() 是否要一起补是
+   * 单独一刀的事）。
+   *
+   * IN 列表分块（chunk = DELETE_ID_CHUNK）：SQLite 一条语句最多绑 32766 个参数
+   * （SQLITE_MAX_VARIABLE_NUMBER，实测第 32767 个报 "too many SQL variables"），而这条
+   * 语句原本一行一个 `?`。车道 A 的包水位按字节不按条数（MAX_PACK_BYTES = 3 MiB），所以
+   * 「正文很短、条数很多」的包理论上能逼近那一格——一条语句撞上限是整笔回滚，效果等于
+   * 「这个包永远撤不掉」，而那正是退出这条路径最不该坏的方式。
+   * 分块不是语义变化，四点逐条对齐分块前的形状：ids 是本事务开头一次读到的固定快照
+   * （slice 出来的连续段，块之间互不相交、并起来就是全集）；按主键删本就幂等；整包裹在同
+   * 一个 runAtomically 里，原子性与快照语义一字未动；generation 只在最后加一次，所以
+   * 「删了行却没记镜像债」这个 crash 窗口和分块前同样不存在。changes 逐块求和——那是
+   * 调用方答复里报出去的数，少加一块就少报一块。
+   */
+  function deleteBySharePackId(packId) {
+    if (typeof packId !== "string" || !packId) return 0;
+    return runAtomically(() => {
+      const ids = db.prepare("SELECT id FROM memories WHERE share_pack_id = ?").all(packId).map((r) => r.id);
+      if (!ids.length) return 0;
+      let deleted = 0;
+      for (let start = 0; start < ids.length; start += DELETE_ID_CHUNK) {
+        const chunk = ids.slice(start, start + DELETE_ID_CHUNK);
+        const marks = chunk.map(() => "?").join(", ");
+        db.prepare(`DELETE FROM memory_provenance WHERE memory_id IN (${marks})`).run(...chunk);
+        deleted += db.prepare(`DELETE FROM memories WHERE id IN (${marks})`).run(...chunk).changes;
+      }
+      incrementGeneration();
+      return deleted;
+    });
+  }
+
   /**
    * Atomic compare-and-set update: applies `patch` only when the row still
    * carries `expectedUpdatedAt` (the version token read by the caller). Returns
@@ -1521,7 +1649,7 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
-  function list({ type, excludeTypes = null, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
+  function list({ type, excludeTypes = null, excludeImported = false, limit = 50, offset = 0, order = "importance", includeForgotten = false, includeArchived = false, onlyArchived = false, depositedOnly = false, minImportance = null, source = null, updatedFrom = null, updatedTo = null, occurredFrom = null, occurredTo = null, visibility = null } = {}) {
     const clauses = [];
     const params = [];
     if (type) {
@@ -1545,6 +1673,17 @@ export function createStore(path) {
       clauses.push("source = ?");
       params.push(source);
     }
+    // excludeImported：「本库不巩固别人导入的原文」这条政策轴的查询层口径。
+    // 它必须站在 LIMIT 之前而不是跟着 .filter 走在后面——与上面 excludeTypes 那条同理由
+    // （#230）：先截断后丢弃的话，被丢掉的外来行照样吃掉窗口名额，导入过包的库里
+    // 模式扫描池会因此饿到 sleepPatternMinMemories 以下而静默跳过。
+    // `source IS NULL OR` 那一支不是防御性冗余，是必填：本方行的 source 恒为 NULL，
+    // 而 SQL 里三值逻辑让 `NULL <> IMPORTED_SOURCE` 求值为 NULL（不是 true），只写后者的
+    // 话本方行整批消失。opt-in 默认关，其余调用方的读数逐字节不变。
+    if (excludeImported) {
+      clauses.push("(source IS NULL OR source <> ?)");
+      params.push(IMPORTED_SOURCE);
+    }
     // Optional updated_at closed range (date-only "to" is normalized to the
     // end of that day). Same helper as count() so total matches the rows.
     const bounds = updatedAtBounds(updatedFrom, updatedTo);
@@ -1645,6 +1784,30 @@ export function createStore(path) {
     return rows.map(toRow);
   }
 
+  // Issue #505：写路径的去重候选必须「按同标题定向取」，不能「按 importance 取
+  // 前 N 条」。后者是「该类型最重要的 100 行」，与「找出同标题的那一行」无关：
+  // 某类型里 importance 高于待写行的行数一旦超过窗口，同标题行与待写行双双落在
+  // 窗口外，saveWithDedupe 的 find 恒不命中，于是静默走创建分支——不报错、不告
+  // 警，合并语义随库增长而失效（报告实测 1047 行类型、importance=5 有 180 行时
+  // 稳定复现）。
+  //
+  // 口径刻意与 saveWithDedupe 的比较式对齐：那边用 m.title.trim() 比
+  // String(memory.title).trim()，而 title 入库时并不 trim（见 save() 的
+  // `memory.title` 直写）⇒ 这里必须 TRIM(title)，否则存量里带首尾空白的标题
+  // 会被精确匹配漏掉，退回同一种静默降级。
+  //
+  // archived/forgotten 的过滤与 list() 默认口径一致（两者都为 0）：合并目标必须
+  // 是活跃行，否则会把内容并进一条已经归档/遗忘的记忆里。
+  // 无 LIMIT：同 (type, title) 的活跃行本就极少，加窗口等于把 #505 重新引进来。
+  function activeByTypeAndTitle(type, title) {
+    const rows = db.prepare(
+      `SELECT ${memoryColumnList} FROM memories
+        WHERE type = ? AND TRIM(title) = ?
+          AND forgotten = 0 AND archived = 0`
+    ).all(type, String(title ?? "").trim());
+    return rows.map(toRow);
+  }
+
   // Issue #430：写路径要的「最近若干条正文」。质量过滤的近重复判定只读 content
   // 这一列 + 前 20 行，此前写成 all().slice(0, 20) —— 全表逐行 toRow（27 字段、
   // 三次 JSON 解析）之后只截前 20 条正文；5k 行实测 100ms 级 → 0.06ms 级。
@@ -1801,6 +1964,71 @@ export function createStore(path) {
     }, new Map());
   }
 
+  /**
+   * 维度探针（#383）：**存在性判据**——库里有没有一条活跃向量的维度等于查询维度。
+   *
+   * #508 评审把判据从「读一行的维度」换成了存在性，因为 LIMIT 1 拿任意一条代表全库，
+   * 在混合维度库里两个方向都错：抽到与查询不符的那条 → 明明有可比的 3 维向量却报
+   * degraded；抽到的那条恰好解析失败 → 其余有效向量都不匹配时又漏报成 full。一行
+   * 读数回答不了「这个维度在这库里能不能比」这个问题。
+   *
+   * 行集与 searchVector **必须同源**：下面这段 WHERE 的谓词与 searchVector（本文件
+   * vector search 段）逐条相同（只是书写顺序不同，语义等价），改一处必须同步改另一处
+   * ——否则 tier 的核心断言「searchVector 会不会找到可比向量」会悄悄失真。活跃 = 未
+   * 遗忘未归档、embedding 非空；/context 只经 searchVector 触达检索，从不传
+   * includeArchived。
+   *
+   * 状态语义（后两个是 fail-closed 兜底态，不是正常读数）：
+   *   match      有维度相符的活跃向量 → 语义路通。注意「通」≠「有命中」：type /
+   *              importance / codingGate / scope 四道门（service.js 的 inject 段）
+   *              仍可能让语义档贡献为 0，这是旧探针就有的边界。
+   *   mismatch   有向量，但没有一条维度相符 → 语义召回实际不可用 → degraded
+   *   none       行集本身为空（空库 / 从未建索引）→ 没有东西可比，**不是**维度
+   *              不符 → full
+   *   unreadable 有行，但一条都读不出来（embedding 列损坏）→ 与 none 是**两种空**：
+   *              前者是还没有内容，后者是内容在那儿却读不出来。判不出来 → unknown，
+   *              绝不因为「读不到」就宣称 full。
+   *   invalid    查询维度本身不是正整数 → 同样判不出来 → unknown。当前 /context
+   *              不可达（embedQueryVector 保证返回非空数组），防御性留着：别让
+   *              「判不了」落到 full 上。
+   *
+   * 成本模型（取代原来「只读一行，O(1)」的说法——那句话对现在的实现是假的）：
+   *   · SQL 是一次**无 ORDER BY 无 LIMIT 的全 id 扫描**，每次调用都有，不免费
+   *     （只拖 id 列，约 40 KB/千行，比 SELECT * 的全表 TEXT 便宜得多）。
+   *   · 按匹配短路：全库同维度（常态）时 JS 循环第一行就 return，只解析 1 个向量。
+   *   · 一条都不匹配时才走完整个循环，而那正是要报 degraded 的情形，值得。此时每个
+   *     缓存未命中的行都要点查一次 embedding TEXT（冷缓存下 = N+1 条语句）；
+   *     getParsedEmbedding 不缓存否定结果，所以读不出来的行每次请求都会重解析一次。
+   *   · 缓存热不热是有条件的：/context 里让 embeddingCache 变热的只有 injectCandidates
+   *     内部两个 vectorIndex 分支（service.js:1696 / :1768），需要 hybridInject 与
+   *     selectiveInject 都没被关掉、行数在 4000 条 FIFO 上限内；standalone 装配不设
+   *     vectorIndex 时缓存是冷的。判档跑在 injectCandidates 之后，装配齐时缓存已热。
+   *
+   * @param {number} dimension 查询向量维度
+   * @returns {{state: "match"|"mismatch"|"none"|"unreadable"|"invalid"}}
+   */
+  function vectorDimensionState(dimension) {
+    if (!Number.isInteger(dimension) || dimension <= 0) return { state: "invalid" };
+    // 与 searchVector 的 WHERE 谓词逐条相同（顺序不同、语义等价）——同源行集，同步改。
+    const rows = db.prepare(
+      `SELECT id FROM memories
+       WHERE embedding IS NOT NULL AND embedding != ''
+         AND forgotten = 0 AND archived = 0`
+    ).all();
+    if (!rows.length) return { state: "none" };
+    let sawVector = false;
+    for (const row of rows) {
+      // 走 getParsedEmbedding 的解析缓存，不自己 JSON.parse——与 searchVector /
+      // getEmbedding(s) 同一条读路径，缓存热时零解析。
+      const v = getParsedEmbedding(row.id);
+      if (!v || !v.length) continue;
+      sawVector = true;
+      if (v.length === dimension) return { state: "match" };
+    }
+    // 有行却零条可解析：不是「没有向量」，是「有向量读不出来」。
+    return { state: sawVector ? "mismatch" : "unreadable" };
+  }
+
   function search(query, { limit = 20, includeArchived = false } = {}) {
     const q = String(query).trim();
     if (!q) return [];
@@ -2429,6 +2657,22 @@ export function createStore(path) {
     ).all(memoryId);
   }
 
+  /**
+   * 一个 (session, seq 区间) 的蒸馏原文行（#399 写入、#421 读出口）。
+   *
+   * 按 seq 升序——原文的先后顺序就是区间顺序，乱序会让「这句从哪来」读不出来。
+   * 到期裁剪后区间可能变空，那时返回 []：链接刻意保留并指向空区间
+   * （见 clearDistillRecords 注释），面板据此显示「原文已过期」而非「没有来源」。
+   */
+  function distillRecordsFor(sessionId, seqStart, seqEnd) {
+    return db.prepare(
+      `SELECT seq, role, text, window_id, distilled_at
+         FROM distill_records
+        WHERE session_id = ? AND seq >= ? AND seq <= ?
+        ORDER BY seq`
+    ).all(sessionId, seqStart, seqEnd);
+  }
+
   // --- 存储生命周期：无损回收（#275 第一批）--------------------------------
   //
   // 两项都零价值判断、零条数变化：行数不变，只把不可重建/不可达的内容丢掉。
@@ -3338,6 +3582,9 @@ export function createStore(path) {
     db,
     count,
     getById,
+    // 车道 C：外来行身份的两个读口（幂等键 / 整包清点）。
+    getByShareExternalId,
+    listBySharePackId,
     save,
     // document 唯一铸造口（#230 写入权分离）：registerDocument 专用，通用
     // save/update/CAS 均拒绝 document 创建或类型转换。
@@ -3347,6 +3594,15 @@ export function createStore(path) {
     // #254：写入准入的内容哈希候选集（只读）。
     findContentHashMatches,
     remove,
+    // 车道 C：整包退出（幂等批删，side table 口径同 remove()）。
+    deleteBySharePackId,
+    // 只管 SQLite 回滚的存储层原语（本文件每个写方法都在用它，这里只是对外露一层：
+    // 外层已开着事务时它直接执行回调，db.isTransaction 早退，嵌套不会二次 BEGIN）。
+    // **它不是导入口**：车道 C 的导入走 service.transaction()——那层除回滚外还会随
+    // ROLLBACK 截断 pendingEmbed / pendingEntity，用这个裸原语导入会让队列和库分叉。
+    // 露出的用途是存储级批写与用例：C1 的 UNIQUE 撞库用例（test/share-store.test.js）
+    // 就靠它把「撞一条、整批不落」这条 ROLLBACK 路径直接命中。
+    runAtomically,
     setForget,
     setArchived,
     touchLastAccess,
@@ -3355,6 +3611,9 @@ export function createStore(path) {
     getUnrecalledSince,
     list,
     all,
+    // Issue #505：写路径去重的定向候选（按 type + TRIM(title) 精确取活跃行），
+    // 替代「importance 前 N 条」那个会随库增长失效的窗口。
+    activeByTypeAndTitle,
     // #430：有界单列读，写路径（质量过滤）用。
     recentContents,
     search,
@@ -3367,6 +3626,7 @@ export function createStore(path) {
     hasStaleEmbedding,
     embeddingModelBreakdown,
     embeddingDimensionBreakdown,
+    vectorDimensionState,
     searchVector,
     saveDreamRun,
     lastDreamRunAt,
@@ -3398,6 +3658,7 @@ export function createStore(path) {
     clearDistillRecords,
     saveMemoryProvenance,
     provenanceFor,
+    distillRecordsFor,
     // 存储生命周期（#275 第一批）：无损回收的统计、清理与体积口径。
     dreamRunInputStats,
     clearDreamRunInputs,

package/lib/summarize.js

@@ -33,11 +33,56 @@ function normalizeDistilledOccurredAt(raw, nowMs = Date.now()) {
   }
 }
 
-function parseSummaryJsonResult(raw) {
+/**
+ * 失败形态分类（#502），只在结果不 ok 时产出：
+ * - no-array：连 `[` 都没有——模型在说话，不是没按格式；
+ * - syntax：有方括号、整体 parse 失败且括号扫描也没救回条目（#339 那一族）；
+ * - filtered-empty：JSON 合法、`arr` 非空，条目却被 VALID 全数滤掉。**这一种最贵**：
+ *   读起来像「没按格式写」，实际是分类词不在枚举内，而游标不推进会让整窗反复重放。
+ */
+function describeParseFailure(arr, entries, salvaged, hasBracket) {
+  if (!Array.isArray(arr) || salvaged) return { kind: hasBracket ? "syntax" : "no-array", arrCount: 0, sampleTypes: [] };
+  if (arr.length === 0) return { kind: "no-array", arrCount: 0, sampleTypes: [] };
+  if (entries.length > 0) return null;
+  const sampleTypes = [...new Set(arr.map((item) => (typeof item?.type === "string" ? item.type.trim() : "")).filter(Boolean))].slice(0, 5);
+  return { kind: "filtered-empty", arrCount: arr.length, sampleTypes };
+}
+
+/**
+ * 失败行的审计读数（纯函数：不驱动整条蒸馏管线也能测）。filtered-empty 的
+ * errorMessage 直接写出 arr/valid 两个数，一眼可辨；metadata 补 failure_kind /
+ * arr_count / invalid_entries / sample_types / raw_tail——尾巴是给「先写几条合法
+ * 条目再跑偏」那种输出准备的，前 300 字看不出来。
+ */
+export function summarizeParseFailureAudit(raw, failure) {
+  const text = String(raw ?? "");
+  const kind = failure?.kind ?? (text.includes("[") ? "syntax" : "no-array");
+  const tail = text.length > 500 ? text.slice(-200) : "";
+  const filtered = kind === "filtered-empty" ? failure : null;
+  return {
+    errorMessage: filtered ? `no valid summary entries (arr=${filtered.arrCount}, valid=0)` : "invalid summary JSON",
+    metadata: {
+      parse_failure: true,
+      failure_kind: kind,
+      raw_len: text.length,
+      raw_head: text.slice(0, 300),
+      ...(tail ? { raw_tail: tail } : {}),
+      raw_has_bracket: text.includes("["),
+      ...(filtered ? { arr_count: filtered.arrCount, invalid_entries: filtered.arrCount, sample_types: filtered.sampleTypes } : {})
+    }
+  };
+}
+
+/** 导出的原因：#502 要能锁住「哪一种失败」这条判据本身，而不是只锁它的下游读数。 */
+export function parseSummaryJsonResult(raw) {
   const text = String(raw ?? "");
   const start = text.indexOf("[");
   const end = text.lastIndexOf("]");
-  if (start === -1 || end === -1 || end <= start) return { ok: false, entries: [] };
+  // 连方括号都没有 = 模型在说话（#493 的 B 臂正是这一型）。早退也要带上下：否则下游
+  // 只能靠「输出里有没有 [」再猜一次，而猜出来的东西不该写进错误消息。
+  if (start === -1 || end === -1 || end <= start) {
+    return { ok: false, entries: [], failure: describeParseFailure(null, [], false, text.includes("[")) };
+  }
   let arr;
   let salvaged = false;
   try {
@@ -77,10 +122,16 @@ function parseSummaryJsonResult(raw) {
   // 空数组表示模型明确判断本轮没有可沉淀内容；非空数组若全部无效，
   // 则不能消费窗口，否则无效输出会永久推进 seq 游标。salvage 路径
   // 没有「显式空数组」可言——ok 只看是否救回了条目。
+  const ok = salvaged ? entries.length > 0 : (arr.length === 0 || entries.length > 0);
   return {
-    ok: salvaged ? entries.length > 0 : (arr.length === 0 || entries.length > 0),
+    ok,
     entries,
-    salvaged
+    salvaged,
+    // #502：失败时要能说出**是哪一种**失败。「压根没写数组」与「写了合法数组、但条目
+    // type 全不在枚举里」过去共用一句 invalid summary JSON，而两者要修的地方完全不同
+    // ——后者是菜单与闸门不一致（summary prompt 只列 4 个类型、VALID 吃 7 个），且失败
+    // 路径游标不推进，同一窗口会被一遍遍重放（社区报告 #493 追加的实测形态）。
+    ...(!ok ? { failure: describeParseFailure(arr, entries, salvaged, text.includes("[")) } : {})
   };
 }
 
@@ -404,12 +455,29 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
     if (seq === undefined) return max;
     return max === undefined ? seq : Math.max(max, seq);
   }, undefined);
+  const transcriptBody = trimTranscript(lines.join("\n"), maxChars);
   return {
     messages: lines.length
-      ? [createUserMessage({ content: [{ type: "text", text: trimTranscript(lines.join("\n"), maxChars) }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } })]
+      ? [createUserMessage({
+        content: [{
+          type: "text",
+          // Issue #493：转录裸放 user 位时，模型把它当成「轮到我说了」接着对话
+          // 往下写，输出里连 `[` 都没有（解析器在括号早退处直接判失败）。围栏 +
+          // 角色重申把「这段文本是被提炼的素材」写进**它所在的那条消息**，而不是
+          // 只写在 system 里——实测同段转录只加 system 约束仍 0/2 出 JSON。
+          // 围栏是确定性的：重试收到的转录与首次逐字节相同（既有回归用例依赖）。
+          text: `${STR.distillRoleReminder[language]}\n\n${STR.transcriptFenceOpen[language]}\n${transcriptBody}\n${STR.transcriptFenceClose[language]}`
+        }],
+        source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" }
+      })]
       : [],
     hasEvents: events.length > 0,
-    lastSeq
+    lastSeq,
+    // Issue #493：只数**转录正文**的字符数。minWindowChars 闸门与审计里的
+    // distillChars 量的都是「这一窗有多少可提炼内容」，不是「我们额外包了多少
+    // 提示词」——若把围栏与角色句算进去，一条「短」也会凭空越过任何阈值，
+    // 闸门随之失效（实测 summarizeMinWindowChars=10 会被 4 字正文 + 包裹放行）。
+    transcriptChars: lines.length ? transcriptBody.length : 0
   };
 }
 
@@ -534,6 +602,10 @@ export function createSummarizer(ctx, service, config, deps = {}) {
   const deferredRuns = new Map();
   // Issue #210：只在一次蒸馏完整成功后记录已消费的最后事件 seq。
   const lastDistilledSeq = new Map();
+  // Issue #493：per-session 连续解析失败计数（失败护栏用）。同一窗口在确定性
+  // 失败下会被每个 turn/end 重试一次、且窗口只会越攒越大——没有出口。成功即
+  // 清零；dispose 一并清理（与 runsUsed / lastRunAt 同生命周期）。
+  const parseFailureStreak = new Map();
   let disposed = false;
 
   /** 写一条 autoSummarize 的 LLM 审计行（审计失败绝不阻塞蒸馏本身）。 */
@@ -701,7 +773,12 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       // summarize_compress 成功行的 metadata 里窗口字符数为 0 条），验收 4「默认配置
       // 下调用量可量化下降」因此无法对账。本改动只加计量，不动任何跳过决策——
       // summarizeMinWindowChars 仍为 0 时行为逐字节不变。
-      const distillChars = messages.reduce(
+      //
+      // Issue #493：口径改为只数转录正文（collected.transcriptChars），不再把
+      // user 消息整段长度当窗口大小——#493 给转录加了围栏与角色句，若继续按
+      // 「消息总字符数」算，一条 4 字的「短」也会被包裹撑过任何阈值，闸门等于
+      // 被自己的提示词旁路掉。
+      const distillChars = collected.transcriptChars ?? messages.reduce(
         (total, message) => total + (Array.isArray(message.content) ? message.content : [])
           .reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0),
         0
@@ -869,12 +946,44 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       const parsedResult = parseSummaryJsonResult(text || assembledText);
       // 解析失败不推进 seq 游标，下一次 turn/end 仍会重试同一窗口。
       if (!parsedResult.ok) {
+        // Issue #493：失败也要留证据。原先 metadata 只在成功路径赋值，失败行恒为
+        // null —— 事后无法回答「模型到底吐了什么形状」。这里只加计量、不做任何
+        // 跳过决策（raw_head 截断到 300 字符，避免把审计表撑大）。
+        const raw = text || assembledText || "";
+        const streak = (parseFailureStreak.get(session.id) ?? 0) + 1;
+        parseFailureStreak.set(session.id, streak);
+        // Issue #493 失败护栏：同一窗口连续失败到阈值后强制消费游标跳过它。
+        // 确定性失败（finish_reason=stop、同文同温）重试收益为 0，而窗口只会随
+        // 新事件继续变大——没有出口时它会一直失败下去。默认 0 = 关闭，行为与
+        // 历史版本逐字节一致（本仓新行为一律 opt-in，见 AGENTS.md）。
+        const maxParseRetries = config.summarizeParseFailureMaxRetries ?? 0;
+        // nextSeq 必须是有限数才算真的「跳过了窗口」：没有可验证的 seq 时
+        // commitCursor 是空操作（persistCursor 早退、内存游标也不写），此时若
+        // 仍按跳过记账并清零 streak，审计会宣称「已放弃」而窗口下一轮照旧重试
+        // —— 那是最坏的一种假象：用户以为止血了，实际还在烧。
+        const skipWindow = maxParseRetries > 0 && streak >= maxParseRetries && Number.isFinite(nextSeq);
+        if (skipWindow) {
+          // 先提交游标再复位计数：窗口已放弃，下一窗从全新状态起算。
+          commitCursor(session.id, nextSeq);
+          parseFailureStreak.delete(session.id);
+        }
         if (audit) {
           audit.status = "error";
-          audit.errorMessage = "invalid summary JSON";
+          // 读数与错误文案由同一个纯函数产出（#502）：三种失败形态各有各的说法，
+          // 「模型在说话」与「分类词不在枚举内」不能都写成 invalid summary JSON。
+          const failureAudit = summarizeParseFailureAudit(raw, parsedResult?.failure);
+          audit.errorMessage = failureAudit.errorMessage;
+          audit.metadata = {
+            distillChars,
+            ...failureAudit.metadata,
+            streak,
+            ...(maxParseRetries > 0 ? { maxRetries: maxParseRetries } : {}),
+            ...(skipWindow ? { skipped: "parse-failure-streak" } : {})
+          };
         }
         return;
       }
+      parseFailureStreak.delete(session.id);
       const parsed = parsedResult.entries;
       // Issue #127 条数上限：0 = 不限（现状）。被截断的条数与去重命中数一并进
       // 审计 metadata——此前产出条数完全由模型输出决定，用户无从自查。
@@ -1064,6 +1173,7 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       inFlight.clear();
       lastRunAt.clear();
       lastDistilledSeq.clear();
+      parseFailureStreak.clear();
     }
   };
 }