dsh-prime-memory 0.11.0 → 0.12.0

package/dist/store/receipts.d.ts

@@ -0,0 +1,157 @@
+/** 摘要格式版本。进入 canonical 串,使算法演进时**不会静默**让新旧凭证看起来可比。 */
+export declare const DIGEST_FORMAT = "l1-receipts/v1";
+/**
+ * 候选池**有序序列** → 稳定摘要(sha256 hex)。
+ *
+ * 语义:`searchCandidates` 返回的是**已排序**的候选池,「当时看到哪些候选、按什么序」
+ * 就是去重决策的输入。故本函数**顺序敏感**——换个序即不同摘要,而不是把候选当集合。
+ *
+ * 三项刻意的设计:
+ * - **顺序敏感**:见上。集合语义会丢掉"哪条候选排在最前"这一信息。
+ * - **重复不折叠**:`['r1','r1']` 与 `['r1']` 摘要不同。候选池里的重复本身是事实
+ *   (例如同一记录被两条通路召回),折叠掉等于篡改输入。
+ * - **长度前缀编码**:逐项写 `${len}:${id}\n` 而非直接拼接。否则 `['a|b']` 与
+ *   `['a','b']`(以及 `['a\nb']` 与 `['a','b']`)会碰撞——分隔符出现在 id 里时,
+ *   序列化就不再是单射,摘要也就失去了作为输入指纹的意义。
+ *
+ * 纯函数:无 I/O、无时间、无随机。同输入**恒**同输出,这是凭证可复算的前提。
+ */
+export declare function inputDigest(candidateIds: readonly string[]): string;
+/**
+ * 凭证保留上限:**最多保留多少个 run**。
+ *
+ * 为什么按 **run 数**而不是按天数(§B task_18):
+ * 本策略要防的是「`memory.db` 无限增长」。时间窗口**给不出这个保证**——
+ * 阈值(比如 90 天)与写入速率无关,一个高频用户 90 天能写进任意多行,
+ * 无界增长只是被推迟,不是被消除。run 数上限则**直接给出行的上界**
+ * (`maxRuns × 每 run 记录数`),这是"有界"与"看起来有界"的区别。
+ * 代价是:一个几乎不用的用户,历史可能只剩最近 1000 次蒸馏——
+ * 但凭证是**诊断设施**,诊断需要的是"最近发生了什么",不是考古。
+ *
+ * 1000 这个量级的依据:一轮 L1 蒸馏通常落 5~20 条凭证,故上限约 1~2 万行
+ * (数 MB 量级,在同为单文件的 `memory.db` 里不构成压力);而 L1 蒸馏本身要
+ * 调一次 LLM,现实中每小时至多几次——1000 轮 ≈ 活跃使用数月。
+ *
+ * **为什么是常量而不是配置项**:配置项要接 schema、契约与设置页,为一个
+ * 诊断表的容量引入用户可见面,收益与面积不成比例(YAGNI)。真需要调,
+ * 改这里即可,且 `recordReceipts(rows, { maxRuns })` 已留出显式注入口。
+ */
+export declare const RECEIPTS_MAX_RUNS = 1000;
+/** 裁剪策略的可选入参。省略时用 {@link RECEIPTS_MAX_RUNS}。 */
+export interface ReceiptRetentionOptions {
+    /** 最多保留的 run 数;<=0 或非有限值视为"不裁剪"。 */
+    maxRuns?: number;
+}
+/**
+ * 凭证的决策类型。
+ * - 前四项是 LLM 明确给出的动作;
+ * - `skip_missing` 表示**根本没拿到可用决策**(模型没返回 / 返回了非法动作)。
+ *   刻意与 `skip` 分开:回溯"这条为什么没进记忆"时,「模型决定不存」与
+ *   「模型没答」是完全不同的两件事,合并会让 §B 失去一半诊断力。
+ * - `conflict`(§C 矛盾冻结)同样是**明确决策**,只是结论为"我判不了,交给人"。
+ *   它必须与 `skip_missing` 分开:漏登记会把这轮记成"模型没答",
+ *   而审计链据此得出的结论(这轮没决策)与事实(模型明确说了判不了)**正好相反**。
+ */
+export type L1ReceiptKind = 'store' | 'update' | 'merge' | 'skip' | 'conflict' | 'skip_missing';
+/** 一条凭证(与 `l1_receipts` 表一行同形)。 */
+export interface L1Receipt {
+    receiptId: string;
+    runId: string;
+    recordId: string;
+    kind: L1ReceiptKind;
+    inputDigest: string;
+    decidedAt: string;
+}
+/** 构建凭证所需的单条输入(与 `runExtraction` 的 `matches` 逐项对应)。 */
+export interface ReceiptInput {
+    recordId: string;
+    /** 该次判定召回的候选池(有序,顺序进入摘要)。 */
+    candidateIds: readonly string[];
+    /** 模型给出的动作;缺失/非法时传 undefined。 */
+    action: string | undefined;
+}
+/**
+ * §B 双维回溯的查询入参(task_19)。
+ *
+ * 两个维度对应两类**互不替代**的问题,故同为可选、同给时为 **AND**:
+ * - 只给 `recordId` →「这条记忆**出自哪一轮**,当时看到什么候选池、被判成了什么」
+ * - 只给 `runId`    →「上一轮蒸馏都判了什么」(那一批的全部决策,跨多条记录)
+ * - 两维同给        →「这条记录在那一轮里被判成了什么」(唯一一条)
+ *
+ * **`recordId` 维度的取值面必须如实说清**:`pipeline/l1.ts` 对每条抽取结果执行
+ * `record_id: newId('mem')`——**每轮新铸 id,从不复用**。故一个 `record_id`
+ * 在现实中只可能属于**一轮** run,该维度目前**恒返回 0 或 1 行**。
+ * 它回答的是「出自哪」,不是「历次变更」;查询层按可多行实现(一旦将来复用 id,
+ * 或模型给的 id 被沿用,无需改这里),但**不要拿"判定史"这种说法承诺现状**——
+ * 这是本任务执行期发现并修正的一处**说过头**。
+ *
+ * **两维都不给不是"查全部"**:那会让一次误调用变成全库判定史导出。调用方
+ * (工具层 / 端点层)必须先拒绝这种用法;数据层在此再兜一层,返回空而非全表。
+ */
+export interface ReceiptQuery {
+    recordId?: string;
+    runId?: string;
+}
+/** 二维回溯命中的是哪个维度(供调用方与用户确认"我查的是哪一类问题")。 */
+export type ReceiptDimension = 'record' | 'run' | 'both' | 'none';
+export declare function dimensionOf(q: ReceiptQuery): ReceiptDimension;
+/**
+ * 回放视图的一行。**snake_case 且与 DB 列同形**——凭证是给人核对的原始证据,
+ * 中间再套一层 camelCase 命名只会让"表里写的"与"工具吐的"对不上,
+ * 核对时多一次心算就是多一次出错机会。
+ */
+export interface ReceiptView {
+    receipt_id: string;
+    run_id: string;
+    record_id: string;
+    kind: L1ReceiptKind;
+    input_digest: string;
+    decided_at: string;
+}
+/** 工具层与 RPC 层**共用**的回溯结果形状(一个事实源,两处消费)。 */
+export interface ReceiptsView {
+    dimension: ReceiptDimension;
+    items: ReceiptView[];
+    /** 该维度命中的总条数(不受 `limit` 影响;`items` 才是分页窗口)。 */
+    total: number;
+    /** 非结果的状态提示(工具层拒答时用;端点层以报错代替)。 */
+    notice?: string;
+}
+export declare function toReceiptView(r: L1Receipt): ReceiptView;
+/** 回溯结果条数上限(与 `list-records` 同量级;超出窗口由 `total` 提示还有多少)。 */
+export declare const RECEIPTS_QUERY_LIMIT_MAX = 200;
+/**
+ * 一次蒸馏执行的 run 标识。
+ *
+ * **为什么不是"由输入切片推导出的确定性值"**——v1 曾这么设计，实测后被推翻：
+ * `pipeline/l1.ts` 对每条抽取结果执行 `record_id: newId('mem')`，
+ * **模型给的 record_id 被丢弃，记录 id 是运行时生成的**。因此"同一批消息重跑"
+ * 必然产生**不同的 record_id**，也就必然产生不同的凭证。把 run_id 做成切片的函数
+ * 换不来任何跨次幂等，只会让两次**互不相干的执行**挤在同一个 run_id 下，
+ * 反而破坏「一个 run = 一次执行」的归因。
+ *
+ * 于是幂等的真正边界是：**同一次 run 内，同一条记录只留一条凭证**
+ * （`receipt_id = f(run, record)` + `INSERT OR IGNORE`）。
+ * 这才是"同一决策不重复落盘"在本代码库里能成立的那个含义。
+ *
+ * 命名沿用仓库既有惯例（`newId('mem')` / `newJobId()` → `前缀_时间戳_随机`）。
+ */
+export declare function newRunId(): string;
+/** receipt_id = f(run, record) —— 幂等的落点(同 run 同记录只留一条)。 */
+export declare function receiptIdFor(runId: string, recordId: string): string;
+/** 动作归一:只认词表内的合法动作,其余一律记 `skip_missing`(不采信模型的非法输出)。 */
+export declare function normalizeKind(action: string | undefined): L1ReceiptKind;
+/** 纯映射:决策集 → 凭证行。无 I/O,便于单测与复算。 */
+export declare function buildReceipts(runId: string, decidedAt: string, items: readonly ReceiptInput[]): L1Receipt[];
+/** 凭证落盘的最小写入缝(与 `L1Store.recordReceipts` 同形)。 */
+export type ReceiptWriter = (rows: readonly L1Receipt[]) => number;
+/**
+ * **失败隔离**:凭证是旁路观测设施,绝不是主链路的单点。
+ *
+ * L1 蒸馏已经把新记忆写进事实源了;此时若凭证写失败还向上抛,等于让一个
+ * 「记录决策」的附属动作把「产生记忆」的主流程打死——代价与收益完全不成比例。
+ * 故此处只记 warn,永不抛出。
+ */
+export declare function persistReceiptsSafely(write: ReceiptWriter, rows: readonly L1Receipt[], logger?: {
+    warn: (msg: string) => void;
+}): void;

