dsh-prime-memory 0.22.2 → 0.24.1

package/dist/store/memory-md.js

@@ -0,0 +1,230 @@
+/**
+ * L1 记录 → markdown 投射（P1 / N1）。
+ *
+ * 三条设计约束，都是被"文件要能双向"逼出来的：
+ *
+ * 1. **渲染必须是纯函数**：同一个记录永远渲染出同一份字节。否则每次导出都会重写
+ *    每个文件，账本里的 `fileDigest` 每轮都变，"文件被人改过"就永远判不出来。
+ *    所以文件里**不写导出时刻**、不写任何非记录字段。
+ * 2. **只写内容层，不写检索轴**（N6 口径）：`hall`/`tags`/`room*`/`cogHall` 留在库里
+ *    ——写进文件就是一份会过期的副本，还会诱导人改它（而改了又不生效）。派生评价
+ *    （`maturity`/`usage`/`rating`）同理：它们是算出来的，不是事实。
+ * 3. **文件名走 `sanitizeFilename` 那一套**（与 `util/md-name.ts` 同源），type 目录名
+ *    走**枚举白名单**（不 sanitize——不在白名单的 type 直接归 `unsorted`，而不是
+ *    洗出一个没人认识的新目录）。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { isAbsolute, normalize, resolve, sep } from 'node:path';
+import { normText } from '../memport/format.js';
+import { memoryTypeDirs, UNCLASSIFIED_DIR } from '../memory-types.js';
+import { deriveName } from '../util/md-name.js';
+import { normalizeContentMd } from '../util/md-normalize.js';
+import { sanitizeFilename } from './scenes.js';
+/**
+ * 允许当目录名的 type 值（pm-name-distill task_1.3：由词表单一真源派生，不再手抄）。
+ *
+ * 手抄的危害很具体：换词表不改这一处，新词表里的十余类会**静默落进兜底桶**——
+ * 不报错、不同步失败，只少目录树。
+ */
+export const MEMORY_TYPE_DIRS = memoryTypeDirs();
+/**
+ * 不在词表的 type 落到这个目录（P4.1 的**默认类**）。
+ *
+ * 它是**目录层的投影**，不是库内事实：记录自己的 `type` 原值照旧写进 frontmatter，
+ * 也绝不回填到 `rowToRecord`/upsert/metadata（F5 红线）。之所以不直接归进某个 `work_*`：
+ * 那会把这批无类记录的 `family` 挑到 work 侧，而 family 决定共享面——等于静默改了可见性。
+ */
+export const UNSORTED_DIR = UNCLASSIFIED_DIR;
+/** frontmatter 允许出现的键（用例断言键集**恰等于**它，防检索轴泄漏进文件）。 */
+export const FRONTMATTER_KEYS = [
+    'name', 'type', 'priority', 'createdAt', 'updatedAt', 'usageScenario', 'extKey', 'id', 'hash', 'retired',
+];
+/** 内容指纹长度（12 hex ≈ 48 bit；账本只用来判"变没变"，不当身份用）。 */
+export const DIGEST_HEX = 12;
+/** 失效后缀（N11）：`x.memory.md` → `x.memory.md.disable`。用户定名，取代原设计的 `.outdated`。 */
+export const DISABLE_SUFFIX = '.disable';
+/** workspace 优先时的子目录（N10）：`<workspace>/.agents/memory/…`。 */
+export const WORKSPACE_SUBDIR = ['.agents', 'memory'];
+/**
+ * 解析单根（无 workspace 归属的记录落这里）。
+ *
+ * 给了 `cfgRoot` 就用它（必须绝对路径且不含 `..`），否则默认 `<dataDir>/memories`。
+ * **不合法只回退默认并 warn，绝不抛错**：投射是旁路，旁路配置写错不能弄挂记忆本体。
+ */
+export function resolveMemoriesRoot(cfgRoot, dataDir, logger) {
+    const raw = (cfgRoot ?? '').trim();
+    if (raw.length === 0)
+        return resolve(dataDir, 'memories');
+    if (!isAbsolute(raw) || raw.includes('..')) {
+        logger?.warn(`[memory] memExport.root 不是无 .. 的绝对路径，回退默认根: ${raw}`);
+        return resolve(dataDir, 'memories');
+    }
+    return resolve(raw);
+}
+/**
+ * 把渲染出的相对路径安全地拼到根下。
+ *
+ * 越界（绝对路径、`..` 跳出、盘符切换）一律返回 `undefined` 由调用方跳过并 warn——
+ * 记录内容是人/模型写的，它可能包含 `../../`，这里必须是结构性挡死而不是"应该不会有"。
+ */
+export function safeJoin(root, relPath) {
+    if (relPath.length === 0 || isAbsolute(relPath))
+        return undefined;
+    const parent = resolve(root);
+    const target = resolve(parent, relPath);
+    if (target === parent)
+        return undefined;
+    // 前缀判定必须带分隔符结尾，否则 `/a/memoriesX` 会被 `/a/memories` 误认包含。
+    const withSep = parent.endsWith('/') || parent.endsWith('\\') ? parent : `${parent}${sep}`;
+    return target.startsWith(withSep) ? target : undefined;
+}
+/**
+ * 投射落点（N10）：**workspace 优先**。
+ *
+ * 有 `workspaceId` ⇒ `<workspace>/.agents/memory/<type>/<stem>.memory.md`；
+ * 没有 ⇒ 单根（`cfg.memExport.root` 或 `<dataDir>/memories`）。
+ *
+ * ⚠️ **导出/对账/失效改名/归档四处必须共用本函数**。库里的 `workspace_id` 在 Windows 上是
+ * 小写形态（`normalizeWorkspacePath` 会 `.toLowerCase()`），任何一处自己拼路径、或者自己
+ * 转一下大小写，就会把“刚写进去的文件”算成另一个账本键 → 对账永远报“文件缺失”。
+ * 同理：**不**在这里做 `fs.realpath` 归一——那会让目录创建前后的键漂移，反而造出假缺失；
+ * Windows 路径大小写不敏感，同一逻辑路径的两种写法解析到同一个文件，键自洽即可。
+ */
+export function targetFor(r, cfgRoot, dataDir, logger) {
+    const { relPath } = renderRecord(r);
+    const ws = (r.workspaceId ?? '').trim();
+    if (ws.length > 0 && isAbsolute(ws) && !ws.includes('..')) {
+        // 护栏（默认开，不给开关）：workspace 目录不存在时不往它下面写。worktree 被删、
+        // 盘符变了、或 `workspace_id` 是脏值时，写盘会凭空造出一棵
+        // `<已消失的项目>/.agents/memory/` 孤儿树——那比落回单根难查得多（单根里的文件
+        // 仍然可见、可导出、可同步；孤儿树没人知道它属于哪个项目）。
+        // 判据用 **workspace 根本身**而不是投射根：后者不存在是常态（首次导出会 mkdir）。
+        if (existsSync(ws)) {
+            const root = resolve(ws, ...WORKSPACE_SUBDIR);
+            return { root, relPath, absPath: safeJoin(root, relPath), inWorkspace: true };
+        }
+        warnMissingWorkspace(logger, ws);
+    }
+    const root = resolveMemoriesRoot(cfgRoot, dataDir, logger);
+    return { root, relPath, absPath: safeJoin(root, relPath), inWorkspace: false };
+}
+/**
+ * 已提醒过的缺失 workspace（同一个根只 warn 一次）。
+ *
+ * 不设上限就会在 1280 条记录上刷屏；集子封到 64 个就不再记录新条目（宁可漏提醒，
+ * 也不让一个诊断集无限吃内存）。放在 `targetFor` 之后：函数声明提升，`const` 集子在
+ * 模块求值后才被调用，所以顺序不影响可用性——影响的是文档块跟谁。
+ */
+const warnedMissingWs = new Set();
+function warnMissingWorkspace(logger, ws) {
+    if (logger === undefined)
+        return;
+    if (warnedMissingWs.has(ws))
+        return;
+    if (warnedMissingWs.size < 64)
+        warnedMissingWs.add(ws);
+    logger.warn(`[memory] workspace 目录不存在，该条投射落点退回单根: ${ws}`);
+}
+/**
+ * 退场判据：与库侧同口径（`sqlite.ts` 的“`valid_to` 非空即退场”，与
+ * `retiredL1Count`/`listRetiredL1` 一致）。
+ *
+ * 为什么住在本文件：导出（要不要把文件放回非退场路径）与失效联动（后缀该不该带）
+ * 两侧都得用同一个判据，否则“列表说它退了、文件却没后缀”会回来。放 `memory-md-disable.ts`
+ * 会让 `memory-md-export.ts` 反向 import 它形成循环（那边已经 import 这边）。
+ */
+export function isRetiredRecord(r) {
+    return typeof r.validTo === 'number' && r.validTo > 0;
+}
+/**
+ * 投射文件的失效路径：`x.memory.md` → `x.memory.md.disable`。
+ * 已带后缀的原样返回（幂等靠这个性质，而不是靠调用方记住判重）。
+ */
+export function disablePathOf(absPath) {
+    return absPath.endsWith(DISABLE_SUFFIX) ? absPath : `${absPath}${DISABLE_SUFFIX}`;
+}
+/**
+ * 内容指纹。
+ *
+ * 刻意**不复用** `memport/format.ts` 的 `contentHash`：那个口径被 TS↔Python 跨实现
+ * 金标准锁死（`tests/memport-ts-consistency`），改了就是让两边算出不同的包。这里只
+ * 借它的 `normText`（NFKC + 换行归一），口径独立、且明确标注为"投射账本专用"。
+ */
+export function digest(text) {
+    return createHash('sha1').update(normText(text), 'utf8').digest('hex').slice(0, DIGEST_HEX);
+}
+/**
+ * 投射文件自带 `hash` 键的**规范口径**（导出写、读入核，两侧都必须走它）。
+ *
+ * 定义 = `digest(归一后的正文)`：与 `renderRecord` 写进 `hash` 的值、以及读侧拿解析出的
+ * `content` 实算的值三处同源。只覆盖正文、不含任何 frontmatter 字段——所以换 id、换文件名、
+ * 退场标记都不改变它，它只回答「正文有没有被改过」这一件事。
+ *
+ * 走 `digest`（内含 NFKC + 空白折叠）而非裸 sha1：CRLF/BOM/尾随空白这类搬运噪声不该触发
+ * 假不符（搬文件、换编辑器、git autocrlf 都会引入它们）。
+ */
+export function contentHash(content) {
+    return digest(normalizeContentMd(content));
+}
+/** 记录内容指纹：正文字段（不含 metadata——轴变了不算内容变）。 */
+export function recordDigest(r) {
+    return digest(r.content);
+}
+/**
+ * 文件名干：有 `name` 用 `name`；没有则回落 `mem-<id 后 8 位>`。
+ *
+ * 回落是**必需**的：存量记录 name 恒空（零回填红线），不回落就没法投射第一批。
+ * id 每轮新铸，所以回落名不稳定——这正是 P0 要先做 `name` 的原因，注释留在这里
+ * 免得后来人以为"回落名也能双向"。
+ */
+export function fileStemFor(r) {
+    const named = (r.name ?? '').length > 0 ? r.name : deriveName(r.content);
+    const base = named.length > 0 ? named : `mem-${r.id.slice(-8)}`;
+    // 借 sanitizeFilename 的字符/保留名纪律，再剥掉它补的 .md（我们后面统一补）。
+    return sanitizeFilename(base).replace(/\.md$/i, '') || `mem-${r.id.slice(-8)}`;
+}
+/** 把值写成可解析回读的 frontmatter 标量/数组（JSON 编码，转义由它负责）。 */
+function fmLine(key, value) {
+    return `${key}: ${JSON.stringify(value)}`;
+}
+/**
+ * 渲染一条记录。
+ *
+ * @param r - L1 记录（含已退场的——退场也要有投影，否则人在文件树里看不到它）。
+ * @returns `relPath`（相对投射根，已归一分隔符）与 `text`（全文）。
+ */
+export function renderRecord(r) {
+    const dir = MEMORY_TYPE_DIRS.has(r.type) ? r.type : UNSORTED_DIR;
+    const stem = fileStemFor(r);
+    const relPath = normalize(`${dir}/${stem}.memory.md`).replace(/\\/g, '/');
+    const scenario = Array.isArray(r.metadata?.dsh_usage_scenario)
+        ? (r.metadata?.dsh_usage_scenario).filter((s) => typeof s === 'string')
+        : [];
+    // 正文只归一一次：`hash` 键与正文行必须落在**同一份正文**上，否则读入侧的
+    // 「声明 vs 实算」核对会因两次归一是否完全一致而变得可疑（归一虽幂等，复用同一变量最稳）。
+    const body = normalizeContentMd(r.content);
+    const lines = ['---'];
+    lines.push(fmLine('name', stem));
+    lines.push(fmLine('type', r.type));
+    lines.push(fmLine('priority', r.priority));
+    lines.push(fmLine('createdAt', r.createdAt ? new Date(r.createdAt).toISOString() : ''));
+    lines.push(fmLine('updatedAt', r.updatedAt ? new Date(r.updatedAt).toISOString() : ''));
+    lines.push(fmLine('usageScenario', scenario));
+    lines.push(fmLine('extKey', r.extKey ?? ''));
+    lines.push(fmLine('id', r.id));
+    // 正文自校验指纹（N13）：写在 frontmatter 里的 `hash`，只覆盖**渲染后的正文**（与下面那行
+    // 正文同源）。读入侧据此确认文件未被外部改动/损坏，且**不依赖账本**——文件搬到别的机器、
+    // 账本丢失时仍可自证。刻意不含 frontmatter：`id` 会随 merge 重铸（F1），把 id 算进去会让
+    // 「换了 id、正文没动」也误报被改。
+    lines.push(fmLine('hash', contentHash(r.content)));
+    // 退场标记只在真退场时写：不留 `retired: false` 这种噪声键（键集越稳，人越不容易改错）。
+    if (r.validTo !== undefined)
+        lines.push(fmLine('retired', true));
+    lines.push('---', '');
+    // 正文过一道版式归一（P4.2）：无结构存量文本出口就是标准形状。归一是**幂等**的，
+    // 所以不会把账本 `fileDigest` 每轮推得变一下（不幂等 = 反向同步永远判“文件被改过”）。
+    lines.push(body);
+    lines.push('');
+    return { relPath, text: lines.join('\n') };
+}

