dsh-prime-memory 0.24.0 → 0.24.1

package/dist/store/memory-md-run.js

@@ -0,0 +1,151 @@
+/**
+ * md 投影长任务的**滚动执行**与进度面。
+ *
+ * 为什么要这一层：`exportRecords` / `convergeDisabledSuffix` 各自是"一次有界的一轮"
+ * （护栏 `maxRecords` + 墙钟 `timeBudgetMs`），设计上就假定调用方会再点一次。真机反馈
+ * 是"点三下才清干净，每次一秒多"——把"要不要继续"这个判断丢给人点是错的：任务自己知道
+ * 有没有做完（`capped`），就该自己滚到完。形状照本包既有的两个长任务（`ruminate` /
+ * `rebuild`）：一个后台任务 + 一个只读状态端点，面板拿状态画进度条。
+ *
+ * 三条纪律：
+ * 1. **同一时刻只跑一个投影任务**：两个任务同时改同一批文件与同一本账，产生的差异
+ *    连对账都解释不清。第二个进来直接抛，不排队（排队会让人以为"点了没反应"）。
+ * 2. **总预算兜底**：单轮的墙钟护栏防的是"一条超大记录挂死一次点击"，跨轮还得有一道
+ *    总闸（`totalBudgetMs`）+ 轮数上限（`maxPasses`），否则一个病态目录能让任务永远
+ *    在滚。用尽时如实写进 `error`，人再点一次接着滚（游标语义幂等，不重复也不漏）。
+ * 3. **进度只读不阻塞**：状态是模块级一份快照，端点读它就返回；执行侧只在轮与轮的
+ *    边界更新它（不在内层循环里写，省掉上千次无意义赋值）。
+ */
+import { exportRecords } from './memory-md-export.js';
+import { convergeDisabledSuffix } from './memory-md-disable.js';
+/** 模块级唯一快照：投影是"同一时刻一个"的任务，不需要多路会话态。 */
+const status = {
+    running: false, phase: 'idle', pass: 0, done: 0, total: 0,
+    written: 0, renamed: 0, detail: '', startedAt: '', endedAt: '',
+};
+/** 只读快照副本（防调用方改到执行中的那份）。 */
+export function mdRunStatus() {
+    return { ...status };
+}
+function blankSuffix() {
+    return {
+        scanned: 0, renamed: 0, revived: 0, edited: 0, already: 0, both: 0, absent: 0, skipped: 0, remaining: 0, capped: false,
+    };
+}
+/** 让出事件循环一次：滚动期间不能独占 tick（进度端点要能挤进来应答）。 */
+function tick() {
+    return new Promise((resolveTick) => { setImmediate(resolveTick); });
+}
+/**
+ * 滚到完：先把导出游标推到表尾，再把收敛游标推到表尾。
+ *
+ * 两阶段分开推进度，是因为收敛必须等导出把该写的文件写完——那时盘态最全，
+ * 判"盘上没这份"才准（反过来会把它误报成 `absent`）。
+ *
+ * @throws 已有任务在跑时抛（不排队，见模块头纪律 1）。
+ */
+export async function runProjection(deps) {
+    if (status.running)
+        throw new Error('已有 md 投影任务在跑，请等它结束（进度见面板）');
+    const clock = deps.now ?? Date.now;
+    const maxPasses = deps.maxPasses ?? 12;
+    const totalBudgetMs = deps.totalBudgetMs ?? 300_000;
+    const started = clock();
+    const total = deps.records.length;
+    Object.assign(status, {
+        running: true, phase: 'export', pass: 0, done: 0, total,
+        written: 0, renamed: 0, detail: `开始投影 ${total} 条`, startedAt: new Date(started).toISOString(), endedAt: '',
+    });
+    const out = {
+        root: '', inWorkspace: 0, scanned: 0, written: 0, unchanged: 0, skipped: 0,
+        remaining: 0, capped: false, passes: 0, suffix: blankSuffix(), appliedMaxRecords: deps.maxRecords,
+    };
+    const agg = blankSuffix();
+    try {
+        // ── 阶段 A：导出游标 ──
+        let cursor = 0;
+        for (let pass = 1; cursor < total && pass <= maxPasses; pass++) {
+            status.pass = pass;
+            status.phase = 'export';
+            const rep = await exportRecords({
+                records: deps.records.slice(cursor),
+                cfgRoot: deps.cfgRoot,
+                dataDir: deps.dataDir,
+                ledger: deps.ledger,
+                maxRecords: deps.maxRecords,
+                timeBudgetMs: deps.timeBudgetMs,
+                logger: deps.logger,
+                now: deps.now,
+            });
+            out.root = rep.root;
+            out.inWorkspace += rep.inWorkspace;
+            out.scanned += rep.scanned;
+            out.written += rep.written;
+            out.unchanged += rep.unchanged;
+            out.skipped += rep.skipped;
+            status.written = out.written;
+            // `remaining` 是"这一轮的输入里没处理完的条数"，所以游标 = 表长 - 剩余。
+            cursor = total - rep.remaining;
+            status.done = cursor;
+            status.detail = `导出第 ${pass} 轮：写 ${rep.written} · 未变 ${rep.unchanged} · 进度 ${cursor}/${total}`;
+            out.passes = pass;
+            out.capped = rep.capped;
+            if (clock() - started >= totalBudgetMs)
+                break;
+            await tick();
+        }
+        out.remaining = Math.max(0, total - cursor);
+        // ── 阶段 B：收敛游标（导出没滚完时也要跑：已写出的那批的后缀要先对上） ──
+        if (out.remaining === 0) {
+            let cur2 = 0;
+            for (let pass = 1; cur2 < total && pass <= maxPasses; pass++) {
+                status.pass = out.passes + pass;
+                status.phase = 'converge';
+                const s = await convergeDisabledSuffix({
+                    records: deps.records.slice(cur2),
+                    cfgRoot: deps.cfgRoot,
+                    dataDir: deps.dataDir,
+                    ledger: deps.ledger,
+                    maxRecords: deps.maxRecords,
+                    timeBudgetMs: deps.timeBudgetMs,
+                    logger: deps.logger,
+                    now: deps.now,
+                });
+                for (const k of ['scanned', 'renamed', 'revived', 'edited', 'already', 'both', 'absent', 'skipped'])
+                    agg[k] += s[k];
+                agg.remaining = s.remaining;
+                agg.capped = s.capped;
+                cur2 = total - s.remaining;
+                status.renamed = agg.renamed;
+                status.done = total + cur2;
+                status.detail = `后缀对齐第 ${pass} 轮：改名 ${s.renamed} · 进度 ${cur2}/${total}`;
+                out.passes += 1;
+                out.capped = s.capped;
+                if (clock() - started >= totalBudgetMs)
+                    break;
+                await tick();
+            }
+            out.remaining = Math.max(0, total - cur2);
+        }
+        out.suffix = agg;
+        status.phase = out.remaining > 0 ? 'failed' : 'done';
+        status.done = total + Math.max(0, Math.min(total, agg.scanned));
+        status.detail = out.remaining > 0
+            ? `总预算用尽：还剩 ${out.remaining} 个文件，再点一次续跑`
+            : `投影完成：写 ${out.written} · 改名 ${agg.renamed} · 共 ${out.passes} 轮`;
+        if (out.remaining > 0) {
+            status.notice = `单次任务预算（${maxPasses} 轮 / ${totalBudgetMs}ms）用尽，还剩 ${out.remaining} 个文件未处理——再点一次从断点续跑`;
+            out.capped = true;
+        }
+        return out;
+    }
+    catch (err) {
+        status.phase = 'failed';
+        status.notice = err instanceof Error ? err.message : String(err);
+        throw err;
+    }
+    finally {
+        status.running = false;
+        status.endedAt = new Date(clock()).toISOString();
+    }
+}