package/dist/store/receipts.js

@@ -0,0 +1,139 @@
+/**
+ * §B L1 决策凭证链(可追溯性基础设施)。
+ *
+ * 为什么需要:`memory.db` 里每条 L1 记录都是**去重决策的结果**(store / update /
+ * merge / skip),但决策本身不留痕——事后只能看到"结果长这样",看不到"当时基于什么
+ * 做的判断"。而判「这次 merge 是否正确」需要**当时的输入快照**,快照无法事后补录。
+ * 这就是 §B 必须**前置**存在、不能等症状触发的原因(findings.md §9)。
+ *
+ * 本文件承载契约中最纯的那一半:`input_digest`。
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/** 摘要格式版本。进入 canonical 串,使算法演进时**不会静默**让新旧凭证看起来可比。 */
+export const DIGEST_FORMAT = 'l1-receipts/v1';
+/**
+ * 候选池**有序序列** → 稳定摘要(sha256 hex)。
+ *
+ * 语义:`searchCandidates` 返回的是**已排序**的候选池,「当时看到哪些候选、按什么序」
+ * 就是去重决策的输入。故本函数**顺序敏感**——换个序即不同摘要,而不是把候选当集合。
+ *
+ * 三项刻意的设计:
+ * - **顺序敏感**:见上。集合语义会丢掉"哪条候选排在最前"这一信息。
+ * - **重复不折叠**:`['r1','r1']` 与 `['r1']` 摘要不同。候选池里的重复本身是事实
+ *   (例如同一记录被两条通路召回),折叠掉等于篡改输入。
+ * - **长度前缀编码**:逐项写 `${len}:${id}\n` 而非直接拼接。否则 `['a|b']` 与
+ *   `['a','b']`(以及 `['a\nb']` 与 `['a','b']`)会碰撞——分隔符出现在 id 里时,
+ *   序列化就不再是单射,摘要也就失去了作为输入指纹的意义。
+ *
+ * 纯函数:无 I/O、无时间、无随机。同输入**恒**同输出,这是凭证可复算的前提。
+ */
+export function inputDigest(candidateIds) {
+    const hash = createHash('sha256');
+    hash.update(DIGEST_FORMAT);
+    hash.update('\n');
+    for (const id of candidateIds) {
+        hash.update(`${id.length}:`);
+        hash.update(id);
+        hash.update('\n');
+    }
+    return hash.digest('hex');
+}
+/**
+ * 凭证保留上限:**最多保留多少个 run**。
+ *
+ * 为什么按 **run 数**而不是按天数(§B task_18):
+ * 本策略要防的是「`memory.db` 无限增长」。时间窗口**给不出这个保证**——
+ * 阈值(比如 90 天)与写入速率无关,一个高频用户 90 天能写进任意多行,
+ * 无界增长只是被推迟,不是被消除。run 数上限则**直接给出行的上界**
+ * (`maxRuns × 每 run 记录数`),这是"有界"与"看起来有界"的区别。
+ * 代价是:一个几乎不用的用户,历史可能只剩最近 1000 次蒸馏——
+ * 但凭证是**诊断设施**,诊断需要的是"最近发生了什么",不是考古。
+ *
+ * 1000 这个量级的依据:一轮 L1 蒸馏通常落 5~20 条凭证,故上限约 1~2 万行
+ * (数 MB 量级,在同为单文件的 `memory.db` 里不构成压力);而 L1 蒸馏本身要
+ * 调一次 LLM,现实中每小时至多几次——1000 轮 ≈ 活跃使用数月。
+ *
+ * **为什么是常量而不是配置项**:配置项要接 schema、契约与设置页,为一个
+ * 诊断表的容量引入用户可见面,收益与面积不成比例(YAGNI)。真需要调,
+ * 改这里即可,且 `recordReceipts(rows, { maxRuns })` 已留出显式注入口。
+ */
+export const RECEIPTS_MAX_RUNS = 1000;
+export function dimensionOf(q) {
+    const hasRecord = typeof q.recordId === 'string' && q.recordId.length > 0;
+    const hasRun = typeof q.runId === 'string' && q.runId.length > 0;
+    if (hasRecord && hasRun)
+        return 'both';
+    if (hasRecord)
+        return 'record';
+    if (hasRun)
+        return 'run';
+    return 'none';
+}
+export function toReceiptView(r) {
+    return {
+        receipt_id: r.receiptId,
+        run_id: r.runId,
+        record_id: r.recordId,
+        kind: r.kind,
+        input_digest: r.inputDigest,
+        decided_at: r.decidedAt,
+    };
+}
+/** 回溯结果条数上限(与 `list-records` 同量级;超出窗口由 `total` 提示还有多少)。 */
+export const RECEIPTS_QUERY_LIMIT_MAX = 200;
+const KNOWN_ACTIONS = ['store', 'update', 'merge', 'skip', 'conflict'];
+/**
+ * 一次蒸馏执行的 run 标识。
+ *
+ * **为什么不是"由输入切片推导出的确定性值"**——v1 曾这么设计，实测后被推翻：
+ * `pipeline/l1.ts` 对每条抽取结果执行 `record_id: newId('mem')`，
+ * **模型给的 record_id 被丢弃，记录 id 是运行时生成的**。因此"同一批消息重跑"
+ * 必然产生**不同的 record_id**，也就必然产生不同的凭证。把 run_id 做成切片的函数
+ * 换不来任何跨次幂等，只会让两次**互不相干的执行**挤在同一个 run_id 下，
+ * 反而破坏「一个 run = 一次执行」的归因。
+ *
+ * 于是幂等的真正边界是：**同一次 run 内，同一条记录只留一条凭证**
+ * （`receipt_id = f(run, record)` + `INSERT OR IGNORE`）。
+ * 这才是"同一决策不重复落盘"在本代码库里能成立的那个含义。
+ *
+ * 命名沿用仓库既有惯例（`newId('mem')` / `newJobId()` → `前缀_时间戳_随机`）。
+ */
+export function newRunId() {
+    return `run_${Date.now()}_${randomBytes(3).toString('hex')}`;
+}
+/** receipt_id = f(run, record) —— 幂等的落点(同 run 同记录只留一条)。 */
+export function receiptIdFor(runId, recordId) {
+    return inputDigest([runId, recordId]);
+}
+/** 动作归一:只认词表内的合法动作,其余一律记 `skip_missing`(不采信模型的非法输出)。 */
+export function normalizeKind(action) {
+    return KNOWN_ACTIONS.includes(action) ? action : 'skip_missing';
+}
+/** 纯映射:决策集 → 凭证行。无 I/O,便于单测与复算。 */
+export function buildReceipts(runId, decidedAt, items) {
+    return items.map((it) => ({
+        receiptId: receiptIdFor(runId, it.recordId),
+        runId,
+        recordId: it.recordId,
+        kind: normalizeKind(it.action),
+        inputDigest: inputDigest(it.candidateIds),
+        decidedAt,
+    }));
+}
+/**
+ * **失败隔离**:凭证是旁路观测设施,绝不是主链路的单点。
+ *
+ * L1 蒸馏已经把新记忆写进事实源了;此时若凭证写失败还向上抛,等于让一个
+ * 「记录决策」的附属动作把「产生记忆」的主流程打死——代价与收益完全不成比例。
+ * 故此处只记 warn,永不抛出。
+ */
+export function persistReceiptsSafely(write, rows, logger) {
+    if (rows.length === 0)
+        return;
+    try {
+        write(rows);
+    }
+    catch (err) {
+        logger?.warn(`[memory] L1 决策凭证落盘失败(${rows.length} 条),本次判定不留痕但**不影响蒸馏结果**: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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

@@ -23,6 +23,21 @@ export declare function applyDecayWeight<T extends {
 export declare function rrfMerge<T>(lists: T[][], getId: (item: T) => string, k?: number): Array<T & {
     rrfScore: number;
 }>;
+/**
+ * RRF 原始分归一化到 0~1(hybrid 检索的展示/比较分)。
+ *
+ * n 条列表融合时,单项最高原始分为 n/(k+1)(各列表 rank1 全中),故按**实际路数**
+ * lanes 归一:`rrfScore × (k+1) / lanes`,满分恰好 1.0,天然不越界。
+ * 旧实现把分母硬编码为 2,只对「FTS + 向量」双路成立;扩至 3/4 路后满分分别
+ * 达到 1.5 / 2.0,越出契约。2 路时本式与旧式逐字等价(无行为漂移)。
+ *
+ * 按「传入的路数」而非「非空路数」归一是有意的:向量源不可用时调用方仍传两条
+ * 列表(其一为空),旧实现给 FTS rank1 的分数是 0.5;按非空路数会变成 1.0,
+ * 反而破坏 2 路无漂移判据。
+ *
+ * 守卫:lanes 非正或非有限 → 0(退化输入不产生 NaN/Infinity)。
+ */
+export declare function normalizeRrf(rrfScore: number, lanes: number): number;
 /** FTS5 bm25 rank(负值=更相关)转 0~1 分数。 */
 export declare function bm25RankToScore(rank: number): number;
 /**

package/dist/store/search-utils.js

@@ -1,6 +1,7 @@
 /**
  * 检索工具:
  * - rrfMerge:RRF(Reciprocal Rank Fusion,k=60)多路结果融合,hybrid 检索用;
+ * - normalizeRrf:RRF 原始分按实际路数归一化到 0~1(hybrid 展示分);
  * - bm25RankToScore:FTS5 bm25 rank(负值=更相关)转 0~1 分数;
  * - applyDecayWeight:#29 时效衰减加权(读路径专用);
  * - buildFtsQuery / tokenizeForFts:FTS5 查询构造与写入侧分词。
@@ -62,6 +63,25 @@ export function rrfMerge(lists, getId, k = RRF_K) {
         .sort((a, b) => b.rrfScore - a.rrfScore)
         .map(({ item, rrfScore }) => ({ ...item, rrfScore }));
 }
+/**
+ * RRF 原始分归一化到 0~1(hybrid 检索的展示/比较分)。
+ *
+ * n 条列表融合时,单项最高原始分为 n/(k+1)(各列表 rank1 全中),故按**实际路数**
+ * lanes 归一:`rrfScore × (k+1) / lanes`,满分恰好 1.0,天然不越界。
+ * 旧实现把分母硬编码为 2,只对「FTS + 向量」双路成立;扩至 3/4 路后满分分别
+ * 达到 1.5 / 2.0,越出契约。2 路时本式与旧式逐字等价(无行为漂移)。
+ *
+ * 按「传入的路数」而非「非空路数」归一是有意的:向量源不可用时调用方仍传两条
+ * 列表(其一为空),旧实现给 FTS rank1 的分数是 0.5;按非空路数会变成 1.0,
+ * 反而破坏 2 路无漂移判据。
+ *
+ * 守卫:lanes 非正或非有限 → 0(退化输入不产生 NaN/Infinity)。
+ */
+export function normalizeRrf(rrfScore, lanes) {
+    if (!Number.isFinite(lanes) || lanes <= 0)
+        return 0;
+    return (rrfScore * (RRF_K + 1)) / lanes;
+}
 /** FTS5 bm25 rank(负值=更相关)转 0~1 分数。 */
 export function bm25RankToScore(rank) {
     if (!Number.isFinite(rank))

package/dist/store/session-modes.d.ts

@@ -17,6 +17,13 @@ export declare class SessionModeStore {
     get default(): MemoryMode;
     /** 同步读取:未设置过的会话返回默认档。 */
     get(sessionId: string): MemoryMode;
+    /**
+     * 该会话是否有**显式**档位条目(区别于 `get()` 的默认档回落)。
+     *
+     * 子代理档位继承(§A)靠它判断"这一层是否设过":未设过则继续沿父链上溯,
+     * 而不是立刻吃默认档——后者正是"用户显式 off 被绕过"的成因。
+     */
+    hasEntry(sessionId: string): boolean;
     /** 会话级注入覆盖原始值:undefined = 未覆盖,跟随全局。 */
     getRecall(sessionId: string): boolean | undefined;
     /** 解析后的注入开关:会话覆盖 ?? 全局运行时开关(部署级 cfg.recall.enabled

package/dist/store/session-modes.js

@@ -60,6 +60,15 @@ export class SessionModeStore {
     get(sessionId) {
         return this.entries.get(sessionId)?.mode ?? this.loaded;
     }
+    /**
+     * 该会话是否有**显式**档位条目(区别于 `get()` 的默认档回落)。
+     *
+     * 子代理档位继承(§A)靠它判断"这一层是否设过":未设过则继续沿父链上溯,
+     * 而不是立刻吃默认档——后者正是"用户显式 off 被绕过"的成因。
+     */
+    hasEntry(sessionId) {
+        return this.entries.has(sessionId);
+    }
     /** 会话级注入覆盖原始值:undefined = 未覆盖,跟随全局。 */
     getRecall(sessionId) {
         return this.entries.get(sessionId)?.recall;

package/dist/store/sqlite.d.ts

@@ -1,5 +1,6 @@
 import type { EmbeddingProviderInfo } from './embedding.js';
 import type { L0MessageRecord, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+import { isZeroVector, vecToBuffer } from './vec-utils.js';
 export interface StoreInitResult {
     /** embedding 配置(provider/model/维度)变化,需要后台全量重嵌入。 */
     needsReindex: boolean;
@@ -14,6 +15,8 @@ import type { BucketRow, CostAggregate, CostByLayer } from './cost-ledger.js';
 export type { BucketRow, CostAggregate, CostByLayer } from './cost-ledger.js';
 import type { CostByModel } from '../contract.js';
 import { GraphStore } from './graph-store.js';
+import type { L1Receipt, ReceiptQuery, ReceiptRetentionOptions } from './receipts.js';
+import type { ConflictPair, ConflictResolution } from './conflicts.js';
 /** L1 检索命中(含 BM25/余弦归一分数)。 */
 export interface L1SearchHit {
     id: string;
@@ -106,7 +109,14 @@ export declare class MemoryDb {
      * 图谱时间锚仍读 metadata,列由新写入路径填充。
      */
     private ensureTemporalColumns;
-    /** 重建后的 l1_fts 从 l1_records 全量回灌(仅在 drop 重建时调用;iterate 流式防大库内存峰值)。 */
+    /**
+     * 重建后的 l1_fts 从 l1_records 全量回灌(仅在 drop 重建时调用;iterate 流式防大库内存峰值)。
+     *
+     * ⚠️ 本函数的参数列表**必须与 `stmtL1FtsInsert` 逐位对齐**。不对齐时 node:sqlite 会在这里抛错,
+     * 而下面的 `catch` 是**逐行吞掉**的——症状是 `count` 停在 0、索引静默变空,
+     * 全库记录从此全文检索不可见却没有任何错误日志。§E 加列时正是这个位置最容易漏
+     * (三处列清单:DDL / insert 语句 / 本函数),故在此留下警示。
+     */
     private backfillL1Fts;
     /** 重建后的 l0_fts 从 l0_conversations 全量回灌(仅 drop 重建时调用;iterate 流式)。 */
     private backfillL0Fts;
@@ -148,12 +158,107 @@ export declare class MemoryDb {
     /** 全量读取(调试/迁移/重嵌入用;检索请走 FTS/向量)。 */
     getAllL1(): MemoryRecord[];
     getL1ByIds(ids: string[]): MemoryRecord[];
-    /** 浏览列表(UI 用):按更新时间倒序,支持类型/场景/族/Hall 过滤与分页。失败返回空。 */
+    /**
+     * §B 决策凭证批量落盘。`INSERT OR IGNORE` + 确定性 `receipt_id`
+     * (见 `receipts.ts` 的 `receiptIdFor`)→ 同一次 run 重放不产生重复行。
+     * 返回实际新增条数(被忽略的重复不计)。
+     *
+     * 刻意**不开事务**:凭证是旁路观测数据,单条独立、重放幂等,部分写入无害;
+     * 为它引入事务只会把失败面扩大。调用方另有 `persistReceiptsSafely` 兜底不抛。
+     *
+     * 写入后**顺带执行保留策略**(task_18)。把裁剪挂在这里而不是交给调用方,
+     * 是为了让"有界"成为**结构性保证**:任何写路径都不可能忘记裁剪,
+     * 因而表容量不可能随使用时间无界增长。裁剪自身失败只 warn——
+     * 它是省空间的动作,失败了最坏是这次没省下来,绝不能因此弄丢刚落盘的凭证
+     * (故裁剪在写入**之后**,且包在 try 里)。
+     */
+    recordReceipts(rows: readonly L1Receipt[], opts?: ReceiptRetentionOptions): number;
+    /**
+     * §C 矛盾冻结(task_22):落盘待裁决冲突对。
+     *
+     * `INSERT OR IGNORE`——幂等来自 **pair_id 主键**而非调用方自觉:
+     * `conflictPairId(runId, winner, loser)` 对同一三元组恒等,故一轮蒸馏重复落盘
+     * 只会得到一行。与 §B 凭证同一手法(那边是 `receipt_id` 主键)。
+     *
+     * 与凭证不同,这里**不做保留裁剪**:待裁决对是**欠人的债**,不是观测数据。
+     * 裁剪它等于把用户还没看的裁决请求悄悄删掉,那是丢工作而不是省空间。
+     * 有界性交给 task_24 的队列上限(超限不再停放、回落自动裁决),语义是
+     * 「**不收新的**」而非「**偷偷删旧的**」。
+     *
+     * @returns 实际新插入的行数。
+     */
+    recordConflictPending(rows: readonly ConflictPair[]): number;
+    /** §C 冻结:把图谱 `disputed` 状态同步到给定冲突集(薄缝,便于单测替换)。 */
+    syncGraphDisputed(disputedRecordIds: readonly string[]): {
+        marked: number;
+        cleared: number;
+    };
+    /**
+     * §C 冻结队列的**未裁决**条数(task_24 队列上限判据)。
+     * 走 `idx_conflict_pending_unresolved` 偏索引,不是全表扫描。
+     */
+    countConflictPendingUnresolved(): number;
+    /**
+     * §C 取未裁决冲突对(task_24 超时扫描 / task_25 裁决工具)。
+     *
+     * `createdBefore` 为**排他上界**(ISO 串):只取该时刻之前创建的,用于超时判定。
+     * 定序 `created_at ASC, pair_id ASC`——先来先服务,且同一毫秒内仍**确定可复现**。
+     */
+    listConflictPending(opts?: {
+        createdBefore?: string;
+        limit?: number;
+    }): ConflictPair[];
+    /**
+     * §C 打上裁决结论。
+     *
+     * `WHERE resolved_at = ''` 使**已裁决的不会被覆盖**:裁决是一次性的判定行为,
+     * 重复调用不该把第一次的结论改写掉(人工裁决与自动了结的次序因此不可逆)。
+     *
+     * @returns 受影响行数(0 = 该对被裁决过或不存在)。
+     */
+    resolveConflictPending(pairId: string, resolution: ConflictResolution, resolvedAt: string): number;
+    /**
+     * §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: number): number;
+    /**
+     * §B 双维回溯(task_19):按 `record_id` / `run_id` 查判定史,两维同给为 **AND**。
+     *
+     * 两条刻意的行为:
+     * - **两维都不给返回空,而不是全表**。「查全部凭证」不是本能力的目标;把缺参
+     *   兜成全表,会让一次误调用变成全库判定史导出。调用方本就该先拒绝这种用法
+     *   (工具层给提示、端点层直接报错),这里是第二道,方向一致。
+     * - **定序确定**:`decided_at DESC, run_id DESC`。回溯的价值在于可复现——
+     *   同一问题两次问出不同顺序,核对时就会怀疑是不是数据变了。`run_id` 兜底
+     *   同一毫秒内的多批(L1 蒸馏是 LLM 调用,同刻两批罕见但非不可能)。
+     *   新的在前,与 `listL1` 的倒序口径一致。
+     */
+    listReceipts(opts: ReceiptQuery & {
+        limit: number;
+    }): L1Receipt[];
+    /** 同维度命中的**总条数**(不受 limit 影响,供"还有多少条没显示"提示)。 */
+    countReceipts(opts: ReceiptQuery): number;
+    /** 浏览列表(UI 用):按更新时间倒序,支持类型/场景/族/Hall/可见范围过滤与分页。失败返回空。 */
     listL1(opts: {
         type?: string;
         scene?: string;
         family?: string;
         hall?: string;
+        workspaceId?: string;
         limit: number;
         offset: number;
     }): {
@@ -162,10 +267,14 @@ export declare class MemoryDb {
     };
     /** 场景名去重列表(UI 筛选器数据源)。失败返回空。 */
     distinctL1Scenes(): string[];
-    /** FTS5 BM25 检索(family 缺省不过滤)。失败返回空数组(调用方降级)。 */
-    searchL1Fts(query: string, limit: number, family?: string): L1SearchHit[];
-    /** vec0 余弦 KNN 检索(score = 1 - cosine distance;family 过滤走过度召回 + 回查过滤,vec0 无法 WHERE)。失败返回空数组。 */
-    searchL1Vector(embedding: Float32Array, topK: number, family?: string): L1SearchHit[];
+    /** FTS5 BM25 检索(family / workspaceId 缺省不过滤)。失败返回空数组(调用方降级)。 */
+    searchL1Fts(query: string, limit: number, family?: string, workspaceId?: string): L1SearchHit[];
+    /**
+     * vec0 余弦 KNN 检索(score = 1 - cosine distance)。失败返回空数组。
+     * family / workspaceId 过滤走**过度召回 + 回查过滤**(vec0 无法 WHERE)。
+     * 放大倍数对两条轴**相乘**:两轴各自丢弃行,单独放大任一条都不够。
+     */
+    searchL1Vector(embedding: Float32Array, topK: number, family?: string, workspaceId?: string): L1SearchHit[];
     /** 批量 upsert L0 消息(元数据 + FTS;embeddings 与 records 等长,可省略)。 */
     upsertL0Batch(records: L0MessageRecord[], embeddings?: Array<Float32Array | undefined>): boolean;
     /** 记录一次蒸馏调用成本(委托 cost-ledger;语义见 CostLedger.insertCostCall)。 */
@@ -242,5 +351,4 @@ export declare class MemoryDb {
     }>, recordedAt: string): number;
     close(): void;
 }
-/** 全零向量(cosine 未定义,不可入向量表)。reindex 侧用它区分"不可嵌入"与"写入失败"。 */
-export declare function isZeroVector(vec: Float32Array): boolean;
+export { isZeroVector, vecToBuffer };