@max-null/dsh-memory 0.20.0 → 0.22.0

package/dist/sync-tombstone.js

@@ -0,0 +1,83 @@
+/**
+ * 同步墓碑：把 `memory_forget` 的真删表达成「记录被修改」，而不是「文件消失」。
+ *
+ * **为什么需要**（设计 §3.1）：多写者下，本地看着「git 里有、我这儿没有」有两种可能——
+ * 本机删了（该删远端），或另一端刚加、我还没拉到（该拉下来）。两种情况的正确动作**完全
+ * 相反**，靠猜一定出错。
+ *
+ * 区分它们的唯一依据是**上一次同步时本机有哪些 id**：曾同步过、现在没了 ⇒ 本机删的。
+ * 所以本模块配一个随仓库走的 `.sync-state.json`。
+ *
+ * **墓碑不删文件、只改文件**，还顺带避开 git 里最难处理的 modify/delete 冲突：删除与
+ * 「另一端改了同一条」于是变成同一类冲突。
+ *
+ * **不记删前内容**：内容在 git 历史里（文件被删除但仍在历史），墓碑只负责回答
+ * 「这条是被删的还是还没同步到」。省下的体积换的是快照体积可控。
+ *
+ * @module dsh-memory/sync-tombstone
+ */
+/** 状态文件在同步仓库里的位置。 */
+export const SYNC_STATE_FILE = '.sync-state.json';
+/** 状态文件的相对路径（含墓碑目录）。 */
+export const TOMBSTONE_DIR = 'tombstones';
+/**
+ * 对比上一次与当前的 id 集合，算出本次该写哪些墓碑。
+ *
+ * **首次同步（`previous` 为空）永远不产生墓碑**：那时没有「曾经有过」这个信息，
+ * 把所有"远端有、本地没有"都判成删除会把另一端刚记的东西全删掉。这是整个模块最容易
+ * 写错的一处。
+ *
+ * @param options - 上次状态、当前状态与删除时刻。
+ * @returns 待写墓碑列表。
+ */
+export function planTombstones(options) {
+    const { previous, current, at } = options;
+    if (previous === undefined)
+        return [];
+    const tombstones = [];
+    const currentGlobal = new Set(current.global);
+    for (const id of previous.global) {
+        if (!currentGlobal.has(id))
+            tombstones.push({ id, scope: 'global', deletedAt: at });
+    }
+    for (const [projectName, ids] of Object.entries(previous.project)) {
+        const still = new Set(current.project[projectName] ?? []);
+        for (const id of ids) {
+            if (!still.has(id))
+                tombstones.push({ id, scope: 'project', projectName, deletedAt: at });
+        }
+    }
+    return tombstones;
+}
+/**
+ * 把墓碑合并进上一次的状态：写过的墓碑不该在下一轮又被判成"删除"。
+ *
+ * 具体做法是把墓碑 id 从 `previous` 里剔掉——它们的删除已经被记录过了。
+ *
+ * @param state - 刚刚用于比对的那份状态。
+ * @param written - 本次写下的墓碑。
+ * @returns 更新后的状态。
+ */
+export function dropTombstoned(state, written) {
+    if (written.length === 0)
+        return state;
+    const globalGone = new Set(written.filter(t => t.scope === 'global').map(t => t.id));
+    const projectGone = new Map();
+    for (const tombstone of written) {
+        if (tombstone.scope !== 'project' || tombstone.projectName === undefined)
+            continue;
+        const key = tombstone.projectName;
+        const set = projectGone.get(key) ?? new Set();
+        set.add(tombstone.id);
+        projectGone.set(key, set);
+    }
+    const project = {};
+    for (const [name, ids] of Object.entries(state.project)) {
+        const gone = projectGone.get(name);
+        project[name] = gone === undefined ? ids : ids.filter(id => !gone.has(id));
+    }
+    return {
+        global: state.global.filter(id => !globalGone.has(id)),
+        project,
+    };
+}

