dsh-prime-memory 0.11.0 → 0.12.0

package/dist/store/sqlite.js

@@ -20,7 +20,9 @@
 import { createRequire } from 'node:module';
 import { existsSync, mkdirSync } from 'node:fs';
 import * as path from 'node:path';
-import { familyForType, normPersistence } from '../types.js';
+import { familyForType, isScopeVisible, normPersistence, normScope } from '../types.js';
+import { isZeroVector, vecToBuffer } from './vec-utils.js';
+import { normalizeWorkspacePath } from '../workspace.js';
 import { bm25RankToScore, buildFtsQuery, tokenizeForFts } from './search-utils.js';
 import { describeTokenizer, ensureTokenizer, tokenizerStamp } from '../util/tokenizer.js';
 const require = createRequire(import.meta.url);
@@ -30,6 +32,7 @@ const TAG = '[memory][sqlite]';
 import { CostLedger } from './cost-ledger.js';
 // 图谱存储(graph_* 表族)同为独立职责类;init 失败仅图谱 no-op,不传染主库降级
 import { GraphStore } from './graph-store.js';
+import { RECEIPTS_MAX_RUNS, RECEIPTS_QUERY_LIMIT_MAX } from './receipts.js';
 /** vec0 KNN 对遗留零向量的补偿缓冲。 */
 const ZERO_VEC_BUFFER = 10;
 /** IN 查询/删除的分块大小(保守避开 SQLite 变量数上限:现代构建 32766,老版 999)。 */
@@ -285,7 +288,9 @@ export class MemoryDb {
         created_time TEXT DEFAULT '',
         updated_time TEXT DEFAULT '',
         metadata_json TEXT DEFAULT '{}',
-        family TEXT NOT NULL DEFAULT 'chat'
+        family TEXT NOT NULL DEFAULT 'chat',
+        scope TEXT NOT NULL DEFAULT 'global',
+        workspace_id TEXT NOT NULL DEFAULT ''
       )
     `);
         // 旧库缺 family 列 → ALTER 补列,并按 type 前缀回填(幂等:已正确的行不再命中)
@@ -293,6 +298,14 @@ export class MemoryDb {
             this.db.exec("ALTER TABLE l1_records ADD COLUMN family TEXT NOT NULL DEFAULT 'chat'");
             this.logger?.info(`${TAG} l1_records 补 family 列(旧数据按 type 前缀回填)`);
         }
+        // §E 可见范围(ADR-0008 条 3:向后兼容是硬要求)。**既有数据零搬运**——
+        // 补列的 DEFAULT 本身就把存量行标成 `global`,不需要 UPDATE 扫描,
+        // 也不删除任何行:"标注归属"而非"搬运/重建",免得拿事实源冒险换配置项的美观。
+        if (!this.hasColumn('l1_records', 'scope')) {
+            this.db.exec("ALTER TABLE l1_records ADD COLUMN scope TEXT NOT NULL DEFAULT 'global'");
+            this.db.exec("ALTER TABLE l1_records ADD COLUMN workspace_id TEXT NOT NULL DEFAULT ''");
+            this.logger?.info(`${TAG} l1_records 补 scope/workspace_id 列(存量数据默认归 global)`);
+        }
         const backfilled = this.db
             .prepare("UPDATE l1_records SET family = 'work' WHERE type LIKE 'work\\_%' ESCAPE '\\' AND family != 'work'")
             .run().changes;
@@ -305,12 +318,52 @@ export class MemoryDb {
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_updated ON l1_records(updated_time)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_family ON l1_records(family)');
         this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_valid_from ON l1_records(valid_from)');
+        // §E:workspace 过滤的唯一命中路径就是本列(scope='global' 的行走 OR 短路,不依赖索引)
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_workspace ON l1_records(workspace_id)');
+        // ── §B L1 决策凭证(DDL 同为磁盘契约) ──
+        // 每条 L1 记录的 store/update/merge/skip 决策留一条凭证:决策当时看到的候选池
+        // 摘要(input_digest)+ 结论(kind)。凭证必须在事件**之前**存在——输入快照
+        // 无法事后补录,故本表先于任何消费方落地(findings.md §9)。
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS l1_receipts (
+        receipt_id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL DEFAULT '',
+        record_id TEXT NOT NULL DEFAULT '',
+        kind TEXT NOT NULL DEFAULT '',
+        input_digest TEXT NOT NULL DEFAULT '',
+        decided_at TEXT NOT NULL DEFAULT ''
+      )
+    `);
+        // 双维回溯(task_19):按批(run_id)看一轮蒸馏的全部决策;按记录(record_id 看单条记忆的完整判定史
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_receipts_run ON l1_receipts(run_id)');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_l1_receipts_record ON l1_receipts(record_id)');
+        // ── §C 矛盾冻结:(DDL 同为磁盘契约) ──
+        // 冻结**不是"拦住写入"**:新记忆照常入 l1_records,与冲突的旧记忆作为**一对**
+        // 停放在本表,双方内容都不被改写,直到人工裁决。LLM 给的 winner_id 只表示
+        // "进入待裁决对时的排序位",**不代表最终结论**——最终结论落在 resolution。
+        // resolved_at 用 '' 而非 NULL 表示未裁决,与 l1_receipts 的约定一致,
+        // 避免 `= ''` 与 `IS NULL` 两套判据并存。
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS conflict_pending (
+        pair_id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL DEFAULT '',
+        winner_id TEXT NOT NULL DEFAULT '',
+        loser_id TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL DEFAULT '',
+        resolved_at TEXT NOT NULL DEFAULT '',
+        resolution TEXT NOT NULL DEFAULT ''
+      )
+    `);
+        // 未裁决索引:队列上限(task_24,取最旧的未裁决行)与裁决工具(task_25,取单条未裁决对)
+        // 都只关心未裁决行——"查未裁决"须走索引。偏索引同时覆盖 created_at 排序。
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conflict_pending_unresolved
+         ON conflict_pending(created_at) WHERE resolved_at = ''`);
         this.stmtUpsertL1 = this.db.prepare(`
       INSERT INTO l1_records (
         record_id, content, type, priority, scene_name, session_id, version,
         timestamp_str, timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family,
-        valid_from, valid_to, persistence
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        valid_from, valid_to, persistence, scope, workspace_id
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(record_id) DO UPDATE SET
         content=excluded.content,
         type=excluded.type,
@@ -325,12 +378,14 @@ export class MemoryDb {
         family=excluded.family,
         valid_from=excluded.valid_from,
         valid_to=excluded.valid_to,
-        persistence=excluded.persistence
+        persistence=excluded.persistence,
+        scope=excluded.scope,
+        workspace_id=excluded.workspace_id
     `);
         this.stmtGetL1 = this.db.prepare(`
       SELECT record_id, content, type, priority, scene_name, version, timestamp_str,
              timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family,
-             valid_from, valid_to, persistence
+             valid_from, valid_to, persistence, scope, workspace_id
       FROM l1_records WHERE record_id = ?
     `);
         this.stmtL1Exists = this.db.prepare('SELECT 1 FROM l1_records WHERE record_id = ?');