package/dist/store/obsolete-notices.d.ts

@@ -0,0 +1,39 @@
+import type { MemoryLogger } from '../types.js';
+export declare const OBSOLETE_NOTICES_FILE_VERSION: 1;
+/** 一条待播报的过时声明。 */
+export interface ObsoleteNotice {
+    /** 被退场的 L1 记录 id。 */
+    id: string;
+    /** 正文首行（注入时供模型定位是哪条；截断至 TITLE_MAX）。 */
+    title: string;
+    /** 用户声明时刻(epoch ms)。 */
+    at: number;
+}
+export declare class ObsoleteNoticeStore {
+    private readonly logger?;
+    private readonly file;
+    private buckets;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    private normalize;
+    private ensureLoaded;
+    /** 判脏序号(测试/观测用;注入侧靠 drain 的返回值判断有无)。 */
+    revision(): number;
+    /** 入队一条(幂等由调用方保证:同 id 重复入队只会多播一行，故这里去重)。 */
+    push(sessionKey: string, notice: ObsoleteNotice): void;
+    /** 出队并清空该会话的待播报(一次性语义:取走即离开 outbox)。 */
+    drain(sessionKey: string): ObsoleteNotice[];
+    /** 只看不取(测试/诊断)。 */
+    peek(sessionKey: string): ObsoleteNotice[];
+    size(): number;
+    private prune;
+    private schedulePersist;
+    private persist;
+    /** 等待在途写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+}

package/dist/store/obsolete-notices.js

@@ -0,0 +1,153 @@
+/**
+ * 「记忆已声明过时」待播报队列（outbox，`obsolete-notices.json`）。
+ *
+ * 为什么需要它：用户在召回卡上打 `-1` 之后，**记忆库那一侧当场就改了**（退场），
+ * 但模型此刻的上下文里那条记忆还在——它得被告知"这条已由用户判定过时、别再依据它
+ * 作答"。这个告知是一次性的：下一轮注入即出队，不常驻（常驻是槽位的语义，见
+ * `hooks/slot-recall.ts`）。
+ *
+ * 落盘而非纯内存：打 `-1` 到下一轮之间若进程重启，纯内存会**静默丢掉这一票**——
+ * 记忆已经退场了，而模型从没被告知。所以 outbox 必须持久化（与 session-recalled
+ * 同款纪律：写穿 + 版本 + 损坏只读降级，绝不抛进注入热路径）。
+ *
+ * 键 = sessionKey（`agent.session?.id ?? agent.id`），与活召回集、pill 的 sessionId
+ * 同源；三处不同键会直接导致"播报错会话"，见 store/session-recalled.ts 头注。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const OBSOLETE_NOTICES_FILE_VERSION = 1;
+/** 单会话待播报上限（超出丢最旧：模型只需知道"这些别再信"，不需历史）。 */
+const PER_SESSION_CAP = 8;
+/** 会话数上限，按最近写入时间淘汰。 */
+const SESSION_CAP = 200;
+const TITLE_MAX = 120;
+export class ObsoleteNoticeStore {
+    logger;
+    file;
+    buckets = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    rev = 0;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'obsolete-notices.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 过时播报队列只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        const raw = read.value.sessions ?? {};
+        for (const [sid, list] of Object.entries(raw)) {
+            const kept = this.normalize(list);
+            if (kept.length > 0)
+                this.buckets.set(sid, kept);
+        }
+        this.loaded = true;
+    }
+    normalize(list) {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const raw of list) {
+            if (!raw || typeof raw !== 'object')
+                continue;
+            const e = raw;
+            if (typeof e.id !== 'string' || !e.id || typeof e.title !== 'string' || typeof e.at !== 'number')
+                continue;
+            out.push({ id: e.id, title: e.title, at: e.at });
+            if (out.length >= PER_SESSION_CAP)
+                break;
+        }
+        return out;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('过时播报队列未初始化(先 await init())');
+    }
+    /** 判脏序号(测试/观测用;注入侧靠 drain 的返回值判断有无)。 */
+    revision() {
+        return this.rev;
+    }
+    /** 入队一条(幂等由调用方保证:同 id 重复入队只会多播一行，故这里去重)。 */
+    push(sessionKey, notice) {
+        this.ensureLoaded();
+        if (!sessionKey)
+            return;
+        const list = this.buckets.get(sessionKey) ?? [];
+        if (list.some((n) => n.id === notice.id))
+            return;
+        const title = notice.title.length > TITLE_MAX ? `${notice.title.slice(0, TITLE_MAX)}…` : notice.title;
+        const next = [...list, { ...notice, title }];
+        this.buckets.set(sessionKey, next.slice(-PER_SESSION_CAP));
+        this.rev += 1;
+        this.prune();
+        this.schedulePersist();
+    }
+    /** 出队并清空该会话的待播报(一次性语义:取走即离开 outbox)。 */
+    drain(sessionKey) {
+        this.ensureLoaded();
+        const list = this.buckets.get(sessionKey);
+        if (list === undefined || list.length === 0)
+            return [];
+        this.buckets.delete(sessionKey);
+        this.rev += 1;
+        this.schedulePersist();
+        return list;
+    }
+    /** 只看不取(测试/诊断)。 */
+    peek(sessionKey) {
+        this.ensureLoaded();
+        return [...(this.buckets.get(sessionKey) ?? [])];
+    }
+    size() {
+        this.ensureLoaded();
+        let n = 0;
+        for (const list of this.buckets.values())
+            n += list.length;
+        return n;
+    }
+    prune() {
+        if (this.buckets.size <= SESSION_CAP)
+            return;
+        const newestAt = (list) => list.reduce((m, n) => Math.max(m, n.at), 0);
+        const byOldest = [...this.buckets.entries()].sort((a, b) => newestAt(a[1]) - newestAt(b[1]));
+        for (const [sid] of byOldest.slice(0, this.buckets.size - SESSION_CAP))
+            this.buckets.delete(sid);
+    }
+    schedulePersist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(() => this.persist(), () => this.persist());
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        const body = {
+            version: OBSOLETE_NOTICES_FILE_VERSION,
+            sessions: Object.fromEntries(this.buckets),
+        };
+        try {
+            await atomicWriteText(this.file, JSON.stringify(body, null, 2));
+        }
+        catch (err) {
+            this.degraded = err instanceof Error ? err.message : String(err);
+            if (!this.degradedLogged) {
+                this.degradedLogged = true;
+                this.logger?.warn(`[memory] 过时播报队列落盘失败,转只读降级: ${this.degraded}`);
+            }
+        }
+    }
+    /** 等待在途写完成(测试/停机用)。 */
+    flush() {
+        return this.writeChain;
+    }
+}