package/dist/store/memory-md-sync.d.ts

@@ -0,0 +1,59 @@
+import type { MemExportReport, SuffixReport } from './memory-md-types.js';
+import type { MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/** 生效的投射配置（现读，含 `live.mdExportMaxRecords` 覆盖后的预算）。 */
+export interface FileSyncCfg {
+    enabled: boolean;
+    root: string | undefined;
+    maxRecords: number;
+    timeBudgetMs: number;
+}
+export interface FileSyncDeps {
+    /** 取**变更后**的快照（判据要看新的 `validTo` / `name`）。 */
+    getByIds: (ids: readonly string[]) => readonly MemoryRecord[];
+    exportCfg: () => FileSyncCfg;
+    dataDir: string;
+    /** 账本未装配时整个挂钩空转（与投射面其他入口一致）。 */
+    ledger: () => MdLedgerStore | undefined;
+    logger?: MemoryLogger;
+}
+/**
+ * `L1Store` 侧的注入面：两类语义变更，调用方只管点火。
+ *
+ * - `sync`：有效性变了（增 / 退场 / 恢复）→ 导出该批 + 对齐后缀；
+ * - `renamed`：身份（`name`）变了 → 投射文件跟着搬（文件名就是 `name`，不搬就出现
+ *   「库里的名字与盘上的文件对不上」的偏离，收敛器也修不了，因为它按当前 name 算路径）。
+ */
+export interface L1FileSyncHook {
+    sync: (ids: readonly string[], why: string) => void;
+    renamed: (oldNameById: ReadonlyMap<string, string>, why: string) => void;
+}
+/** 一轮「导出 + 后缀收敛」的结果（反刍增量投射复用同一形状，不各写一套日志）。 */
+export interface SyncFilesResult {
+    exported: MemExportReport;
+    suffix: SuffixReport;
+}
+/** 一轮「导出 + 后缀收敛」必需的最小依赖（不需要按 id 回查的调用方拿这一份就够）。 */
+export type SyncFilesCoreDeps = Pick<FileSyncDeps, 'exportCfg' | 'dataDir' | 'ledger' | 'logger'>;
+/**
+ * 该批记录的投射跟随：导出 → 后缀收敛。**不打日志**（调用方自己的口径不同：钩子说
+ * “联动”，反刍说“增量”，统一格式反而把两者都稀释）；也不抛，异常由调用方收敛。
+ *
+ * @returns 两个报告；投射面关着或账本未装配时返回 `undefined`（调用方据此不打日志）。
+ */
+export declare function syncFiles(deps: SyncFilesCoreDeps, records: readonly MemoryRecord[]): Promise<SyncFilesResult | undefined>;
+/** 按 id 取快照后跑一轮 `syncFiles`（钩子走这个入口，判据只有一份）。 */
+export declare function syncFilesByIds(deps: FileSyncDeps, ids: readonly string[], why: string): Promise<SyncFilesResult | undefined>;
+/**
+ * 造注入给 `L1Store` 的挂钩。契约与 `disableProjectionFile` 一致：同步返回、异常只落日志。
+ *
+ * 双触发是**允许的**（`recall-feedback(-1)` 仍直接调 `disableProjectionFile` 拿确定性凭证）：
+ * 两条路径落到同一形状，第二次要么 ENOENT 兜底、要么 `already` 幂等。
+ *
+ * **串行队列（真机测出来的，不是洁癖）**：同一批文件与同一本账不能被两个后台任务同时
+ * 动。旧写法每次点火就自己开一个 promise，于是「先 `appendNew` 再 `retire`」这种紧邻的两次
+ * 点火会重叠：第二个任务的收敛器在第一个还没写出文件时判「盘上没这份」(`absent`)，
+ * 什么都不做——退场记录就永久停在 `.memory.md` 上，直到下次全量导出才被抬回来。
+ * 串成一条链后，后一个任务看到的是前一个的终态；执行时再按 id 回查快照，拿到的也是最新有效性。
+ */
+export declare function makeFileSyncHook(deps: FileSyncDeps): L1FileSyncHook;

package/dist/store/memory-md-sync.js

@@ -0,0 +1,152 @@
+/**
+ * 库 → 文件投射的**统一挂钩**（收口点）。
+ *
+ * 为什么收在 `L1Store` 而不是各个调用方：改变「记录有效性/身份」的写路径全部汇流到
+ * `appendNew` / `retire` / `restore` / `rename` 四个方法，而上游有 8 处 `retire()` 调用点
+ * （面板批量软删、Room 退役、`memory_delete` 工具、槽位连带、冲突裁决、合并取代、冲突自动
+ * 判负、召回判过时）。事件挂钩已被真机证伪：920 条退场记录里只有 8 个 `.disable`，全部来自
+ * 召回面板那一条路径。收在汇流口意味着——机器侧自动退场（合并取代、冲突判负）和模型侧
+ * `memory_add` 都自动跟随，以后新增调用点不会漏。
+ *
+ * 一次 `sync` 的形状固定为「导出 → 后缀收敛」，顺序不可反：收敛器判「盘上没有这份」要靠
+ * 导出先把这份写出来，反过来会把它算成 `absent` 而漏改名。调用方因此**不需要分辨自己
+ * 是增还是删**。
+ *
+ * 一句话口径：**投射文件形状是库状态的函数，不是任何调用点的事件**（事件只是重算契机）。
+ *
+ * 四条契约（前三条与 `makeSuffixSync` 时期一致，收口没有放宽）：
+ * 1. **不阻塞库**：钩子同步返回，文件侧在后台跑；磁盘满不能变成「记忆删不掉」。
+ * 2. **绝不抛**：异常一律收敛成 warn（与 `disableProjectionFile` 同纪律）。
+ * 3. **现读配置与账本**：`memExport` 是 volatile，快照会让「事后打开旋钮」一直到下次启动
+ *    才生效；账本在 `stores.l1` 之后才装配，所以也只能现拿（见 `setFileSyncHook` 晚绑定）。
+ * 4. **后台任务串行**：同一个文件树与同一本账不能被两个任务同时动，否则紧邻的两次点火
+ *    （先写后退）会互踩，退场记录会停在 `.memory.md` 上（详 `makeFileSyncHook`）。
+ *
+ * 批量路径**禁止逐条 flush 账本**（账本是整本 JSON 的原子重写，逐条 flush = O(n²)）：
+ * 统一走 `moveLedger(..., persist=false)` + 收尾一次 `flush()`。
+ */
+import { dirname } from 'node:path';
+import { rename, stat } from 'node:fs/promises';
+import { ensureDir } from '../util/io.js';
+import { exportRecords } from './memory-md-export.js';
+import { convergeDisabledSuffix, moveLedger } from './memory-md-disable.js';
+import { disablePathOf, isRetiredRecord, renderRecord, targetFor } from './memory-md.js';
+/** 存在性判定：一次 `stat`，任何错误都当「不存在」（与 `memory-md-disable.ts` 同口径）。 */
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 该批记录的投射跟随：导出 → 后缀收敛。**不打日志**（调用方自己的口径不同：钩子说
+ * “联动”，反刍说“增量”，统一格式反而把两者都稀释）；也不抛，异常由调用方收敛。
+ *
+ * @returns 两个报告；投射面关着或账本未装配时返回 `undefined`（调用方据此不打日志）。
+ */
+export async function syncFiles(deps, records) {
+    if (records.length === 0)
+        return undefined;
+    const cfg = deps.exportCfg();
+    const ledger = deps.ledger();
+    if (!cfg.enabled || ledger === undefined)
+        return undefined;
+    const base = { cfgRoot: cfg.root, dataDir: deps.dataDir, ledger, maxRecords: cfg.maxRecords, timeBudgetMs: cfg.timeBudgetMs, logger: deps.logger };
+    const exported = await exportRecords({ records, ...base });
+    const suffix = await convergeDisabledSuffix({ records, ...base });
+    return { exported, suffix };
+}
+/** 按 id 取快照后跑一轮 `syncFiles`（钩子走这个入口，判据只有一份）。 */
+export async function syncFilesByIds(deps, ids, why) {
+    if (ids.length === 0)
+        return undefined;
+    const out = await syncFiles(deps, deps.getByIds(ids));
+    if (out !== undefined) {
+        deps.logger?.info(`[memory] 投射联动(${why}): ${ids.length} 条,写 ${out.exported.written},未变 ${out.exported.unchanged},改名 ${out.suffix.renamed},改回 ${out.suffix.revived}`);
+    }
+    return out;
+}
+/**
+ * 改名跟随：把 `name` 变更的那批文件搬到新路径（含 `.disable` 兄弟）。
+ *
+ * 三种盘态：
+ * - 旧路径有文件 → 改名到新路径 + 账本换键（键是绝对路径，不换下一轮对账两边都错）；
+ * - 旧路径没文件 → 不报错，交给导出按新名补写（这条记录可能从没导出过）；
+ * - 新路径已被占用 → 只 warn 不动盘：`rename` 到已存在路径在 Windows 上会 EEXIST，
+ *   覆盖等于揉掉别人的投射文件，而 name 唯一性由写入侧管，这里不越权裁决。
+ */
+async function relocateRenamed(deps, oldNameById, why) {
+    const cfg = deps.exportCfg();
+    const ledger = deps.ledger();
+    if (!cfg.enabled || ledger === undefined || oldNameById.size === 0)
+        return;
+    const needExport = [];
+    let moved = 0;
+    for (const [id, oldName] of oldNameById) {
+        const r = deps.getByIds([id])[0];
+        if (r === undefined || r.name === undefined || r.name === oldName)
+            continue;
+        const oldTarget = targetFor({ ...r, name: oldName }, cfg.root, deps.dataDir, deps.logger);
+        const newTarget = targetFor(r, cfg.root, deps.dataDir, deps.logger);
+        if (oldTarget.absPath === undefined || newTarget.absPath === undefined)
+            continue;
+        // 退场记录的文件住在 `.disable` 上：后缀跟着走，别把无效态搬成有效态。
+        const retire = isRetiredRecord(r);
+        const from = retire ? disablePathOf(oldTarget.absPath) : oldTarget.absPath;
+        const to = retire ? disablePathOf(newTarget.absPath) : newTarget.absPath;
+        if (from === to)
+            continue;
+        if (!(await exists(from))) {
+            needExport.push(r);
+            continue;
+        }
+        if (await exists(to)) {
+            deps.logger?.warn(`[memory] 改名跟随跳过（目标已存在，不覆盖他人投射）: ${to}`);
+            continue;
+        }
+        try {
+            await ensureDir(dirname(to));
+            await rename(from, to);
+            await moveLedger(ledger, from, to, r, renderRecord(r).text, false);
+            moved++;
+        }
+        catch (err) {
+            deps.logger?.warn(`[memory] 改名跟随失败(下轮导出/收敛重试): ${from} → ${to} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 收尾落一次账：循环里只记脏（逐条 flush 会把整本 JSON 重写 N 次）。
+    await ledger.flush();
+    if (needExport.length > 0)
+        await syncFiles(deps, needExport);
+    if (moved > 0)
+        deps.logger?.info(`[memory] 改名跟随(${why}): 搬运 ${moved} 个投射文件,补写 ${needExport.length} 条`);
+}
+/**
+ * 造注入给 `L1Store` 的挂钩。契约与 `disableProjectionFile` 一致：同步返回、异常只落日志。
+ *
+ * 双触发是**允许的**（`recall-feedback(-1)` 仍直接调 `disableProjectionFile` 拿确定性凭证）：
+ * 两条路径落到同一形状，第二次要么 ENOENT 兜底、要么 `already` 幂等。
+ *
+ * **串行队列（真机测出来的，不是洁癖）**：同一批文件与同一本账不能被两个后台任务同时
+ * 动。旧写法每次点火就自己开一个 promise，于是「先 `appendNew` 再 `retire`」这种紧邻的两次
+ * 点火会重叠：第二个任务的收敛器在第一个还没写出文件时判「盘上没这份」(`absent`)，
+ * 什么都不做——退场记录就永久停在 `.memory.md` 上，直到下次全量导出才被抬回来。
+ * 串成一条链后，后一个任务看到的是前一个的终态；执行时再按 id 回查快照，拿到的也是最新有效性。
+ */
+export function makeFileSyncHook(deps) {
+    let chain = Promise.resolve();
+    const fire = (task, why) => {
+        chain = chain
+            .then(task)
+            .catch((err) => {
+            deps.logger?.warn(`[memory] 投射联动失败(${why}，不影响库侧结果，下轮导出重试): ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    return {
+        sync: (ids, why) => fire(() => syncFilesByIds(deps, ids, why), why),
+        renamed: (oldNameById, why) => fire(() => relocateRenamed(deps, oldNameById, why), why),
+    };
+}

package/dist/store/memory-md-types.d.ts

@@ -25,7 +25,36 @@ export interface MemExportReport {
     capped: boolean;
 }
 /**
- * `dsh-memory/mem-export` 的响应 = 导出报告 + 命名回填计数。
+ * 后缀不变式收敛报告（库里的“是否有效” ⇄ 文件后缀）。
+ *
+ * 口径：投射文件的后缀**只由这条记录在库里是否退场决定**，与 `name` 字段无关、
+ * 与“是哪条路径把它退场的”也无关。所以这个计数面不挂在某个按钮的事件后面，
+ * 而是每次导出都按「文件存在性 + 当前后缀 + 指纹一致性」重算一遍。
+ */
+export interface SuffixReport {
+    /** 本次遍历过的记录数（含什么都不做的）。 */
+    scanned: number;
+    /** 已退场但盘上还是 `.memory.md` → 已改名。 */
+    renamed: number;
+    /** 在库但只剩 `.disable`（且账本认得是我们写的）→ 已改回。 */
+    revived: number;
+    /** 改名前发现文件与账本指纹不符（人动过正文）；**仍照改**，改名不丢字节。 */
+    edited: number;
+    /** 后缀已经对上，没碰盘。 */
+    already: number;
+    /** 两份都在（或 `.disable` 不是我们写的）：语义相冲，**保守不动**，交人裁决。 */
+    both: number;
+    /** 盘上根本没有对应文件（从没导出过）：不凭空造。 */
+    absent: number;
+    /** 路径越界 / 单条失败（都各自留痕，不阻断整批）。 */
+    skipped: number;
+    /** 因护栏未处理到的剩余条数。 */
+    remaining: number;
+    /** 是否因墙钟/条数护栏提前收工（>0 时 UI 提示“再点一次继续”）。 */
+    capped: boolean;
+}
+/**
+ * `dsh-memory/mem-export` 的响应 = 导出报告 + 命名回填计数 + 后缀收敛计数。
  *
  * 为什么要单开一个类型：投射默认开后，导出这条路径现在会先做一步**写库**的命名回填
  * （给 `name` 为空的记录派生全库唯一的文件身份名）。它只改 `name`——内容/类型/退场态都不动，
@@ -37,9 +66,49 @@ export interface MemExportResponse extends MemExportReport {
     named: number;
     /** 起名算出来但落库失败的条数（下轮会重试）。 */
     nameFailed: number;
+    /** 导出后紧跟的后缀收敛结果（退场记录的文件该带 `.disable`）。 */
+    suffix: SuffixReport;
+    /**
+     * 本次实际滚了几轮（一轮 = 一次有界遍历）。
+     *
+     * 要报这个：`written`/`renamed` 是各轮累加的，人得知道“一次点击背后跑了 4 轮”
+     * 才不会把面板上的时长误读成“一次只能做这么多”。
+     */
+    passes: number;
+    /**
+     * 本次**实际生效**的单次动作护栏（包了 `live.mdExportMaxRecords` 覆盖后的值）。
+     *
+     * 为什么报而不是让人自己算：面板上那个旋钮经 `effectiveCfg` 落地，人看到的数字
+     * 必须是被应用过的那个，否则“改了但没生效”与“改了且生效”在报告上长得一样。
+     */
+    appliedMaxRecords: number;
+}
+/**
+ * 投影长任务的进度快照（`dsh-memory/mem-run-status` 的响应）。
+ *
+ * 形状住在这里而不是执行侧：`contract.ts` 要 import 它但不能把 `node:fs` 拖进
+ * client 编译程序（同本文件头的纪律）。
+ */
+export interface MdRunStatus {
+    running: boolean;
+    /** 当前阶段：导出（库→文件）/ 收敛（后缀对齐）/ 已结束。 */
+    phase: 'idle' | 'export' | 'converge' | 'done' | 'failed';
+    /** 第几轮（一轮 = 一次有界遍历）。 */
+    pass: number;
+    /** 两阶段合计已推进的条数（分母 = `total`×2，两阶段各算一遍全表）。 */
+    done: number;
+    total: number;
+    written: number;
+    renamed: number;
+    /** 人读的一行进度说明。 */
+    detail: string;
+    startedAt: string;
+    endedAt: string;
+    /** 出错或总预算用尽的说明（非空 = 需要再点一次续跑）。 */
+    notice?: string;
 }
 /**
- * 孤儿投射文件扫描报告（P4.4）。
+ * 孤儿投射文件遍历报告（P4.4）。
  *
  * “孤儿”只算**有账可查且没人认领**的路径：账本里没有的来路不明文件（人自己放进投射目录
  * 等着被同步的输入）一律不报也不动，所以这里没有“陌生文件”这一项——那个计数在同步侧。

package/dist/store/memory-md.d.ts

@@ -62,6 +62,15 @@ export type MdRecordInput = Pick<MemoryRecord, 'id' | 'content' | 'type' | 'prio
  * Windows 路径大小写不敏感，同一逻辑路径的两种写法解析到同一个文件，键自洽即可。
  */
 export declare function targetFor(r: MdRecordInput, cfgRoot: string | undefined, dataDir: string, logger?: MemoryLogger): MdTarget;
+/**
+ * 退场判据：与库侧同口径（`sqlite.ts` 的“`valid_to` 非空即退场”，与
+ * `retiredL1Count`/`listRetiredL1` 一致）。
+ *
+ * 为什么住在本文件：导出（要不要把文件放回非退场路径）与失效联动（后缀该不该带）
+ * 两侧都得用同一个判据，否则“列表说它退了、文件却没后缀”会回来。放 `memory-md-disable.ts`
+ * 会让 `memory-md-export.ts` 反向 import 它形成循环（那边已经 import 这边）。
+ */
+export declare function isRetiredRecord(r: Pick<MemoryRecord, 'validTo'>): boolean;
 /**
  * 投射文件的失效路径：`x.memory.md` → `x.memory.md.disable`。
  * 已带后缀的原样返回（幂等靠这个性质，而不是靠调用方记住判重）。

package/dist/store/memory-md.js

@@ -126,6 +126,17 @@ function warnMissingWorkspace(logger, ws) {
         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`。
  * 已带后缀的原样返回（幂等靠这个性质，而不是靠调用方记住判重）。

package/dist/tools/index.js

@@ -633,6 +633,7 @@ roomRegistry) {
             const record = buildRecord(args, scene, Date.now(), workspaceIdOf(exec));
             applyManualRedaction(record, cfg, logger);
             await stores.l1.appendNew([record]);
+            // 新增的投射落盘由 `appendNew` 里的 store 钩子承接（写删对称，这里不双写）。
             logger.info(`[memory] 高权限写入记忆(${record.type}${record.metadata?.hall ? '/' + String(record.metadata.hall) : ''},时间轴 ${record.persistence ?? '?'}):${record.content.slice(0, 120)}`);
             return { id: record.id };
         },
@@ -759,7 +760,7 @@ roomRegistry) {
                 records.push(record);
             });
             if (records.length > 0)
-                await stores.l1.appendNew(records);
+                await stores.l1.appendNew(records); // 同上：批量导入也由钩子上盘
             logger.info(`[memory] 批量导入 ${records.length} 条(幂等跳过 ${deduped} 条,场景 ${scene}${sourceId ? `,来源 ${sourceId}` : ''})`);
             return { written: records.length, deduped, ids: records.map((r) => r.id), skipped };
         },
@@ -832,6 +833,7 @@ roomRegistry) {
             // 可以在记忆列表里恢复,而不必去 records/*.jsonl 事实源手工捞。
             const n = stores.l1.retire(ids, { at: new Date().toISOString(), reason: 'manual' });
             logger.info(`[memory] 高权限退场(软删)记忆 ${n} 条(${ids.join('，')})`);
+            // 投射文件跟随不在这里点火：`l1.retire()` 是汇流口，钩子在那里（`store/memory-md-sync.ts`）。
             return { deleted: n, ids };
         },
     })));

package/dist/tools/slots.d.ts

@@ -13,5 +13,6 @@ import type { SessionModeStore } from '../store/session-modes.js';
 import type { SlotStore } from '../store/slots.js';
 import type { MemoryLogger } from '../types.js';
 export declare function registerSlotTools(ctx: Context, cfg: MemoryConfig, slots: SlotStore, logger: MemoryLogger, modes: SessionModeStore, live: LiveSettingsHandle, 
-/** L1 存储句柄:close 的 refs→记忆勾连(解析/退场)依赖;缺省时 close 只关槽位不碰 L1。 */
+/** L1 存储句柄:close 的 refs→记忆勾连(解析/退场)依赖;缺省时 close 只关槽位不碰 L1。
+ *  退场文件的跟随不在本模块点火：`l1.retire()` 已收口（`store/memory-md-sync.ts`）。 */
 l1?: L1Store): void;

package/dist/tools/slots.js

@@ -3,7 +3,8 @@ const MUTATE_OFF_NOTICE = '槽位写操作未开放:请在记忆库面板开启
 const OFF_NOTICE = '本会话的记忆档位为"关闭":槽位读取不可用。';
 const GLOBAL_OFF_NOTICE = '记忆召回已关闭:槽位读取不可用。';
 export function registerSlotTools(ctx, cfg, slots, logger, modes, live, 
-/** L1 存储句柄:close 的 refs→记忆勾连(解析/退场)依赖;缺省时 close 只关槽位不碰 L1。 */
+/** L1 存储句柄:close 的 refs→记忆勾连(解析/退场)依赖;缺省时 close 只关槽位不碰 L1。
+ *  退场文件的跟随不在本模块点火：`l1.retire()` 已收口（`store/memory-md-sync.ts`）。 */
 l1) {
     if (!cfg.tools)
         return;

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-prime-memory",
   "name": "dsh-prime-memory",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": {
     "en": "Layered distilled memory plugin (L0 capture → L1 atomic memory → L2 scenes → L3 persona) with automatic recall injection before each model step.",
     "zh": "L0~L3 分层蒸馏记忆插件:自动捕获对话、抽取原子记忆、整合场景块、蒸馏核心画像,并在模型步骤前自动召回注入。"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-prime-memory",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public",