dsh-prime-memory 0.22.1 → 0.24.0

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

@@ -0,0 +1,174 @@
+/**
+ * md 投射的**纯类型**面（无 IO、无 node 依赖）。
+ *
+ * 为什么要单独一个文件：`src/contract.ts` 的头部纪律是"只允许 type/interface，
+ * 不 import 任何运行时值"——它一旦被拉进 client 编译程序，就会连带把
+ * `node:fs`/`node:crypto` 的依赖也拖进去（实测：`tsc -p tsconfig.client.json`
+ * 立刻报 `Cannot find module 'node:path'`）。所以报告形状收在这里，
+ * 存储层与契约层各自 import type，**单一事实源仍然成立**。
+ */
+/** 导出报告（库 → 文件 + 账本）。`skipped` 含"路径越界/写盘失败"两类，都各自留痕。 */
+export interface MemExportReport {
+    /** 单根（无 workspace 归属那批落这里）；workspace 优先的条目不反映在此字段。 */
+    root: string;
+    /** 落在各 workspace 根下的条数（N10）。 */
+    inWorkspace: number;
+    /** 本次真正遍历过的条数（含未命中/跳过）。 */
+    scanned: number;
+    written: number;
+    /** 内容指纹一致、没重写的条数。 */
+    unchanged: number;
+    skipped: number;
+    /** 因护栏未处理的条数（>0 时 UI 提示"再点一次继续"）。 */
+    remaining: number;
+    /** 是否因墙钟/条数护栏提前收工。 */
+    capped: boolean;
+}
+/**
+ * `dsh-memory/mem-export` 的响应 = 导出报告 + 命名回填计数。
+ *
+ * 为什么要单开一个类型：投射默认开后，导出这条路径现在会先做一步**写库**的命名回填
+ * （给 `name` 为空的记录派生全库唯一的文件身份名）。它只改 `name`——内容/类型/退场态都不动，
+ * 而 `name` 不在 `canonicalRecords` 的快照哈希字段表里，所以「导出不改检索面」依旧成立；
+ * 但“导出什么都不写”这句话已经不成立了，把计数摆到响应上是让这笔写在面板上看得见。
+ */
+export interface MemExportResponse extends MemExportReport {
+    /** 本轮新起了多少条名字（0 = 全都已有名）。 */
+    named: number;
+    /** 起名算出来但落库失败的条数（下轮会重试）。 */
+    nameFailed: number;
+}
+/**
+ * 孤儿投射文件扫描报告（P4.4）。
+ *
+ * “孤儿”只算**有账可查且没人认领**的路径：账本里没有的来路不明文件（人自己放进投射目录
+ * 等着被同步的输入）一律不报也不动，所以这里没有“陌生文件”这一项——那个计数在同步侧。
+ */
+export interface OrphanSample {
+    path: string;
+    /** `orphan`（干跑时只报这个）/ `moved` / `failed` / `unsafe-relPath`。 */
+    reason: string;
+}
+export interface OrphanReport {
+    /** 本次是不是干跑（面板要知道这段数字是哪个模式出的，与 cleanup 同一个理由）。 */
+    dryRun: boolean;
+    /** 扫过的账本条目数。 */
+    scanned: number;
+    /** 仍被某条记录（含它的 `.disable` 兄弟）认领的。 */
+    claimed: number;
+    /** 无人认领的总数（干跑时就等于“将要搬走的数”）。 */
+    orphans: number;
+    moved: number;
+    failed: number;
+    /** 账本说有、盘上没：那是“文件缺失”，对账已经在报，这里不重复处理也不删账本。 */
+    missing: number;
+    /** 因护栏没扫完的剩余条目数。 */
+    remaining: number;
+    capped: boolean;
+    /** 本批归档目录（干跑或什么都没做时为空串）。 */
+    dir: string;
+    samples: OrphanSample[];
+}
+/** 四态计数（外加两个边界态）。 */
+export interface ReconcileCounts {
+    /** 账本里没有这条文件（首次导出前，或人新加了文件）。 */
+    firstTime: number;
+    /** 两边都没变。 */
+    same: number;
+    /** 只有库变了 → 该重渲染文件。 */
+    dbOnly: number;
+    /** 只有文件变了 → P2 该回灌库。 */
+    fileOnly: number;
+    /** 两边都变 → P2 挂待裁决，绝不自动覆盖任何一边。 */
+    both: number;
+    /** 账本说有文件、磁盘上没有（被删/被移走）。 */
+    missingFile: number;
+}
+/** 差异样本（人拿它决定要不要真同步）。 */
+export interface ReconcileSample {
+    relPath: string;
+    id: string;
+    state: keyof ReconcileCounts;
+}
+/** 对账报告。`capped` 时必须提醒"计数只覆盖已扫部分，不等于全库无差异"。 */
+export interface ReconcileReport extends ReconcileCounts {
+    root: string;
+    capped: boolean;
+    scanned: number;
+    samples: ReconcileSample[];
+}
+/** 反向同步的单条挂账样本（只给路径与做了什么，不给内容——内容可能含敏感信息）。 */
+export interface MdSyncSample {
+    path: string;
+    action: string;
+}
+/**
+ * P2 反向同步报告（文件 → 库）。
+ *
+ * 与对账报告的区别：对账**只读**，同步会写。所以这里的每个计数都对应一次真实动作，
+ * `pending` 那批除外——那批是刻意什么都不做。
+ */
+export interface MdSyncReport {
+    /** 本轮遍历过的投射根数（workspace 根 + 单根，N10）。 */
+    roots: number;
+    scanned: number;
+    /** 只有文件变 → 已回灌入库。 */
+    imported: number;
+    /** 只有库变 → 已重写文件。 */
+    rendered: number;
+    /** 两边都没变。 */
+    same: number;
+    /** 跳过（读不出/形状不符/写库失败）。 */
+    skipped: number;
+    /** **两边都变 → 挂待裁决**：两侧保持原样，等人裁决。 */
+    pending: number;
+    /** `.disable` → 已退场。 */
+    retired: number;
+    /** 没有账本、也认不出记录的新文件：本轮**不入库**（导入必须过写入内核）。 */
+    newFiles: number;
+    /** `.disable` 文件但找不到对应记录（改名后的 id 也追不到）。 */
+    orphan: number;
+    /**
+     * 遍历防护拦下的条目数（task_3.7）：dirent 报链接的条目、真实路径落在投射根外的目录、
+     * 以及 realpath 解析失败因而无法验证的目录（含整根划不出边界那一种）。
+     * 与 `skipped` 的区别：那是“进来了但不合格式”，这里是**根本没进**——两者混在一个数里
+     * 就分不清“文件写得不对”和“目录拓扑越界”，而后者的代价是扫描被链接吞掉整棵外部树。
+     */
+    skippedLinks: number;
+    /**
+     * 扫到了但**所在根不是这条记录当前的落点根**的文件数（换过 `memExport.root`、迁库、
+     * workspace 根与单根并存时会出现：同一条记录在两个根下各一份）。
+     *
+     * 它们一律**不参与象限判定、不回灌、不被重写**——拿旧根那份判“谁变了”、却往新根那份写，
+     * 会绕过“两边都变就不动”把新根覆盖掉（真机双向往返实测出的形状）。
+     * 这些文件本质是孤儿，处置归 `mem-orphans` 归档，不归同步。
+     * 注意判据只看**根**不看全路径：同根内嵌套目录里的人手文件仍是既有语义。
+     */
+    staleRootFiles: number;
+    /**
+     * 同一条记录被两份以上投射文件认领，且**多于一份被改过** → 这些文件本轮一律不动的件数。
+     *
+     * 成因是改名（撞车消歧 / 人改 `name` / 命名回填）后旧路径文件与旧账本条目都还留着——
+     * 搬走它们的是 `mem-orphans`，不是同步。两份各自独立判象限就会变成两次「仅文件变」回灌，
+     * **后跑的赢**，前一份人写的编辑被静默丢掉；而「两边都变就不动」是按单条账本条目判的，
+     * 看不见对面那份（真机沙箱实测：旧路径被改 → `imported 1`，库里正文来自已改名那一侧）。
+     * 这里把同记录的多路径当成一个裁决单元：只要多于一份有改动就全部挂账不动，等人自己定留哪份
+     * （把旧残片交给孤儿归档后，下一轮就只剩一份，判定回到正常轨道）。
+     */
+    multiPath: number;
+    /**
+     * 声明 `hash` 与正文实算**不符**的文件数（N13 自校验）：文件被外部改动或损坏，内容已不是
+     * 我们上次写出去的那份字节。它**不阻断**任何裁决——正文被人改过恰是 P2 要回灌的正常输入；
+     * 这里只把它从“静默按文件侧处理”变成“看得见地处理”。
+     */
+    hashMismatch: number;
+    /**
+     * 没带 `hash` 键的老投射文件数（升级前导出的产物）：本身无自校验能力，按兼容放行；
+     * 下一轮导出会补盖指纹，因此这个数会随同步推进自然收敛到 0。
+     */
+    unsigned: number;
+    /** 因护栏没扫完的剩余文件数。 */
+    remaining: number;
+    capped: boolean;
+    samples: MdSyncSample[];
+}

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