package/dist/store/recall-feedback.d.ts

@@ -0,0 +1,75 @@
+import type { MemoryLogger } from '../types.js';
+export declare const RECALL_FEEDBACK_FILE_VERSION: 1;
+/** 合法打分：-1（声明过时）与 0..5（相关度）。 */
+export declare const FEEDBACK_SCORES: readonly [-1, 0, 1, 2, 3, 4, 5];
+export type FeedbackScore = (typeof FEEDBACK_SCORES)[number];
+/** 单条记忆的反馈聚合。 */
+export interface RecallFeedbackEntry {
+    /** 最近一次打分(-1..5)。 */
+    last: FeedbackScore;
+    /** 有效相关度评分次数(不含 -1)。 */
+    rated: number;
+    /** 0..5 评分均值(rated=0 时为 0)。 */
+    mean: number;
+    /** 被声明过时的次数(-1 计数)。 */
+    obsolete: number;
+    /** 最近一次打分时刻(epoch ms)。 */
+    updatedAt: number;
+    /** 最近若干条打分轨迹(旧→新，截断至 HISTORY_CAP)。 */
+    history: Array<{
+        s: FeedbackScore;
+        at: number;
+    }>;
+}
+/** 是否合法打分(供端点入参校验复用)。 */
+export declare function isFeedbackScore(v: unknown): v is FeedbackScore;
+export declare class RecallFeedbackStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    /** 判脏序号:每次有效写入 +1(投影 view 带 rating，靠它决定要不要重建)。 */
+    private rev;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    /** 读侧逐条收窄:形状不符的条目丢弃，不让一条坏数据拖垮整表。 */
+    private normalize;
+    private ensureLoaded;
+    /** 判脏序号(供投影 O(1) 决定要不要重建 view)。 */
+    revision(): number;
+    /**
+     * 记一次打分。返回聚合后的条目(供端点回执)。
+     * 只聚合不裁决:`-1` 进 obsolete 计数、不进均值(过时不是"不相关",两回事)。
+     */
+    rate(id: string, score: FeedbackScore, at?: number): RecallFeedbackEntry;
+    get(id: string): RecallFeedbackEntry | undefined;
+    /** 均值(0..5);无有效评分 → undefined(缺席 ≠ 0 分)。 */
+    meanOf(id: string): number | undefined;
+    /** 最近一次打分(-1..5);未标注 → undefined。 */
+    lastOf(id: string): FeedbackScore | undefined;
+    /**
+     * 把一条记录的人工标注搬到新 id（merge 之后由管线调用，P0-d）。
+     *
+     * 不搬的后果比使用史更直接：成熟度只吃“人工最近一笔”，而 `last` 留在旧 id 上
+     * 就等于新记录**看起来从没被人打过**；更坏的是旧 id 上那一笔 `-1`（已判过时）
+     * 会跟着旧行一起沉进垃圾堆，新行反而以“未标注”的活状态回到召回里。
+     *
+     * 计数按相加、不按轨迹重算：`history` 截断到 12 条，拿它反推 `obsolete` 必然少算。
+     * 两侧都有条目时取较新一侧的 `last`，轨迹按时间归并。
+     */
+    rekey(oldId: string, newId: string): boolean;
+    summary(): {
+        tracked: number;
+        rated: number;
+        obsolete: number;
+    };
+    private prune;
+    /** 立即落盘(串行链上排队,不与在途写交错)。 */
+    private schedulePersist;
+    private persist;
+    /** 等待在途写完成(测试/停机用)。 */
+    flush(): Promise<void>;
+}