package/dist/sync-writer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 同步写盘层：把 {@link exportRecords} 的输出落到磁盘上的镜像目录。
+ *
+ * **两条硬要求**（见设计文档 §9.2 第 1 步）：
+ *
+ * 1. **增量**：内容相同的文件不重写。不做这件事的后果不是"慢"，是每次写盘都产生
+ *    一批 mtime 变动——git 看起来像全量改动，`git log` 与 `git diff` 随即失去意义。
+ * 2. **删除先算差集**：现有文件里不在待写列表的才算该删。不能边扫边删——边扫边删
+ *    在目录枚举顺序变化时会漏删或错删。
+ *
+ * **只管 `records/`**：`conflicts/`（§3.3 的留证）与 `index.json`（§3.2 的派生品）
+ * 都不归这里管。写盘层负责的是"把记忆库投影成一条一文件"，不是"维护整个同步仓库"。
+ *
+ * @module dsh-memory/sync-writer
+ */
+import type { SyncRecordFile } from './sync-export.ts';
+/** {@link writeMirror} 的入参。 */
+export interface MirrorWriteOptions {
+    /** 镜像仓库的根（`records/` 就在它下面）。 */
+    readonly targetDir: string;
+    /** 待写入的记录文件；路径相对 `targetDir`。 */
+    readonly files: readonly SyncRecordFile[];
+}
+/** 一次写盘的结果。 */
+export interface MirrorWriteRun {
+    /** 真正写了的文件数（内容有变化的）。 */
+    readonly written: number;
+    /** 内容与磁盘一致的、跳过的文件数。 */
+    readonly unchanged: number;
+    /** 被删掉的文件数。 */
+    readonly removed: number;
+    /** 被删掉的相对路径（便于日志与测试断言）。 */
+    readonly removedPaths: readonly string[];
+}
+/**
+ * 把记录文件镜像到磁盘。**纯 IO，不读写任何记忆状态**。
+ *
+ * 三个步骤按固定顺序：先算差集（该删哪些）、再写（内容有变的）、最后删。
+ * 顺序不能调换——先删会让"写失败 + 删成功"变成净损失。
+ *
+ * 单文件失败不会中断整批：记忆镜像少一份总比整次同步失败好，缺的那份下次写盘会补上。
+ *
+ * @param options - 目标目录与待写文件。
+ * @returns 写入 / 跳过 / 删除的统计。
+ */
+export declare function writeMirror(options: MirrorWriteOptions): MirrorWriteRun;

package/dist/sync-writer.js

@@ -0,0 +1,85 @@
+/**
+ * 同步写盘层：把 {@link exportRecords} 的输出落到磁盘上的镜像目录。
+ *
+ * **两条硬要求**（见设计文档 §9.2 第 1 步）：
+ *
+ * 1. **增量**：内容相同的文件不重写。不做这件事的后果不是"慢"，是每次写盘都产生
+ *    一批 mtime 变动——git 看起来像全量改动，`git log` 与 `git diff` 随即失去意义。
+ * 2. **删除先算差集**：现有文件里不在待写列表的才算该删。不能边扫边删——边扫边删
+ *    在目录枚举顺序变化时会漏删或错删。
+ *
+ * **只管 `records/`**：`conflicts/`（§3.3 的留证）与 `index.json`（§3.2 的派生品）
+ * 都不归这里管。写盘层负责的是"把记忆库投影成一条一文件"，不是"维护整个同步仓库"。
+ *
+ * @module dsh-memory/sync-writer
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 记录文件所在的顶层目录名。 */
+const RECORDS_DIR = 'records';
+/** 路径规范成 `/` 分隔——`exportRecords` 用 `join()` 产出，在 Windows 上是反斜杠。 */
+function normalize(path) {
+    return path.replace(/\\/gu, '/');
+}
+/** 递归列出 `root` 下的文件，返回相对 `relBase` 的路径（`/` 分隔）。 */
+function scan(root, relBase) {
+    if (!existsSync(root))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const rel = relBase === '' ? entry.name : `${relBase}/${entry.name}`;
+        if (entry.isDirectory())
+            found.push(...scan(join(root, entry.name), rel));
+        else
+            found.push(rel);
+    }
+    return found;
+}
+/**
+ * 把记录文件镜像到磁盘。**纯 IO，不读写任何记忆状态**。
+ *
+ * 三个步骤按固定顺序：先算差集（该删哪些）、再写（内容有变的）、最后删。
+ * 顺序不能调换——先删会让"写失败 + 删成功"变成净损失。
+ *
+ * 单文件失败不会中断整批：记忆镜像少一份总比整次同步失败好，缺的那份下次写盘会补上。
+ *
+ * @param options - 目标目录与待写文件。
+ * @returns 写入 / 跳过 / 删除的统计。
+ */
+export function writeMirror(options) {
+    const recordsRoot = join(options.targetDir, RECORDS_DIR);
+    // 待写集合：normalize 之后的相对路径 → 内容
+    const wanted = new Map();
+    for (const file of options.files)
+        wanted.set(normalize(file.path), file.content);
+    // 差集先算：磁盘上有、但这次不该存在的，才是要删的
+    const stale = scan(recordsRoot, RECORDS_DIR).filter(path => !wanted.has(path));
+    let written = 0;
+    let unchanged = 0;
+    for (const [relativePath, content] of wanted) {
+        const absolute = join(options.targetDir, relativePath);
+        try {
+            if (existsSync(absolute) && readFileSync(absolute, 'utf8') === content) {
+                unchanged += 1;
+                continue;
+            }
+            mkdirSync(dirname(absolute), { recursive: true });
+            writeFileSync(absolute, content, 'utf8');
+            written += 1;
+        }
+        catch {
+            // 单个文件写失败不中断整批；缺的那份下次写盘会补。
+        }
+    }
+    const removedPaths = [];
+    for (const relativePath of stale) {
+        try {
+            rmSync(join(options.targetDir, relativePath), { force: true });
+            removedPaths.push(relativePath);
+        }
+        catch {
+            // 同上：删除失败留到下次。
+        }
+    }
+    return { written, unchanged, removed: removedPaths.length, removedPaths };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {
@@ -66,6 +66,7 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.4",
+    "isomorphic-git": "^1.44.11",
     "zod": "^4.4.3"
   },
   "peerDependencies": {