@@ -366,7 +421,10 @@ export class MemoryDb {
         // ── token_cost:蒸馏成本明细表(成本账本自治) ──
         this.costLedger.init(this.db, this.logger);
         // ── graph_*:知识图谱投影表族(GraphStore.init 自带 try/catch,失败仅图谱 no-op) ──
-        this.graphStore.init(this.db, this.logger);
+        // §F 节点向量列的维度**复用既有探测结果**（`vecLoaded` / `dimensions` 由
+        // `prepareL1VecStatements` 之前的探测决定），不新增一套能力探测。探测未通过 →
+        // 不传 → 图谱向量路结构性不存在（不建表、不告警、不抛）。
+        this.graphStore.init(this.db, this.logger, this.vecLoaded && this.dimensions > 0 ? { dimensions: this.dimensions } : undefined);
         // ── FTS5 全文索引(建表失败仅停用 FTS,不降级整个库) ──
         try {
             // 索引重建判据(FTS5 无法 ALTER,只能 drop 后从源表全量回灌):
@@ -376,10 +434,10 @@ export class MemoryDb {
             const savedStamp = this.readMetaString('fts_tokenizer') ?? 'bigram-v1';
             const tokenizerChanged = savedStamp !== wantStamp;
             let ftsRebuilt = false;
-            if (this.tableExists('l1_fts') && (!this.hasColumn('l1_fts', 'family') || tokenizerChanged)) {
+            if (this.tableExists('l1_fts') && (!this.hasColumn('l1_fts', 'family') || !this.hasColumn('l1_fts', 'scope') || tokenizerChanged)) {
                 this.db.exec('DROP TABLE l1_fts');
                 ftsRebuilt = true;
-                this.logger?.info(`${TAG} l1_fts 缺 family 列或分词器已变更(${savedStamp} → ${wantStamp}),重建全文索引`);
+                this.logger?.info(`${TAG} l1_fts 缺 family/scope 列或分词器已变更(${savedStamp} → ${wantStamp}),重建全文索引`);
             }
             let l0FtsRebuilt = false;
             if (this.tableExists('l0_fts') && tokenizerChanged) {
@@ -401,7 +459,9 @@ export class MemoryDb {
           timestamp_start UNINDEXED,
           timestamp_end UNINDEXED,
           metadata_json UNINDEXED,
-          family UNINDEXED
+          family UNINDEXED,
+          scope UNINDEXED,
+          workspace_id UNINDEXED
         )
       `);
             this.db.exec(`
@@ -417,26 +477,33 @@ export class MemoryDb {
       `);
             this.stmtL1FtsInsert = this.db.prepare(`
         INSERT INTO l1_fts (content, content_original, record_id, type, priority, scene_name,
-          session_id, version, timestamp_str, timestamp_start, timestamp_end, metadata_json, family)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          session_id, version, timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
+          scope, workspace_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
             this.stmtL1FtsDelete = this.db.prepare('DELETE FROM l1_fts WHERE record_id = ?');
+            // §E 可见范围过滤的**唯一缝**。设计要点:
+            // ① `? = ''` 是"不过滤"的哨兵——检索侧不传工作区标识(即 cfg.scope='global')时
+            //    整个条件短路为真,行为与改动前逐字一致(**零漂移不是比对出来的,是构造出来的**);
+            // ② 过滤表达式与 family 落在**同一条语句**里(ADR-0008 组合关系:scope 过滤必须与
+            //    族隔离同层),否则会产出"看不见但已影响决策"的记忆——去重候选召回也走这里;
+            // ③ `scope = 'global'` 分支让跨工作区可见的记忆在任何工作区都能被召回。
             this.stmtL1FtsSearch = this.db.prepare(`
         SELECT record_id, content_original AS content, type, priority, scene_name, version,
-               timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
+               timestamp_str, timestamp_start, timestamp_end, metadata_json, family, scope, workspace_id,
                bm25(l1_fts) AS rank
         FROM l1_fts
-        WHERE l1_fts MATCH ?
+        WHERE l1_fts MATCH ? AND (? = '' OR scope = 'global' OR workspace_id = ?)
         ORDER BY rank ASC
         LIMIT ?
       `);
             // 族过滤版(FTS5 UNINDEXED 列可作行级过滤条件)
             this.stmtL1FtsSearchFamily = this.db.prepare(`
         SELECT record_id, content_original AS content, type, priority, scene_name, version,
-               timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
+               timestamp_str, timestamp_start, timestamp_end, metadata_json, family, scope, workspace_id,
                bm25(l1_fts) AS rank
         FROM l1_fts
-        WHERE l1_fts MATCH ? AND family = ?
+        WHERE l1_fts MATCH ? AND family = ? AND (? = '' OR scope = 'global' OR workspace_id = ?)
         ORDER BY rank ASC
         LIMIT ?
       `);
@@ -565,15 +632,26 @@ export class MemoryDb {
             this.logger?.info(`${TAG} l1_records 补 ${column} 列(时间增强)`);
         }
     }
-    /** 重建后的 l1_fts 从 l1_records 全量回灌(仅在 drop 重建时调用;iterate 流式防大库内存峰值)。 */
+    /**
+     * 重建后的 l1_fts 从 l1_records 全量回灌(仅在 drop 重建时调用;iterate 流式防大库内存峰值)。
+     *
+     * ⚠️ 本函数的参数列表**必须与 `stmtL1FtsInsert` 逐位对齐**。不对齐时 node:sqlite 会在这里抛错,
+     * 而下面的 `catch` 是**逐行吞掉**的——症状是 `count` 停在 0、索引静默变空,
+     * 全库记录从此全文检索不可见却没有任何错误日志。§E 加列时正是这个位置最容易漏
+     * (三处列清单:DDL / insert 语句 / 本函数),故在此留下警示。
+     */
     backfillL1Fts() {
         let count = 0;
         const stmt = this.db
             .prepare(`SELECT record_id, content, type, priority, scene_name, session_id, version,
-                timestamp_str, timestamp_start, timestamp_end, metadata_json, family FROM l1_records`);
+                timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
+                scope, workspace_id FROM l1_records`);
         for (const r of stmt.iterate()) {
             try {
-                this.stmtL1FtsInsert.run(tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'));
+                this.stmtL1FtsInsert.run(tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'), 
+                // §E:回灌必须带上可见范围——漏掉这两列等于**每次 FTS 重建都把隔离抹平**
+                // (所有行回落 'global',跨工作区记忆瞬间互相可见),且没有任何报错。
+                normScope(r.scope), String(r.workspace_id ?? ''));
                 count++;
             }
             catch {
@@ -712,12 +790,26 @@ export class MemoryDb {
         const priority = record.priority ?? 50;
         const sceneName = record.scene_name ?? '';
         const family = record.family ?? familyForType(type);
+        // §E 写入侧兜底归一,并维持一条**不变量**:`scope='global'` 的记录 `workspace_id` 恒为空串。
+        // 不维持它就会出现"标着 global 却带着工作区归属"的行——语义含糊,且日后改判定时
+        // 无法区分"全局可见但顺带记了个 id"与"其实属于某工作区"。写入侧算好归属
+        // (pipeline 用 `resolveRecordScope`),这里只保证不变量,不重新决策。
+        //
+        // ⚠️ **形态归一必须在这里做**（不是"顺便"）：检索侧传入的标识经 `workspaceIdOf`
+        // 归一（Windows 转小写、resolve 掉 `..`），而写入侧若原样存调用方给的字符串，
+        // 同一个工作区会以两种拼写落库 → `isScopeVisible` 的字符串相等判定必然落空
+        // → **记忆写进去却再也查不出来**。这一条曾被端到端测试抓出
+        // （`tests/scope-tool-wiring.test.ts` 的 `expected 1 to be 2`），
+        // 当时的实现只做了"清空"归一而漏了"形态"归一。收在存储层是因为调用方不止一个
+        // （pipeline / memory_add / 外部导入），逐个记得归一迟早漏一个。
+        const scope = normScope(record.scope);
+        const workspaceId = scope === 'workspace' ? (normalizeWorkspacePath(record.workspaceId) ?? '') : '';
         // 防御性 FTS 删除的前置点查(主键索引,微秒级):record_id 在 FTS 表是 UNINDEXED,
         // 按 id DELETE 是 O(N) 全表扫描——导入/重建/重嵌等"全新增"路径曾为每条记录白付一次
         // 全扫(批量写整体 O(N²))。只有主表已有该行(覆盖/合并)才可能有旧 FTS 行需要删。
         // 同批重复 id 也能正确处理:首条插入后,第二条的点查在同一事务内已见新行。
         const ftsExisted = this.ftsAvailable ? this.stmtL1Exists.get(record.id) !== undefined : false;
-        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '');
+        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family, toIso(record.validFrom), toIso(record.validTo), normPersistence(record.persistence) ?? '', scope, workspaceId);
         // vec0 不支持 ON CONFLICT → 先删后插;零向量跳过(cosine 未定义)
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
             this.stmtDeleteL1Vec.run(record.id);
@@ -730,7 +822,7 @@ export class MemoryDb {
         if (this.ftsAvailable) {
             if (ftsExisted)
                 this.stmtL1FtsDelete.run(record.id);
-            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family);
+            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family, scope, workspaceId);
         }
     }
     /** 批量删除 L1(元数据 + 向量 + FTS),返回删除条数。IN 按 ≤900 分块(避变量数上限)。
@@ -769,8 +861,11 @@ export class MemoryDb {
             const temporal = table === 'l1_records' && this.hasColumn('l1_records', 'valid_from')
                 ? ', valid_from, valid_to, persistence'
                 : '';
+            // §E:同款按形状探测——未迁移的旧库(补列前)不应因缺列让"按 id 取记录"整条路径失败。
+            const scopeCols = table === 'l1_records' && this.hasColumn('l1_records', 'scope') ? ', scope, workspace_id' : '';
             const metaCols = 'record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family' +
-                temporal;
+                temporal +
+                scopeCols;
             stmt =
                 action === 'delete'
                     ? this.db.prepare(`DELETE FROM ${table} WHERE record_id IN (${ph})`)
@@ -830,7 +925,7 @@ export class MemoryDb {
         if (this.degraded)
             return [];
         const rows = this.db
-            .prepare('SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence FROM l1_records')
+            .prepare('SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id FROM l1_records')
             .all();
         return rows.map(rowToRecord);
     }
@@ -843,7 +938,194 @@ export class MemoryDb {
         }
         return rows.map(rowToRecord);
     }
-    /** 浏览列表(UI 用):按更新时间倒序,支持类型/场景/族/Hall 过滤与分页。失败返回空。 */
+    /**
+     * §B 决策凭证批量落盘。`INSERT OR IGNORE` + 确定性 `receipt_id`
+     * (见 `receipts.ts` 的 `receiptIdFor`)→ 同一次 run 重放不产生重复行。
+     * 返回实际新增条数(被忽略的重复不计)。
+     *
+     * 刻意**不开事务**:凭证是旁路观测数据,单条独立、重放幂等,部分写入无害;
+     * 为它引入事务只会把失败面扩大。调用方另有 `persistReceiptsSafely` 兜底不抛。
+     *
+     * 写入后**顺带执行保留策略**(task_18)。把裁剪挂在这里而不是交给调用方,
+     * 是为了让"有界"成为**结构性保证**:任何写路径都不可能忘记裁剪,
+     * 因而表容量不可能随使用时间无界增长。裁剪自身失败只 warn——
+     * 它是省空间的动作,失败了最坏是这次没省下来,绝不能因此弄丢刚落盘的凭证
+     * (故裁剪在写入**之后**,且包在 try 里)。
+     */
+    recordReceipts(rows, opts) {
+        if (this.degraded || rows.length === 0)
+            return 0;
+        const stmt = this.db.prepare(`INSERT OR IGNORE INTO l1_receipts (receipt_id, run_id, record_id, kind, input_digest, decided_at)
+       VALUES (?, ?, ?, ?, ?, ?)`);
+        let n = 0;
+        for (const r of rows) {
+            n += Number(stmt.run(r.receiptId, r.runId, r.recordId, r.kind, r.inputDigest, r.decidedAt).changes);
+        }
+        try {
+            this.trimReceipts(opts?.maxRuns ?? RECEIPTS_MAX_RUNS);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 决策凭证裁剪失败,本次不回收空间(**凭证已正常落盘,记忆与回溯不受影响**): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return n;
+    }
+    /**
+     * §C 矛盾冻结(task_22):落盘待裁决冲突对。
+     *
+     * `INSERT OR IGNORE`——幂等来自 **pair_id 主键**而非调用方自觉:
+     * `conflictPairId(runId, winner, loser)` 对同一三元组恒等,故一轮蒸馏重复落盘
+     * 只会得到一行。与 §B 凭证同一手法(那边是 `receipt_id` 主键)。
+     *
+     * 与凭证不同,这里**不做保留裁剪**:待裁决对是**欠人的债**,不是观测数据。
+     * 裁剪它等于把用户还没看的裁决请求悄悄删掉,那是丢工作而不是省空间。
+     * 有界性交给 task_24 的队列上限(超限不再停放、回落自动裁决),语义是
+     * 「**不收新的**」而非「**偷偷删旧的**」。
+     *
+     * @returns 实际新插入的行数。
+     */
+    recordConflictPending(rows) {
+        if (this.degraded || rows.length === 0)
+            return 0;
+        const stmt = this.db.prepare(`INSERT OR IGNORE INTO conflict_pending
+         (pair_id, run_id, winner_id, loser_id, created_at, resolved_at, resolution)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        let n = 0;
+        for (const r of rows) {
+            n += Number(stmt.run(r.pairId, r.runId, r.winnerId, r.loserId, r.createdAt, r.resolvedAt, r.resolution).changes);
+        }
+        return n;
+    }
+    /** §C 冻结:把图谱 `disputed` 状态同步到给定冲突集(薄缝,便于单测替换)。 */
+    syncGraphDisputed(disputedRecordIds) {
+        if (this.degraded)
+            return { marked: 0, cleared: 0 };
+        return this.graphStore.syncDisputed(disputedRecordIds);
+    }
+    /**
+     * §C 冻结队列的**未裁决**条数(task_24 队列上限判据)。
+     * 走 `idx_conflict_pending_unresolved` 偏索引,不是全表扫描。
+     */
+    countConflictPendingUnresolved() {
+        if (this.degraded)
+            return 0;
+        const row = this.db.prepare(`SELECT COUNT(*) AS n FROM conflict_pending WHERE resolved_at = ''`).get();
+        return Number(row?.n ?? 0);
+    }
+    /**
+     * §C 取未裁决冲突对(task_24 超时扫描 / task_25 裁决工具)。
+     *
+     * `createdBefore` 为**排他上界**(ISO 串):只取该时刻之前创建的,用于超时判定。
+     * 定序 `created_at ASC, pair_id ASC`——先来先服务,且同一毫秒内仍**确定可复现**。
+     */
+    listConflictPending(opts = {}) {
+        if (this.degraded)
+            return [];
+        const limit = Number.isFinite(opts.limit) && (opts.limit ?? 0) > 0 ? Math.floor(opts.limit) : 500;
+        const params = [];
+        let where = `resolved_at = ''`;
+        if (opts.createdBefore) {
+            where += ` AND created_at < ?`;
+            params.push(opts.createdBefore);
+        }
+        const rows = this.db
+            .prepare(`SELECT pair_id, run_id, winner_id, loser_id, created_at, resolved_at, resolution
+           FROM conflict_pending WHERE ${where}
+          ORDER BY created_at ASC, pair_id ASC LIMIT ?`)
+            .all(...params, limit);
+        return rows.map(toConflictPair);
+    }
+    /**
+     * §C 打上裁决结论。
+     *
+     * `WHERE resolved_at = ''` 使**已裁决的不会被覆盖**:裁决是一次性的判定行为,
+     * 重复调用不该把第一次的结论改写掉(人工裁决与自动了结的次序因此不可逆)。
+     *
+     * @returns 受影响行数(0 = 该对被裁决过或不存在)。
+     */
+    resolveConflictPending(pairId, resolution, resolvedAt) {
+        if (this.degraded)
+            return 0;
+        const stmt = this.db.prepare(`UPDATE conflict_pending SET resolved_at = ?, resolution = ?
+        WHERE pair_id = ? AND resolved_at = ''`);
+        return Number(stmt.run(resolvedAt, resolution, pairId).changes);
+    }
+    /**
+     * §B 凭证保留策略(task_18):只保留**最新**的 `maxRuns` 个 run,更老的整批删除。
+     * 返回被删除的行数。
+     *
+     * 两条刻意的约束:
+     * - **粒度是 run,不是行**。按行裁剪会切出"半截批次",而 task_19 的按 run 回溯
+     *   正是要回答"这一轮蒸馏都判了什么"——一个少了尾巴的批次会给出**看似完整、
+     *   实则遗漏**的结论,比查不到更糟。整批留、整批删,回溯的原子性才有保证。
+     * - **只碰 `l1_receipts`,绝不碰 `l1_records`**。前者是可再生/可丢弃的观测数据,
+     *   后者是用户的事实源。为省几 MB 而波及记忆本体,是把容量优化做成了数据丢失。
+     *
+     * `maxRuns <= 0` 或非有限值一律**不裁剪**——"传 0 即清空"是个太容易被误触的
+     * 语义,宁可把它定义为无效输入。
+     *
+     * 定序取每 run 的 `MAX(decided_at)`(凭证的 decided_at 在一批内恒定)并以
+     * `run_id` 兜底,使同一时刻产生的多个 run 也有**确定**的相对序,裁剪结果可复现。
+     */
+    trimReceipts(maxRuns) {
+        if (this.degraded)
+            return 0;
+        if (!Number.isFinite(maxRuns) || maxRuns <= 0)
+            return 0;
+        const stmt = this.db.prepare(`DELETE FROM l1_receipts WHERE run_id NOT IN (
+         SELECT run_id FROM l1_receipts
+          GROUP BY run_id
+          ORDER BY MAX(decided_at) DESC, run_id DESC
+          LIMIT ?
+       )`);
+        return Number(stmt.run(Math.floor(maxRuns)).changes);
+    }
+    /**
+     * §B 双维回溯(task_19):按 `record_id` / `run_id` 查判定史,两维同给为 **AND**。
+     *
+     * 两条刻意的行为:
+     * - **两维都不给返回空,而不是全表**。「查全部凭证」不是本能力的目标;把缺参
+     *   兜成全表,会让一次误调用变成全库判定史导出。调用方本就该先拒绝这种用法
+     *   (工具层给提示、端点层直接报错),这里是第二道,方向一致。
+     * - **定序确定**:`decided_at DESC, run_id DESC`。回溯的价值在于可复现——
+     *   同一问题两次问出不同顺序,核对时就会怀疑是不是数据变了。`run_id` 兜底
+     *   同一毫秒内的多批(L1 蒸馏是 LLM 调用,同刻两批罕见但非不可能)。
+     *   新的在前,与 `listL1` 的倒序口径一致。
+     */
+    listReceipts(opts) {
+        if (this.degraded)
+            return [];
+        const where = receiptWhere(opts);
+        if (where === null)
+            return [];
+        const limit = Math.min(Math.max(Math.floor(opts.limit) || 1, 1), RECEIPTS_QUERY_LIMIT_MAX);
+        const rows = this.db
+            .prepare(`SELECT receipt_id, run_id, record_id, kind, input_digest, decided_at
+           FROM l1_receipts WHERE ${where.sql}
+          ORDER BY decided_at DESC, run_id DESC
+          LIMIT ?`)
+            .all(...where.params, limit);
+        return rows.map((r) => ({
+            receiptId: r.receipt_id,
+            runId: r.run_id,
+            recordId: r.record_id,
+            kind: r.kind,
+            inputDigest: r.input_digest,
+            decidedAt: r.decided_at,
+        }));
+    }
+    /** 同维度命中的**总条数**(不受 limit 影响,供"还有多少条没显示"提示)。 */
+    countReceipts(opts) {
+        if (this.degraded)
+            return 0;
+        const where = receiptWhere(opts);
+        if (where === null)
+            return 0;
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM l1_receipts WHERE ${where.sql}`)
+            .get(...where.params);
+        return Number(row.n);
+    }
+    /** 浏览列表(UI 用):按更新时间倒序,支持类型/场景/族/Hall/可见范围过滤与分页。失败返回空。 */
     listL1(opts) {
         if (this.degraded)
             return { items: [], total: 0 };
@@ -862,6 +1144,11 @@ export class MemoryDb {
                 where.push('family = ?');
                 params.push(opts.family);
             }
+            // §E 可见范围(缺省不过滤):global 记录 + 本工作区记录。与检索路径同一条判据。
+            if (opts.workspaceId) {
+                where.push("(scope = 'global' OR workspace_id = ?)");
+                params.push(opts.workspaceId);
+            }
             if (opts.hall) {
                 // Hall 存于 metadata_json,用 json_extract 过滤(表小,逐行代价可接受)
                 where.push(`json_extract(metadata_json, '$.hall') = ?`);
@@ -870,7 +1157,7 @@ export class MemoryDb {
             const whereSql = where.length > 0 ? ` WHERE ${where.join(' AND ')}` : '';
             const totalRow = this.db.prepare(`SELECT COUNT(*) AS n FROM l1_records${whereSql}`).get(...params);
             const rows = this.db
-                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence FROM l1_records${whereSql} ORDER BY updated_time DESC LIMIT ? OFFSET ?`)
+                .prepare(`SELECT record_id, content, type, priority, scene_name, version, timestamp_str, created_time, updated_time, metadata_json, family, valid_from, valid_to, persistence, scope, workspace_id FROM l1_records${whereSql} ORDER BY updated_time DESC LIMIT ? OFFSET ?`)
                 .all(...params, opts.limit, opts.offset);
             return { items: rows.map(rowToRecord), total: totalRow?.n ?? 0 };
         }
@@ -896,17 +1183,19 @@ export class MemoryDb {
     // ============================
     // L1 检索
     // ============================
-    /** FTS5 BM25 检索(family 缺省不过滤)。失败返回空数组(调用方降级)。 */
-    searchL1Fts(query, limit, family) {
+    /** FTS5 BM25 检索(family / workspaceId 缺省不过滤)。失败返回空数组(调用方降级)。 */
+    searchL1Fts(query, limit, family, workspaceId) {
         if (this.degraded || !this.ftsAvailable || limit <= 0)
             return [];
         const ftsQuery = buildFtsQuery(query);
         if (!ftsQuery)
             return [];
+        // 哨兵:'' = 不做可见范围过滤(与 SQL 里的 `? = ''` 分支对应)
+        const ws = workspaceId ?? '';
         try {
             const rows = (family
-                ? this.stmtL1FtsSearchFamily.all(ftsQuery, family, limit)
-                : this.stmtL1FtsSearch.all(ftsQuery, limit));
+                ? this.stmtL1FtsSearchFamily.all(ftsQuery, family, ws, ws, limit)
+                : this.stmtL1FtsSearch.all(ftsQuery, ws, ws, limit));
             return rows.map((r) => ({
                 id: r.record_id,
                 content: r.content,
@@ -922,13 +1211,17 @@ export class MemoryDb {
             return [];
         }
     }
-    /** vec0 余弦 KNN 检索(score = 1 - cosine distance;family 过滤走过度召回 + 回查过滤,vec0 无法 WHERE)。失败返回空数组。 */
-    searchL1Vector(embedding, topK, family) {
+    /**
+     * vec0 余弦 KNN 检索(score = 1 - cosine distance)。失败返回空数组。
+     * family / workspaceId 过滤走**过度召回 + 回查过滤**(vec0 无法 WHERE)。
+     * 放大倍数对两条轴**相乘**:两轴各自丢弃行,单独放大任一条都不够。
+     */
+    searchL1Vector(embedding, topK, family, workspaceId) {
         if (this.degraded || !this.stmtSearchL1Vec || topK <= 0)
             return [];
         try {
-            // 过度召回补偿遗留零向量;带族过滤时再放大(不命中本族的行会被丢弃)
-            const retrieveCount = (topK + ZERO_VEC_BUFFER) * (family ? 3 : 1);
+            // 过度召回补偿遗留零向量;带过滤时再放大(不命中过滤条件的行会被丢弃)
+            const retrieveCount = (topK + ZERO_VEC_BUFFER) * (family ? 3 : 1) * (workspaceId ? 3 : 1);
             const rows = this.stmtSearchL1Vec.all(vecToBuffer(embedding), retrieveCount);
             const hits = [];
             for (const { record_id, distance } of rows) {
@@ -939,6 +1232,8 @@ export class MemoryDb {
                     continue;
                 if (family && normFamily(meta.family, meta.type) !== family)
                     continue;
+                if (workspaceId && !isScopeVisible(meta.scope, meta.workspace_id, workspaceId))
+                    continue;
                 hits.push({
                     id: record_id,
                     content: meta.content,
@@ -1429,14 +1724,47 @@ function rowToRecord(row) {
         version: row.version ?? 0,
         metadata,
         family: normFamily(row.family, row.type),
+        // §E:读回时归一(缺列/缺值一律 global)——"读不到归属"等价于"跨工作区可见",
+        // 与写入侧 fail-open 同向:宁可退化成全局可见,也不让记忆凭空消失。
+        scope: normScope(row.scope),
+        workspaceId: row.workspace_id ?? '',
         // 时间轴回读:空串 → undefined(空串表示"未填",不是"时间 0")
         validFrom: row.valid_from ? Date.parse(row.valid_from) || undefined : undefined,
         validTo: row.valid_to ? Date.parse(row.valid_to) || undefined : undefined,
         persistence: normPersistence(row.persistence),
     };
 }
-/** epoch 数组 → {逗号连接 ISO, 首尾 ISO}(磁盘格式契约:逗号连接、升序、ISO)。 */
-function timestampsToDb(ts) {
+/**
+ * 双维回溯的 WHERE 构造。返回 `null` 表示**二维皆缺**——调用方据此返回空,
+ * 而不是拼出无 WHERE 的全表扫描(那会把误用变成全库导出)。
+ * 两维同给时按 `AND` 组合:问的是"这条记录在那一轮里被判成了什么"。
+ */
+function receiptWhere(q) {
+    const sql = [];
+    const params = [];
+    if (q.recordId) {
+        sql.push('record_id = ?');
+        params.push(q.recordId);
+    }
+    if (q.runId) {
+        sql.push('run_id = ?');
+        params.push(q.runId);
+    }
+    return sql.length === 0 ? null : { sql: sql.join(' AND '), params };
+}
+/** `conflict_pending` 行 → {@link ConflictPair}(snake_case 只活在这一层)。 */
+function toConflictPair(r) {
+    return {
+        pairId: String(r.pair_id ?? ''),
+        runId: String(r.run_id ?? ''),
+        winnerId: String(r.winner_id ?? ''),
+        loserId: String(r.loser_id ?? ''),
+        createdAt: String(r.created_at ?? ''),
+        resolvedAt: String(r.resolved_at ?? ''),
+        resolution: String(r.resolution ?? ''),
+    };
+}
+/** epoch 数组 → {逗号连接 ISO, 首尾 ISO}(磁盘格式契约:逗号连接、升序、ISO)。 */ function timestampsToDb(ts) {
     if (!ts || ts.length === 0)
         return { str: '', start: '', end: '' };
     const sorted = [...ts].filter((t) => Number.isFinite(t)).sort((a, b) => a - b);
@@ -1458,14 +1786,6 @@ function toIso(epochMs) {
         return '';
     return new Date(epochMs).toISOString();
 }
-/** 全零向量(cosine 未定义,不可入向量表)。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
-export function isZeroVector(vec) {
-    for (const v of vec) {
-        if (v !== 0)
-            return false;
-    }
-    return true;
-}
 /** NOT IN 片段(空集 → 空串;配合 notInParams 使用)。 */
 function notInClause(column, exclude) {
     if (!exclude || exclude.size === 0)
@@ -1486,6 +1806,6 @@ function normFamily(raw, type) {
         return raw;
     return familyForType(type);
 }
-function vecToBuffer(vec) {
-    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
-}
+// 向量编码工具的实现已抽到 `vec-utils.ts`（避免 sqlite ↔ graph-store 形成模块环），
+// 此处 re-export 保持既有外部导入点不变；文件内部使用走上方 import。
+export { isZeroVector, vecToBuffer };

package/dist/store/vec-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * vec0 编码工具:抽取向量 ↔ Buffer 的**唯一**编码约定。
+ *
+ * 为什么单独一个文件:`l1_vec` / `l0_vec`（在 `sqlite.ts`）与 `graph_node_vec`
+ * （在 `graph-store.ts`）必须用**同一种**二进制编码，否则同一份 vec0 扩展会出现
+ * 两种字节布局。而 `sqlite.ts` 已经 import 了 `GraphStore`——若让 `graph-store.ts`
+ * 反过来 import `sqlite.ts`，就形成模块环：能跑，但生死取决于加载顺序，
+ * 属于"隐式依赖"，不是可以留在代码里的东西。
+ */
+/** 全零向量(cosine 未定义,不可入向量表)。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
+export declare function isZeroVector(vec: Float32Array): boolean;
+/**
+ * Float32Array → Buffer（零拷贝视图，共享底层 ArrayBuffer）。
+ * vec0 的 `float[N]` 列按 little-endian 连续 float32 读取，这正是该视图的布局。
+ */
+export declare function vecToBuffer(vec: Float32Array): Buffer;