dsh-prime-memory 0.22.2 → 0.24.1

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

@@ -0,0 +1,153 @@
+/**
+ * 孤儿投射文件的归档（P4.4）。
+ *
+ * 孤儿是怎么长出来的：投射路径 = `<type>/<name>.memory.md`，而 `name` 会变——本轮的
+ * 撞车消歧（42 条挤 17 个同名文件）、下一次的身份改名、以及记录被物理删除，都会让
+ * **磁盘上的旧路径不再属于任何记录**。它们既不报错也不碍事，只是越积越多，而人无法分辨
+ * 哪份是历史、哪份是刚被覆盖的。
+ *
+ * 只归档**有账可查**的那部分，判据是一条硬边界：
+ * - 账本里记着这个绝对路径（= 确认是我们自己写出去的），且**现在没有记录映射到它** → 孤儿，搬走；
+ * - 账本里没有 = 来路不明。那可能是人自己放进投射目录、等着被同步进来的输入，
+ *   **绝对不许动**（md 同步侧对这类文件只计数不入库，同一个纪律）。
+ *
+ * 搬 ≠ 删：整批进 `<dataDir>/memories-orphans/<批次时间戳>/`，保留 `<ws|home>/<类型>/<名>` 的
+ * 相对形状。删是 cleanup 的活，这里只负责别再挡在活档案里。账本条目跟着删——文件已经搬走，
+ * 留着基线下一轮对账就会一直报「文件缺失」。
+ */
+import { mkdir, rename, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { disablePathOf, resolveMemoriesRoot, safeJoin, targetFor } from './memory-md.js';
+import { deriveRelPath, looksAbsolute } from './memory-md-ledger.js';
+/** 样本条数上限：孤儿可能上千，面板不需要全量。 */
+const SAMPLE_CAP = 20;
+/**
+ * 扫一遍账本，把无人认领的投射文件搬进归档目录。
+ *
+ * @param deps - 见 `OrphanDeps`。
+ * @returns 报告；`dir` 在干跑时是空串（还没建批次目录）。任何单条失败只计数并留痕，绝不抛挂整轮。
+ */
+export async function sweepOrphanFiles(deps) {
+    const { records, cfgRoot, dataDir, ledger, logger } = deps;
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    const report = {
+        dryRun: deps.dryRun,
+        scanned: 0,
+        claimed: 0,
+        orphans: 0,
+        moved: 0,
+        failed: 0,
+        missing: 0,
+        remaining: 0,
+        capped: false,
+        dir: '',
+        samples: [],
+    };
+    const sample = (path, reason) => {
+        if (report.samples.length < SAMPLE_CAP)
+            report.samples.push({ path, reason });
+    };
+    // 认领集：每条记录现在的路径 + 它的 `.disable` 兄弟。后者必须在集合里，否则 N11 的失效
+    // 凭证会被当成孤儿搬走——那个后缀就是“这条已被判过时”的唯一文件侧表达。
+    const claimed = new Set();
+    for (const r of records) {
+        const abs = targetFor(r, cfgRoot, dataDir, logger).absPath;
+        if (abs === undefined)
+            continue;
+        claimed.add(abs);
+        claimed.add(disablePathOf(abs));
+    }
+    const homeRoot = resolveMemoriesRoot(cfgRoot, dataDir, logger);
+    const stamp = new Date(now()).toISOString().replace(/[:.]/g, '-');
+    const archiveBase = deps.archiveRoot ?? join(dataDir, 'memories-orphans');
+    const archiveDir = join(archiveBase, stamp);
+    // 走的是**带键**的遍历：账本的键才是绝对路径，条目里的 root/relPath 只供恢复归档形状。
+    const rows = ledger.allWithKeys();
+    // 配额只数**动作**（搬走/失败的孤儿），确认过“仍被认领”的不吃配额——与导出侧同一口径。
+    // 旧写法在这里会把配额花在“翻了一页全是认领”上，于是后面的孤儿永远扫不到，
+    // 报告却说“没孤儿”：那是把谎报写进了护栏。
+    let worked = 0;
+    for (let i = 0; i < rows.length; i++) {
+        // 两条护栏都在循环顶部查（写在末尾会被 continue 跳过，导出侧栽过）。
+        if (worked >= deps.maxFiles || now() - startedAt >= deps.timeBudgetMs) {
+            report.capped = true;
+            report.remaining = rows.length - i;
+            break;
+        }
+        const { path, entry: e } = rows[i];
+        report.scanned++;
+        if (path.length === 0) {
+            report.failed++;
+            worked++;
+            continue;
+        }
+        if (claimed.has(path)) {
+            report.claimed++;
+            continue;
+        }
+        report.orphans++;
+        if (deps.dryRun) {
+            // 干跑里“报出一个孤儿”就是本轮将要做的一个动作，所以它吃配额。
+            worked++;
+            sample(path, 'orphan');
+            continue;
+        }
+        // 账本说有文件、盘上没有：那是“文件缺失”，对账已经在报了，这里不重复处理，
+        // 也**不删账本条目**（删了就把“人把文件移走了”这个事实一起抹掉）。
+        if ((await stat(path).catch(() => undefined)) === undefined) {
+            report.missing++;
+            continue;
+        }
+        const side = e.root === homeRoot ? 'home' : 'ws';
+        // **不直接信存下来的 relPath**：它曾经被加载器污染成绝对路径（真机 1167/1241 条），
+        // 而 `safeJoin` 拦不住它——`join(归档根, 'home/C:\\Users\\…')` 的结果仍以归档根开头，
+        // 于是拼出含冒号的非法目录、75 条搬家全 ENOENT。键才是事实源：按 root+键重推，
+        // 推不出再退回存值（存值看着像绝对路径就一律不走）。
+        const rel = deriveRelPath(e.root, path) ?? (looksAbsolute(e.relPath) ? undefined : e.relPath);
+        const dest = rel === undefined ? undefined : safeJoin(archiveDir, `${side}/${rel}`);
+        if (rel === undefined || dest === undefined) {
+            // 账本被人手工编辑过（relPath 越界或 root 丢失）：宁可不动，也不要借这道手续把文件写到目录外。
+            report.failed++;
+            worked++;
+            sample(path, 'unsafe-relPath');
+            logger?.warn(`[memory] 孤儿投射跳过（推不出安全的归档相对路径）: ${path} → ${e.relPath}`);
+            continue;
+        }
+        try {
+            await mkdir(dirname(dest), { recursive: true });
+            await rename(path, await freeSlot(dest));
+            ledger.delete(path);
+            report.moved++;
+            worked++;
+            sample(path, 'moved');
+        }
+        catch (err) {
+            report.failed++;
+            worked++;
+            sample(path, 'failed');
+            logger?.warn(`[memory] 孤儿投射搬家失败: ${path} - ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!deps.dryRun && (report.moved > 0 || report.failed > 0))
+        report.dir = archiveDir;
+    await ledger.flush();
+    return report;
+}
+/**
+ * 目标位已被占用时加数字尾巴。
+ *
+ * 正常不会撞（每次跑都用新的批次目录），但账本里可能有两条指向同一 relPath 的不同绝对路径
+ * （不同 workspace 根），落进同一个 `ws/<类型>/<名>` 就会叠。叠了也不能覆盖——
+ * 那些文件是彼此不同的历史版本。
+ */
+async function freeSlot(dest) {
+    if ((await stat(dest).catch(() => undefined)) === undefined)
+        return dest;
+    for (let n = 2; n <= 999; n++) {
+        const candidate = `${dest}.${n}`;
+        if ((await stat(candidate).catch(() => undefined)) === undefined)
+            return candidate;
+    }
+    return `${dest}.${Date.now()}`;
+}

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

@@ -0,0 +1,35 @@
+/** 解析出的文件形状（值已按渲染时的类型还原）。 */
+export interface MdParsed {
+    /** 文件名干（= 渲染时写入的 `name` 键）。 */
+    name: string;
+    type: string;
+    priority: number;
+    /** ISO 串（渲染时就是 ISO；空串 = 没有）。 */
+    createdAt: string;
+    updatedAt: string;
+    usageScenario: string[];
+    extKey: string;
+    /** 文件里记的 record_id，只当线索。 */
+    id: string;
+    /** 文件声明的正文指纹（`hash` 键原文）；空串 = 老文件没带（未签名）。 */
+    hash: string;
+    /**
+     * 声明指纹与正文实算的比对：`true` 一致、`false` 不符、`undefined` = 文件没声明（无从判）。
+     *
+     * `false` **不是**拒收理由：正文被人改过恰恰是 P2 要回灌的正常输入；它只说明「文件不是
+     * 我们上次写出去的那份字节」，交给调用方计入报告并重盖指纹。结构性拒收仍在更上面
+     * （形状不符 / 正文为空）。
+     */
+    hashValid: boolean | undefined;
+    /** frontmatter 带 `retired: true`。 */
+    retired: boolean;
+    /** 正文（已去首尾空白）。 */
+    content: string;
+}
+/**
+ * 解析一个投射文件。
+ *
+ * @param text - 文件全文。
+ * @returns 解析结果；形状不符（无 frontmatter / 无正文 / 键全不认识）时 `undefined`。
+ */
+export declare function parseMdFile(text: string): MdParsed | undefined;

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

@@ -0,0 +1,85 @@
+/**
+ * md 投射文件的解析（P2 反向同步的读侧）。
+ *
+ * 只认 `memory-md.ts` 自己渲染出来的那种 frontmatter：`key: <JSON 值>`，正文在第二个
+ * `---` 之后。**不做通用 YAML**——通用解析器会接受我们从不产出的形状，那些形状进到
+ * 回灌路径就是"看起来能读、读回来是垃圾"。解析不出来就返回 `undefined`，调用方跳过并
+ * 计数；绝不猜、绝不抛。
+ *
+ * 一条刻意的不对称：文件里的 `id` 只当**线索**，不当身份。id 每轮新铸（F1），一次合并
+ * 就换；真正认人靠账本键（绝对路径）与 `name`。
+ *
+ * 另有一条自校验：frontmatter 里的 `hash` 是投射时盖下的正文指纹（N13）。这里只**核对**它
+ * 与正文本体是否一致（`hashValid`），不替调用方决定怎么处置——那属于同步侧的裁决。
+ */
+import { contentHash } from './memory-md.js';
+/** 取 frontmatter 块：首行必须是 `---`，到下一个 `---` 为止。 */
+function splitFrontmatter(text) {
+    // BOM 与 CRLF 都要先吃掉：人在记事本里改一行就会引入 \r，而 `\r` 会让 key 匹配不上。
+    const normalized = text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const lines = normalized.split('\n');
+    if (lines.length < 2 || lines[0].trim() !== '---')
+        return undefined;
+    const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+    if (end < 0)
+        return undefined;
+    return { meta: lines.slice(1, end), body: lines.slice(end + 1).join('\n').trim() };
+}
+/** 一行 `key: <JSON>` → [key, 值]；值解析失败则退回原始字符串。 */
+function readLine(line) {
+    const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (m === null)
+        return undefined;
+    const raw = m[2];
+    if (raw.length === 0)
+        return [m[1], ''];
+    try {
+        return [m[1], JSON.parse(raw)];
+    }
+    catch {
+        return [m[1], raw];
+    }
+}
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/**
+ * 解析一个投射文件。
+ *
+ * @param text - 文件全文。
+ * @returns 解析结果；形状不符（无 frontmatter / 无正文 / 键全不认识）时 `undefined`。
+ */
+export function parseMdFile(text) {
+    const parts = splitFrontmatter(text);
+    if (parts === undefined)
+        return undefined;
+    const fields = new Map();
+    for (const line of parts.meta) {
+        const kv = readLine(line);
+        if (kv !== undefined)
+            fields.set(kv[0], kv[1]);
+    }
+    // 正文为空 = 这条记忆没内容了。人手工清空正文不该被回灌成"一条空记忆"，
+    // 那既不是有效输入，也会让对账以为文件是权威。
+    if (parts.body.length === 0)
+        return undefined;
+    const scenario = Array.isArray(fields.get('usageScenario'))
+        ? fields.get('usageScenario').filter((s) => typeof s === 'string' && s.length > 0)
+        : [];
+    const prio = Number(fields.get('priority'));
+    const declaredHash = str(fields.get('hash'));
+    return {
+        name: str(fields.get('name')),
+        type: str(fields.get('type')),
+        priority: Number.isFinite(prio) ? prio : 60,
+        createdAt: str(fields.get('createdAt')),
+        updatedAt: str(fields.get('updatedAt')),
+        usageScenario: scenario,
+        extKey: str(fields.get('extKey')),
+        id: str(fields.get('id')),
+        hash: declaredHash,
+        hashValid: declaredHash.length === 0 ? undefined : declaredHash === contentHash(parts.body),
+        retired: fields.get('retired') === true,
+        content: parts.body,
+    };
+}

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

@@ -0,0 +1,48 @@
+import type { MdRunStatus, SuffixReport } from './memory-md-types.js';
+import type { MdLedgerStore } from './memory-md-ledger.js';
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/** 进度快照的形状与契约层共用一份定义（在 `memory-md-types.ts`），本模块只转发。 */
+export type { MdRunStatus };
+/** 只读快照副本（防调用方改到执行中的那份）。 */
+export declare function mdRunStatus(): MdRunStatus;
+export interface MdRunDeps {
+    /** 全表快照（含退场行）；本函数按游标切片喂给两个执行器。 */
+    records: readonly MemoryRecord[];
+    cfgRoot: string | undefined;
+    dataDir: string;
+    ledger: MdLedgerStore;
+    /** 单轮护栏（与 `cfg.memExport` 同值）。 */
+    maxRecords: number;
+    timeBudgetMs: number;
+    /** 跨轮总闸：最多滚几轮 / 最多花多少毫秒。 */
+    maxPasses?: number;
+    totalBudgetMs?: number;
+    logger?: MemoryLogger;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/** 滚动执行的汇总（形状与单轮报告一致，多出的字段告诉人滚了几轮）。 */
+export interface MdRunResult {
+    root: string;
+    inWorkspace: number;
+    scanned: number;
+    written: number;
+    unchanged: number;
+    skipped: number;
+    /** 0 = 两阶段都滚到完；>0 = 总预算用尽，剩这么多条没处理，再点一次续跑。 */
+    remaining: number;
+    capped: boolean;
+    /** 实际滚了几轮。 */
+    passes: number;
+    suffix: SuffixReport;
+    appliedMaxRecords: number;
+}
+/**
+ * 滚到完：先把导出游标推到表尾，再把收敛游标推到表尾。
+ *
+ * 两阶段分开推进度，是因为收敛必须等导出把该写的文件写完——那时盘态最全，
+ * 判"盘上没这份"才准（反过来会把它误报成 `absent`）。
+ *
+ * @throws 已有任务在跑时抛（不排队，见模块头纪律 1）。
+ */
+export declare function runProjection(deps: MdRunDeps): Promise<MdRunResult>;

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-skeleton.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryLogger } from '../types.js';
+/** 每类目录下的索引文件名（不带 `.memory.md`，因此天然落在投射/扫描面之外）。 */
+export declare const SKELETON_INDEX_FILE = "_index.md";
+export interface SkeletonDeps {
+    /** 要补骨架的投射根（绝对路径）列表。单根必补、workspace 根按需由调用方决定。 */
+    roots: readonly string[];
+    /** 目录名（= 类型）→ 库里条数；缺省按 0 计（0 也写，否则"没目录"与"0 条"仍无法区分）。 */
+    countsByType: ReadonlyMap<string, number>;
+    /** 诊断口：任何单目录写失败只走它留痕，绝不抛挂整轮。 */
+    logger?: MemoryLogger;
+}
+/**
+ * 往每个投射根补齐 37 类目录及各自的 `_index.md`。
+ *
+ * @param deps - 见 `SkeletonDeps`。
+ * @returns 无（副作用为落盘）。任何单目录失败只 warn，不抛。
+ */
+export declare function ensureTypeSkeleton(deps: SkeletonDeps): Promise<void>;

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

@@ -0,0 +1,61 @@
+/**
+ * 类型目录骨架 + `_index.md`（pm-name-distill Phase 4 / task_4.1）。
+ *
+ * 投射根（`<dataDir>/memories/` 或 `cfg.memExport.root`）过去只有"库里出现过记录"的类型目录
+ * （实测 6 个）；词表已扩到 37 类。空目录会被 git/压缩包吐掉，而"没这个目录"与"这类 0 条"
+ * 在人眼里长得一样——所以每类目录固定放一个 `_index.md`（类名 + 库里条数），目录集合从
+ * **词表真源** `memoryTypeDirs()` 派生，不再手抄。
+ *
+ * 三条纪律：
+ * 1. **幂等**：内容不变就不重写（也不刷 mtime）。投射是"库 → 文件"的旁路，重刷 mtime 会让
+ *    下一轮对账把"我们没动过"误判成"文件被改过"——与 `exportRecords` 的 mtime 纪律同口径。
+ * 2. **失败只 warn 不抛**：旁路写挂不能弄挂记忆本体（照 `resolveMemoriesRoot` / 导出侧的降级口径）。
+ * 3. **原子落盘**：临时文件 + rename，走仓内既有范式 `atomicWriteText`（带 fsync / 安全路径校验 /
+ *    失败清理）；根不存在由它内部 `ensureDir` recursive 建出。
+ *
+ * `_index.md` 刻意**不是**投射文件：md-sync 只认 `.memory.md` / `.memory.md.disable` 后缀
+ * （`listProjectionFiles`），孤儿扫描只遍历账本键（`sweepOrphanFiles`）——本模块从不把
+ * `_index.md` 写进账本，故两条通路都不会碰它（防误伤用例把这两条钉成断言）。
+ */
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { MEMORY_TYPE_LABELS, memoryTypeDirs } from '../memory-types.js';
+import { atomicWriteText } from '../util/io.js';
+/** 每类目录下的索引文件名（不带 `.memory.md`，因此天然落在投射/扫描面之外）。 */
+export const SKELETON_INDEX_FILE = '_index.md';
+/**
+ * 渲染一个目录的索引文本（纯函数：同一 (dir,label,count) 永远同一字节，幂等判据靠它）。
+ * 含类名标签、类型 id、条数三项——条数为 0 也如实写"0"。
+ */
+function renderIndex(dir, label, count) {
+    return `# ${label}\n\n- 类型: ${dir}\n- 条数: ${count}\n`;
+}
+/**
+ * 往每个投射根补齐 37 类目录及各自的 `_index.md`。
+ *
+ * @param deps - 见 `SkeletonDeps`。
+ * @returns 无（副作用为落盘）。任何单目录失败只 warn，不抛。
+ */
+export async function ensureTypeSkeleton(deps) {
+    const { roots, countsByType, logger } = deps;
+    // 目录集合来自词表真源，杜绝手抄漂移（换词表不改这里也不会静默少目录）。
+    const dirs = memoryTypeDirs();
+    for (const root of roots) {
+        for (const dir of dirs) {
+            const abs = join(root, dir, SKELETON_INDEX_FILE);
+            const count = countsByType.get(dir) ?? 0;
+            const label = MEMORY_TYPE_LABELS[dir] ?? dir;
+            const text = renderIndex(dir, label, count);
+            try {
+                // 读现内容比对：一致就跳过——既不重写，也不碰 mtime（atomicWriteText 会 rename 换 inode 刷 mtime）。
+                const existing = await readFile(abs, 'utf8').catch(() => undefined);
+                if (existing === text)
+                    continue;
+                await atomicWriteText(abs, text, { logger });
+            }
+            catch (err) {
+                logger?.warn(`[memory] 类型骨架写入失败(旁路，不影响投射本体): ${abs} - ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}

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;