@@ -0,0 +1,10 @@
+/**
+ * md 投射的**纯类型**面（无 IO、无 node 依赖）。
+ *
+ * 为什么要单独一个文件：`src/contract.ts` 的头部纪律是"只允许 type/interface，
+ * 不 import 任何运行时值"——它一旦被拉进 client 编译程序，就会连带把
+ * `node:fs`/`node:crypto` 的依赖也拖进去（实测：`tsc -p tsconfig.client.json`
+ * 立刻报 `Cannot find module 'node:path'`）。所以报告形状收在这里，
+ * 存储层与契约层各自 import type，**单一事实源仍然成立**。
+ */
+export {};

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

@@ -0,0 +1,108 @@
+import type { MemoryLogger, MemoryRecord } from '../types.js';
+/**
+ * 允许当目录名的 type 值（pm-name-distill task_1.3：由词表单一真源派生，不再手抄）。
+ *
+ * 手抄的危害很具体：换词表不改这一处，新词表里的十余类会**静默落进兜底桶**——
+ * 不报错、不同步失败，只少目录树。
+ */
+export declare const MEMORY_TYPE_DIRS: ReadonlySet<string>;
+/**
+ * 不在词表的 type 落到这个目录（P4.1 的**默认类**）。
+ *
+ * 它是**目录层的投影**，不是库内事实：记录自己的 `type` 原值照旧写进 frontmatter，
+ * 也绝不回填到 `rowToRecord`/upsert/metadata（F5 红线）。之所以不直接归进某个 `work_*`：
+ * 那会把这批无类记录的 `family` 挑到 work 侧，而 family 决定共享面——等于静默改了可见性。
+ */
+export declare const UNSORTED_DIR = "unclassified";
+/** frontmatter 允许出现的键（用例断言键集**恰等于**它，防检索轴泄漏进文件）。 */
+export declare const FRONTMATTER_KEYS: readonly string[];
+/** 内容指纹长度（12 hex ≈ 48 bit；账本只用来判"变没变"，不当身份用）。 */
+export declare const DIGEST_HEX = 12;
+/** 失效后缀（N11）：`x.memory.md` → `x.memory.md.disable`。用户定名，取代原设计的 `.outdated`。 */
+export declare const DISABLE_SUFFIX = ".disable";
+/** workspace 优先时的子目录（N10）：`<workspace>/.agents/memory/…`。 */
+export declare const WORKSPACE_SUBDIR: readonly string[];
+/**
+ * 解析单根（无 workspace 归属的记录落这里）。
+ *
+ * 给了 `cfgRoot` 就用它（必须绝对路径且不含 `..`），否则默认 `<dataDir>/memories`。
+ * **不合法只回退默认并 warn，绝不抛错**：投射是旁路，旁路配置写错不能弄挂记忆本体。
+ */
+export declare function resolveMemoriesRoot(cfgRoot: string | undefined, dataDir: string, logger?: MemoryLogger): string;
+/**
+ * 把渲染出的相对路径安全地拼到根下。
+ *
+ * 越界（绝对路径、`..` 跳出、盘符切换）一律返回 `undefined` 由调用方跳过并 warn——
+ * 记录内容是人/模型写的，它可能包含 `../../`，这里必须是结构性挡死而不是"应该不会有"。
+ */
+export declare function safeJoin(root: string, relPath: string): string | undefined;
+/** 一个记录该落到哪。`absPath` 为 `undefined` = 越界，调用方必须跳过而不是写。 */
+export interface MdTarget {
+    /** 投射根（workspace 根或单根），绝对路径。 */
+    root: string;
+    /** 相对根的路径（正斜杠），展示与归档分目录用。 */
+    relPath: string;
+    /** 绝对路径——**账本键与文件操作都用它**。undefined = 越界。 */
+    absPath: string | undefined;
+    /** 是否落在 workspace 下（区分两个根，面板与归档路径都要看）。 */
+    inWorkspace: boolean;
+}
+/** 渲染一条记录所需的最小字段集（也是算落点所需的全部）。 */
+export type MdRecordInput = Pick<MemoryRecord, 'id' | 'content' | 'type' | 'priority' | 'createdAt' | 'updatedAt' | 'metadata' | 'validTo' | 'extKey' | 'name' | 'workspaceId'>;
+/**
+ * 投射落点（N10）：**workspace 优先**。
+ *
+ * 有 `workspaceId` ⇒ `<workspace>/.agents/memory/<type>/<stem>.memory.md`；
+ * 没有 ⇒ 单根（`cfg.memExport.root` 或 `<dataDir>/memories`）。
+ *
+ * ⚠️ **导出/对账/失效改名/归档四处必须共用本函数**。库里的 `workspace_id` 在 Windows 上是
+ * 小写形态（`normalizeWorkspacePath` 会 `.toLowerCase()`），任何一处自己拼路径、或者自己
+ * 转一下大小写，就会把“刚写进去的文件”算成另一个账本键 → 对账永远报“文件缺失”。
+ * 同理：**不**在这里做 `fs.realpath` 归一——那会让目录创建前后的键漂移，反而造出假缺失；
+ * Windows 路径大小写不敏感，同一逻辑路径的两种写法解析到同一个文件，键自洽即可。
+ */
+export declare function targetFor(r: MdRecordInput, cfgRoot: string | undefined, dataDir: string, logger?: MemoryLogger): MdTarget;
+/**
+ * 投射文件的失效路径：`x.memory.md` → `x.memory.md.disable`。
+ * 已带后缀的原样返回（幂等靠这个性质，而不是靠调用方记住判重）。
+ */
+export declare function disablePathOf(absPath: string): string;
+/**
+ * 内容指纹。
+ *
+ * 刻意**不复用** `memport/format.ts` 的 `contentHash`：那个口径被 TS↔Python 跨实现
+ * 金标准锁死（`tests/memport-ts-consistency`），改了就是让两边算出不同的包。这里只
+ * 借它的 `normText`（NFKC + 换行归一），口径独立、且明确标注为"投射账本专用"。
+ */
+export declare function digest(text: string): string;
+/**
+ * 投射文件自带 `hash` 键的**规范口径**（导出写、读入核，两侧都必须走它）。
+ *
+ * 定义 = `digest(归一后的正文)`：与 `renderRecord` 写进 `hash` 的值、以及读侧拿解析出的
+ * `content` 实算的值三处同源。只覆盖正文、不含任何 frontmatter 字段——所以换 id、换文件名、
+ * 退场标记都不改变它，它只回答「正文有没有被改过」这一件事。
+ *
+ * 走 `digest`（内含 NFKC + 空白折叠）而非裸 sha1：CRLF/BOM/尾随空白这类搬运噪声不该触发
+ * 假不符（搬文件、换编辑器、git autocrlf 都会引入它们）。
+ */
+export declare function contentHash(content: string): string;
+/** 记录内容指纹：正文字段（不含 metadata——轴变了不算内容变）。 */
+export declare function recordDigest(r: Pick<MemoryRecord, 'content'>): string;
+/**
+ * 文件名干：有 `name` 用 `name`；没有则回落 `mem-<id 后 8 位>`。
+ *
+ * 回落是**必需**的：存量记录 name 恒空（零回填红线），不回落就没法投射第一批。
+ * id 每轮新铸，所以回落名不稳定——这正是 P0 要先做 `name` 的原因，注释留在这里
+ * 免得后来人以为"回落名也能双向"。
+ */
+export declare function fileStemFor(r: Pick<MemoryRecord, 'id' | 'name' | 'content'>): string;
+/**
+ * 渲染一条记录。
+ *
+ * @param r - L1 记录（含已退场的——退场也要有投影，否则人在文件树里看不到它）。
+ * @returns `relPath`（相对投射根，已归一分隔符）与 `text`（全文）。
+ */
+export declare function renderRecord(r: MdRecordInput): {
+    relPath: string;
+    text: string;
+};

