@max-null/dsh-memory 0.20.0 → 0.22.0

package/dist/sync-remote.js

@@ -0,0 +1,157 @@
+/**
+ * 同步镜像的远端层：`push` / `pull` / 状态查询。
+ *
+ * **必须走 HTTP**：`isomorphic-git` 的 `push` 在没有 `http` 参数时直接抛
+ * `The function requires a "http" parameter but none was provided`（2026-11-11 实测，
+ * 想用本地 bare 仓库做离线测试也走不通）。所以本层天然依赖网络，与上一层的
+ * `sync-git.ts`（纯本地、可离线全测）分开。
+ *
+ * **认证用 PAT（https）而不是 SSH**：SSH key 在移动端的管理成本远高于 token，
+ * 而 dsh-go 那类环境正是目标场景之一。
+ *
+ * **token 不进 profile 配置**：由调用方从既有 credentials 机制取出后传入。本模块只
+ * 负责把它放进 http 请求，不负责存。
+ *
+ * @module dsh-memory/sync-remote
+ */
+import * as nodeFs from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** 默认分支。 */
+const DEFAULT_BRANCH = 'main';
+/** 动态载入 isomorphic-git 与它的 Node http 实现。 */
+async function loadGit() {
+    const [git, http] = await Promise.all([
+        import('isomorphic-git'),
+        import('isomorphic-git/http/node'),
+    ]);
+    return { git: git.default, http: http.default };
+}
+/** 把原始错误归到三类之一，便于调用方决定是改凭据还是重试。 */
+function classify(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const text = raw.toLowerCase();
+    // 401/403、authentication failed、invalid credentials、权限不足
+    if (/401|403|auth|credential|permission|denied|token/u.test(text)) {
+        return { ok: false, error: raw, kind: 'auth' };
+    }
+    if (/enotfound|econnrefused|etimedout|timeout|network|dns|socket|offline/u.test(text)) {
+        return { ok: false, error: raw, kind: 'network' };
+    }
+    return { ok: false, error: raw, kind: 'unknown' };
+}
+/** 组装 isomorphic-git 的 onAuth 回调。 */
+function authFor(token) {
+    return () => (token === undefined || token === ''
+        ? { username: 'git' }
+        : { username: 'x-access-token', password: token });
+}
+/** 镜像目录是不是一个已初始化的仓库。 */
+function isRepo(dir) {
+    return existsSync(join(dir, '.git'));
+}
+/**
+ * 确保镜像目录是一个**与远端有共同历史**的仓库。
+ *
+ * 首次同步时如果只 `git init`，本地与远端是两条无关的历史线——push 会被拒
+ * （`Push rejected because it was not a simple fast-forward`）。这是 2026-11-11
+ * 第一次用真实仓库跑时撞出来的：单元测试里没有真远端，所以永远发现不了。
+ *
+ * 因此首次必须 clone，而不是 init + push。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 是否执行了 clone；失败时带分类。
+ */
+export async function ensureMirrorRepo(options) {
+    if (isRepo(options.dir))
+        return { cloned: false };
+    const { git, http } = await loadGit();
+    try {
+        await git.clone({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            url: options.url,
+            ref: options.branch ?? DEFAULT_BRANCH,
+            depth: 1,
+            onAuth: authFor(options.token),
+        });
+        return { cloned: true };
+    }
+    catch (error) {
+        return { cloned: false, ...classify(error) };
+    }
+}
+/**
+ * 把本地提交推到远端。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export async function pushMirror(options) {
+    if (!isRepo(options.dir)) {
+        return { ok: false, error: `not a git repository: ${options.dir}`, kind: 'unknown' };
+    }
+    const { git, http } = await loadGit();
+    try {
+        await git.push({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            remote: 'origin',
+            ref: options.branch ?? DEFAULT_BRANCH,
+            onAuth: authFor(options.token),
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return classify(error);
+    }
+}
+/**
+ * 从远端拉取并快进本地。
+ *
+ * `fastForwardOnly: true`：合并策略不该由这一层决定。本地有分叉时宁可失败让人看见，
+ * 也不要让 isomorphic-git 悄悄造出一个 merge commit。
+ *
+ * @param options - 目录、远端地址、分支与 token。
+ * @returns 成功与否；失败时带分类。
+ */
+export async function pullMirror(options) {
+    if (!isRepo(options.dir)) {
+        return { ok: false, error: `not a git repository: ${options.dir}`, kind: 'unknown' };
+    }
+    const { git, http } = await loadGit();
+    try {
+        await git.pull({
+            fs: nodeFs,
+            http,
+            dir: options.dir,
+            remote: 'origin',
+            ref: options.branch ?? DEFAULT_BRANCH,
+            fastForwardOnly: true,
+            author: { name: 'dsh-memory', email: 'dsh-memory@localhost' },
+            onAuth: authFor(options.token),
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return classify(error);
+    }
+}
+/**
+ * 确保 `origin` 指向给定地址。地址变化时重设（用户换了仓库）。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param url - 期望的远端地址。
+ */
+export async function ensureRemote(dir, url) {
+    if (!isRepo(dir))
+        return;
+    const { git } = await loadGit();
+    const remotes = await git.listRemotes({ fs: nodeFs, dir });
+    const origin = remotes.find(remote => remote.remote === 'origin');
+    if (origin?.url === url)
+        return;
+    await git.addRemote({ fs: nodeFs, dir, remote: 'origin', url, force: true });
+}

package/dist/sync-service.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 同步编排：把导出 / 写盘 / 墓碑 / git / 远端五层串成一次操作。
+ *
+ * 这一层没有自己的算法，只有**顺序**。顺序在这里是有意义的：
+ *
+ * push 时先写镜像与墓碑、再提交、最后推送——反过来的话，一次失败会留下
+ * 「远端已有、本地没有」的状态，下次 push 会把差异当成删除。
+ *
+ * pull 时先拉、再规划导入、最后逐条落地——导入是唯一会改本地记忆库的一步，
+ * 放在最后意味着前面任何一步失败都不会动数据。
+ *
+ * @module dsh-memory/sync-service
+ */
+import type { MemoryEngine } from './engine.ts';
+import type { SyncRecordFile } from './sync-export.ts';
+import type { ImportConflict } from './sync-import.ts';
+/** 同步配置。 */
+export interface SyncConfig {
+    /** 镜像仓库目录。 */
+    readonly mirrorDir: string;
+    /** 远端地址（https）；缺省时只做本地提交。 */
+    readonly remote?: string;
+    /** 分支名；缺省 `main`。 */
+    readonly branch?: string;
+    /** 环境短名，用于冲突留证与提交信息；缺省「本机」。 */
+    readonly envName?: string;
+    /**
+     * HTTPS token。**不从配置里读**——由调用方从环境变量或凭据机制取出后传入，
+     * 避免它落进 profile 配置或提交历史。
+     */
+    readonly token?: string;
+}
+/** 一次 push 的结果。 */
+export interface SyncPushRun {
+    readonly files: number;
+    readonly written: number;
+    readonly unchanged: number;
+    readonly removed: number;
+    readonly tombstones: number;
+    readonly committed: boolean;
+    readonly sha?: string;
+    readonly pushed: boolean;
+    readonly error?: string;
+    readonly errorKind?: 'auth' | 'network' | 'unknown';
+}
+/** 一次 pull 的结果。 */
+export interface SyncPullRun {
+    readonly pulled: boolean;
+    readonly imported: number;
+    readonly conflicts: number;
+    readonly orphaned: number;
+    readonly error?: string;
+    readonly errorKind?: 'auth' | 'network' | 'unknown';
+}
+/** 同步状态快照（给 `memory_sync status`）。 */
+export interface SyncStatus {
+    readonly mirrorDir: string;
+    readonly initialized: boolean;
+    readonly remote?: string;
+    readonly lastCommit?: {
+        sha: string;
+        message: string;
+        at: number;
+    };
+    readonly commits: number;
+    readonly conflicts: number;
+    readonly tombstones: number;
+}
+/**
+ * 收集当前记忆库应有的镜像文件。
+ *
+ * 空项目不产生目录——`records/project/<name>/` 里一个文件都没有时，那个目录本身
+ * 不该出现在仓库里（否则每加一个空项目就多一个空目录）。
+ *
+ * @param memory - 引擎实例。
+ * @returns 待写入的记录文件列表。
+ */
+export declare function collectMirror(memory: MemoryEngine): Promise<readonly SyncRecordFile[]>;
+/**
+ * 推一次：收集 → 写镜像 → 写墓碑 → 提交 → 推送。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点（测试用）。
+ * @returns 各阶段统计；远端失败时保留本地提交已完成的事实。
+ */
+export declare function syncPush(memory: MemoryEngine, config: SyncConfig, now?: number): Promise<SyncPushRun>;
+/**
+ * 拉一次：拉取 → 规划导入 → 逐条落地。
+ *
+ * 冲突不自动裁决：两边版本都写进 `conflicts/`，本地版本保留（§3.3）。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点。
+ * @returns 导入统计。
+ */
+export declare function syncPull(memory: MemoryEngine, config: SyncConfig, now?: number): Promise<SyncPullRun>;
+/**
+ * 查同步状态。
+ *
+ * @param config - 同步配置。
+ * @returns 镜像目录、最近提交、冲突与墓碑数量。
+ */
+export declare function syncStatus(config: SyncConfig): Promise<SyncStatus>;
+/** 便于测试：导出一份当前冲突的快照。 */
+export declare function conflictFiles(config: SyncConfig): string[];
+export type { ImportConflict };

package/dist/sync-service.js

@@ -0,0 +1,347 @@
+/**
+ * 同步编排：把导出 / 写盘 / 墓碑 / git / 远端五层串成一次操作。
+ *
+ * 这一层没有自己的算法，只有**顺序**。顺序在这里是有意义的：
+ *
+ * push 时先写镜像与墓碑、再提交、最后推送——反过来的话，一次失败会留下
+ * 「远端已有、本地没有」的状态，下次 push 会把差异当成删除。
+ *
+ * pull 时先拉、再规划导入、最后逐条落地——导入是唯一会改本地记忆库的一步，
+ * 放在最后意味着前面任何一步失败都不会动数据。
+ *
+ * @module dsh-memory/sync-service
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exportRecords } from "./sync-export.js";
+import { commitMirror, readHistory } from "./sync-git.js";
+import { planImport } from "./sync-import.js";
+import { SYNC_STATE_FILE, TOMBSTONE_DIR, dropTombstoned, planTombstones } from "./sync-tombstone.js";
+import { ensureMirrorRepo, ensureRemote, pullMirror, pushMirror } from "./sync-remote.js";
+import { writeMirror } from "./sync-writer.js";
+/** 作者信息——isomorphic-git 没有可读的全局配置，必须显式给。 */
+const AUTHOR = { name: 'dsh-memory', email: 'dsh-memory@localhost' };
+/** 把一份 unit 文档里的 block 取出来。 */
+function blocksOfDocument(document) {
+    const doc = document;
+    return doc?.tables?.blocks ?? {};
+}
+/** 记录数组 → unit 文档形状（`exportRecords` 的入参）。 */
+function recordsToDocument(records) {
+    const blocks = {};
+    for (const record of records) {
+        const { id, ...rest } = record;
+        blocks[id] = rest;
+    }
+    return { tables: { blocks } };
+}
+/**
+ * 收集当前记忆库应有的镜像文件。
+ *
+ * 空项目不产生目录——`records/project/<name>/` 里一个文件都没有时，那个目录本身
+ * 不该出现在仓库里（否则每加一个空项目就多一个空目录）。
+ *
+ * @param memory - 引擎实例。
+ * @returns 待写入的记录文件列表。
+ */
+export async function collectMirror(memory) {
+    const global = await memory.list({ namespace: 'global' });
+    const projectDocuments = [];
+    for (const cwd of memory.projectCwds()) {
+        const records = await memory.list({ namespace: 'project' }, cwd);
+        if (records.length === 0)
+            continue;
+        projectDocuments.push({ cwd, document: recordsToDocument(records) });
+    }
+    return exportRecords({ globalDocument: recordsToDocument(global), projectDocuments }).files;
+}
+/** 从镜像文件列表推出「当前有哪些 id」——墓碑比对的当前态。 */
+function stateOfFiles(files) {
+    const global = [];
+    const project = {};
+    for (const file of files) {
+        const parts = file.path.replace(/\\/gu, '/').split('/');
+        // records/global/<id>.json 或 records/project/<name>/<id>.json
+        if (parts[0] !== 'records' || parts.length < 3)
+            continue;
+        const id = parts[parts.length - 1]?.replace(/\.json$/u, '') ?? '';
+        if (id === '')
+            continue;
+        if (parts[1] === 'global')
+            global.push(id);
+        else if (parts[1] === 'project' && parts.length >= 4) {
+            const name = parts[2] ?? '';
+            (project[name] ??= []).push(id);
+        }
+    }
+    return { global, project };
+}
+/** 读上一次同步留下的状态；没有时返回 `undefined`（首次同步）。 */
+function readState(dir) {
+    const file = join(dir, SYNC_STATE_FILE);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return {
+            global: Array.isArray(parsed.global) ? parsed.global : [],
+            project: typeof parsed.project === 'object' && parsed.project !== null ? parsed.project : {},
+        };
+    }
+    catch {
+        // 坏了就当没有：宁可这轮不产生墓碑，也不要基于坏数据删东西。
+        return undefined;
+    }
+}
+/** 写状态文件。 */
+function writeState(dir, state) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, SYNC_STATE_FILE), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/** 把墓碑落成文件（`tombstones/<id>.json`）。 */
+function writeTombstones(dir, tombstones) {
+    if (tombstones.length === 0)
+        return;
+    const target = join(dir, TOMBSTONE_DIR);
+    mkdirSync(target, { recursive: true });
+    for (const tombstone of tombstones) {
+        writeFileSync(join(target, `${tombstone.id}.json`), `${JSON.stringify(tombstone, null, 2)}\n`, 'utf8');
+    }
+}
+/**
+ * 推一次：收集 → 写镜像 → 写墓碑 → 提交 → 推送。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点（测试用）。
+ * @returns 各阶段统计；远端失败时保留本地提交已完成的事实。
+ */
+export async function syncPush(memory, config, now = Date.now()) {
+    // 首次同步**必须先 clone**：本地 `git init` 出来的仓库与远端是两条无关的历史线，
+    // push 会被拒（`not a simple fast-forward`）。这一步得在写镜像之前，否则写好的内容
+    // 会被随后的 clone 覆盖掉。
+    if (config.remote !== undefined && config.remote !== '' && !existsSync(join(config.mirrorDir, '.git'))) {
+        const ready = await ensureMirrorRepo({
+            dir: config.mirrorDir,
+            url: config.remote,
+            ...config.branch === undefined ? {} : { branch: config.branch },
+            ...config.token === undefined ? {} : { token: config.token },
+        });
+        if (!ready.cloned) {
+            return {
+                files: 0,
+                written: 0,
+                unchanged: 0,
+                removed: 0,
+                tombstones: 0,
+                committed: false,
+                pushed: false,
+                error: `首次同步无法 clone 远端：${ready.error ?? '未知原因'}`,
+                ...ready.kind === undefined ? {} : { errorKind: ready.kind },
+            };
+        }
+    }
+    const files = await collectMirror(memory);
+    const write = writeMirror({ targetDir: config.mirrorDir, files });
+    // 墓碑：用「上次状态」与「本次要写的 id」对比。首次同步没有上次状态 → 不产生墓碑。
+    const previous = readState(config.mirrorDir);
+    const current = stateOfFiles(files);
+    const tombstones = planTombstones({ previous, current, at: now });
+    writeTombstones(config.mirrorDir, tombstones);
+    writeState(config.mirrorDir, dropTombstoned(current, tombstones));
+    const commit = await commitMirror({
+        dir: config.mirrorDir,
+        message: `sync: ${files.length} 条记录${tombstones.length > 0 ? `，${tombstones.length} 条墓碑` : ''}`,
+        author: AUTHOR,
+    });
+    if (config.remote === undefined || config.remote === '') {
+        return {
+            files: files.length,
+            written: write.written,
+            unchanged: write.unchanged,
+            removed: write.removed,
+            tombstones: tombstones.length,
+            committed: commit.committed,
+            ...commit.sha === undefined ? {} : { sha: commit.sha },
+            pushed: false,
+            error: '未配置远端地址（memory.sync.remote）—— 已完成本地提交',
+        };
+    }
+    await ensureRemote(config.mirrorDir, config.remote);
+    const remote = await pushMirror({
+        dir: config.mirrorDir,
+        url: config.remote,
+        ...config.branch === undefined ? {} : { branch: config.branch },
+        ...config.token === undefined ? {} : { token: config.token },
+    });
+    return {
+        files: files.length,
+        written: write.written,
+        unchanged: write.unchanged,
+        removed: write.removed,
+        tombstones: tombstones.length,
+        committed: commit.committed,
+        ...commit.sha === undefined ? {} : { sha: commit.sha },
+        pushed: remote.ok,
+        ...remote.error === undefined ? {} : { error: remote.error },
+        ...remote.kind === undefined ? {} : { errorKind: remote.kind },
+    };
+}
+/** 读镜像目录里的记录文件。 */
+function readIncoming(mirrorDir) {
+    const root = join(mirrorDir, 'records');
+    if (!existsSync(root))
+        return [];
+    const incoming = [];
+    const walk = (dir, segments) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                walk(join(dir, entry.name), [...segments, entry.name]);
+                continue;
+            }
+            if (!entry.name.endsWith('.json'))
+                continue;
+            const id = entry.name.replace(/\.json$/u, '');
+            try {
+                const block = JSON.parse(readFileSync(join(dir, entry.name), 'utf8'));
+                if (segments[0] === 'global')
+                    incoming.push({ id, scope: 'global', block });
+                else if (segments[0] === 'project' && segments.length >= 2) {
+                    incoming.push({ id, scope: 'project', projectName: segments[1] ?? '', block });
+                }
+            }
+            catch {
+                // 坏文件跳过：一条损坏不该挡住整次拉取。
+            }
+        }
+    };
+    walk(root, []);
+    return incoming;
+}
+/**
+ * 拉一次：拉取 → 规划导入 → 逐条落地。
+ *
+ * 冲突不自动裁决：两边版本都写进 `conflicts/`，本地版本保留（§3.3）。
+ *
+ * @param memory - 引擎实例。
+ * @param config - 同步配置。
+ * @param now - 时间注入点。
+ * @returns 导入统计。
+ */
+export async function syncPull(memory, config, now = Date.now()) {
+    if (config.remote !== undefined && config.remote !== '') {
+        // 同 push：首次必须先 clone，否则本地 init 出来的仓库与远端没有共同祖先。
+        if (!existsSync(join(config.mirrorDir, '.git'))) {
+            const ready = await ensureMirrorRepo({
+                dir: config.mirrorDir,
+                url: config.remote,
+                ...config.branch === undefined ? {} : { branch: config.branch },
+                ...config.token === undefined ? {} : { token: config.token },
+            });
+            if (!ready.cloned) {
+                return {
+                    pulled: false,
+                    imported: 0,
+                    conflicts: 0,
+                    orphaned: 0,
+                    error: `首次同步无法 clone 远端：${ready.error ?? '未知原因'}`,
+                    ...ready.kind === undefined ? {} : { errorKind: ready.kind },
+                };
+            }
+        }
+        await ensureRemote(config.mirrorDir, config.remote);
+        const remote = await pullMirror({
+            dir: config.mirrorDir,
+            url: config.remote,
+            ...config.branch === undefined ? {} : { branch: config.branch },
+            ...config.token === undefined ? {} : { token: config.token },
+        });
+        if (!remote.ok) {
+            return {
+                pulled: false,
+                imported: 0,
+                conflicts: 0,
+                orphaned: 0,
+                ...remote.error === undefined ? {} : { error: remote.error },
+                ...remote.kind === undefined ? {} : { errorKind: remote.kind },
+            };
+        }
+    }
+    const incoming = readIncoming(config.mirrorDir);
+    // 本地各层现状
+    const globalRecords = await memory.list({ namespace: 'global' });
+    const localGlobal = { blocks: blocksOfDocument(recordsToDocument(globalRecords)) };
+    const localProjects = {};
+    for (const cwd of memory.projectCwds()) {
+        const name = (cwd.replace(/\\/gu, '/').split('/').pop() ?? '').toLowerCase();
+        if (name === '')
+            continue;
+        const records = await memory.list({ namespace: 'project' }, cwd);
+        localProjects[name] = { blocks: blocksOfDocument(recordsToDocument(records)) };
+    }
+    const plan = planImport({ incoming, localGlobal, localProjects });
+    // 冲突留证：两边都写进 conflicts/
+    if (plan.conflicts.length > 0) {
+        const dir = join(config.mirrorDir, 'conflicts');
+        mkdirSync(dir, { recursive: true });
+        for (const conflict of plan.conflicts) {
+            const env = config.envName ?? 'local';
+            writeFileSync(join(dir, `${conflict.id}.${env}.json`), `${JSON.stringify(conflict, null, 2)}\n`, 'utf8');
+        }
+    }
+    // 逐条落地（唯一会改本地记忆库的一步）
+    let imported = 0;
+    for (const upsert of plan.upserts) {
+        const cwd = upsert.scope === 'project' && upsert.projectName !== undefined
+            ? memory.projectCwds().find(candidate => (candidate.replace(/\\/gu, '/').split('/').pop() ?? '').toLowerCase() === upsert.projectName?.toLowerCase())
+            : undefined;
+        if (upsert.scope === 'project' && cwd === undefined)
+            continue;
+        try {
+            await memory.adopt(upsert.id, upsert.block, cwd);
+            imported += 1;
+        }
+        catch {
+            // 单条失败跳过——一条不合规不该挡住整次拉取。
+        }
+    }
+    return {
+        pulled: true,
+        imported,
+        conflicts: plan.conflicts.length,
+        orphaned: plan.orphaned.length,
+    };
+}
+/**
+ * 查同步状态。
+ *
+ * @param config - 同步配置。
+ * @returns 镜像目录、最近提交、冲突与墓碑数量。
+ */
+export async function syncStatus(config) {
+    const initialized = existsSync(join(config.mirrorDir, '.git'));
+    const history = initialized ? await readHistory(config.mirrorDir) : [];
+    const conflictsDir = join(config.mirrorDir, 'conflicts');
+    const tombstonesDir = join(config.mirrorDir, TOMBSTONE_DIR);
+    const countFiles = (dir) => {
+        if (!existsSync(dir))
+            return 0;
+        return readdirSync(dir).filter(name => name.endsWith('.json')).length;
+    };
+    return {
+        mirrorDir: config.mirrorDir,
+        initialized,
+        ...config.remote === undefined ? {} : { remote: config.remote },
+        ...history[0] === undefined ? {} : { lastCommit: history[0] },
+        commits: history.length,
+        conflicts: countFiles(conflictsDir),
+        tombstones: countFiles(tombstonesDir),
+    };
+}
+/** 便于测试：导出一份当前冲突的快照。 */
+export function conflictFiles(config) {
+    const dir = join(config.mirrorDir, 'conflicts');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).filter(name => name.endsWith('.json'));
+}

package/dist/sync-tombstone.d.ts

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