package/dist/store/memory-md.js

@@ -0,0 +1,219 @@
+/**
+ * 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}`);
+}
+/**
+ * 投射文件的失效路径：`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/memory-sources.d.ts

@@ -0,0 +1,59 @@
+import type { MemoryLogger } from '../types.js';
+/** sidecar 版本常量（file-versions 同款集中纪律）。 */
+export declare const MEMORY_SOURCES_FILE_VERSION: 1;
+/** 已知外部 agent 来源类别（与 memport foreign-agent.md 对齐）；'file' = 任意路径。 */
+export declare const SOURCE_KINDS: readonly ["trae", "qoder", "codex", "claude", "workbuddy", "golutra", "cursor", "file"];
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+export interface MemorySourceEntry {
+    /** 稳定 id（小写字母数字连字符）；扫描/导入按此归类、支持按来源撤销。 */
+    id: string;
+    kind: SourceKind;
+    /** 路径指针（绝对路径/目录），正文永不复制进来。 */
+    path: string;
+    label?: string;
+    /** 最近一次扫描时间（ISO）；未扫为空。 */
+    lastScanAt: string;
+    /** 最近一次导入时间（ISO）；未导入为空。 */
+    lastImportAt: string;
+    /** 用户临时停用（保留条目但不参与自动扫描；≠ 删除）。 */
+    disabled: boolean;
+    status: 'active' | 'retired';
+    createdAt: string;
+    updatedAt: string;
+}
+export type MemorySourceInput = Pick<MemorySourceEntry, 'id' | 'kind' | 'path'> & Partial<Pick<MemorySourceEntry, 'label'>>;
+export declare class MemorySourceStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private rev;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入（启动 await 一次）。缺失 = 合法空表；损坏 = 只读降级（回退"无来源"）。 */
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 全量条目（含 retired；副本返回，活引用纪律）。 */
+    list(): MemorySourceEntry[];
+    /** active 且未停用的来源（扫描/导入遍历用）。 */
+    listEnabled(): MemorySourceEntry[];
+    byId(id: string): MemorySourceEntry | undefined;
+    /** 登记来源（幂等：同 id 已存在则原地补全 kind/path/label，不新建）。上限防刷。 */
+    register(input: MemorySourceInput): Promise<{
+        entry: MemorySourceEntry;
+        created: boolean;
+    }>;
+    /** 记一次扫描时间。 */
+    markScanned(id: string, at: string): Promise<boolean>;
+    /** 记一次导入时间。 */
+    markImported(id: string, at: string): Promise<boolean>;
+    /** 启用/停用（停用保留条目、只是不参与自动扫描）。 */
+    setDisabled(id: string, disabled: boolean): Promise<boolean>;
+    /** 退役/恢复（status 迁移）。 */
+    setStatus(id: string, status: 'active' | 'retired'): Promise<boolean>;
+    private patch;
+    /** 写穿持久化（串行链；失败降级内存态并告警一次，绝不抛出阻塞调用方）。 */
+    private persist;
+}