@yandy0725/memory-core 2.0.0 → 2.1.0

package/src/sync/backend.ts

@@ -0,0 +1,220 @@
+/**
+ * 同步的**传输端口**：引擎只认这个接口，不认任何具体存储。
+ *
+ * 端口形状由「以后还要有别的 backend（对象存储之类）」倒推：**不得**出现「本地工作树」
+ * 「clone」「commit」「ref」这类 git 专属概念。原因不是洁癖 —— 第三方 SDK 进不了 core
+ * （core 的源码只许 import 标准库与相对路径，这是一道测试门），所以将来那些 backend 只能是
+ * **独立的包**实现这里导出的端口，再由适配层装配。端口里漏进一个 git 概念，那个包就实现不出来。
+ *
+ * 两条最容易踩的口径：
+ * - `revision` 是**不透明字符串**。引擎把它写回基线、下次原样交回来，从不解析它。
+ * - `list()` 的 hash 恒为 **sha256(文件字节) 的十六进制小写**。这是端口契约的一部分，
+ *   不是实现细节：基线与三方差集都直接与它比较。backend 若原生只有别的标识（git 的 blob
+ *   sha1 掺了 `blob <长度>\0` 头，对象存储的 ETag 掺了分片规则），换算责任在 backend 自己
+ *   身上 —— 换算错了不会报错，只会让「没变」被判成「变了」，每轮同步凭空生出冲突副本。
+ *
+ * 本文件只有类型与一个错误类，**没有运行时代码**：任何逻辑都会把整条同步链绑到某个具体存储上。
+ */
+
+/**
+ * 每次 backend 调用的运行参数。`timeoutMs` 由调用方按「自动路径 / 用户显式在等」两档给。
+ *
+ * 注意它是**这次调用的总预算**，不是「单次远端往返的上限」：一次 `fetch()` 内部就是
+ * `git fetch` + 失败复核的 `ls-remote` + `ls-tree` + `cat-file --batch` 好几个往返，它们**共享**
+ * 这一份预算（实现见 `backend-git.ts` 的 `budgeted()`：每跑一个子进程时现算剩余量）。
+ * 引擎那边同理：一轮同步会在多次 backend 调用（fetch → publish，含一次整轮重跑）之间共享同一份预算，
+ * 交下来的是剩余量。所以谁也不要把它当成「每个子进程/每次请求都能各花这么久」。
+ */
+export interface SyncRunOptions {
+	/** 本次调用的**总预算**：调用内部多次往返共享它。超时按失败处理，绝不无限等（自动路径是挂在会话启动上的）。 */
+	timeoutMs: number;
+	/** 可选的中止信号：宿主退出/切会话时让在途的远端操作尽快收尾。 */
+	signal?: AbortSignal;
+}
+
+/**
+ * 远端内的一个前缀。backend 只在该前缀内活动，因此引擎不必知道远端还放着别的项目。
+ * 前缀恒为 POSIX 形态（`/` 分隔），与宿主平台无关 —— 它是远端仓库里的数据布局，
+ * 跟着平台走会让同一个仓库在两台设备上算出两个目录、各同步各的。
+ */
+export interface SyncScope {
+	readonly prefix: string;
+}
+
+/** 远端一次快照的只读视图。 */
+export interface RemoteView {
+	/**
+	 * 这次快照的**不透明**标识，会被写回基线的 `revision`。空串表示远端还没有任何已同步的
+	 * 内容（第一次同步之前），即「没有基线可比」。
+	 */
+	readonly revision: string;
+
+	/**
+	 * 远端在 `scope.prefix` 下的全部路径 + 内容 hash。
+	 *
+	 * **路径相对于 `scope.prefix`**（因此就是单层文件名），与引擎差集用的 key 同域。
+	 * **hash 恒为 sha256(字节) 的十六进制小写** —— 换算责任在 backend，见文件头。
+	 */
+	list(): Promise<Array<{ path: string; hash: string }>>;
+
+	/**
+	 * 取内容。只会被 `list()` 报出的路径调用。
+	 *
+	 * **可能在根锁释放之后才被调用**：引擎只在真要落到本地时才读内容，那时这一轮已经不在
+	 * `fetch`/`publish` 的串行段里了（下面 `SyncBackend` 那条并发假设只盖住这两个调用）。
+	 * 所以这里读的必须是 `fetch` 那一刻就已经固定下来的快照（内容已缓存，或按当时那个
+	 * revision 取对象），**不能**对着共享的传输状态现取 —— 另一个项目的 `fetch`/`publish`
+	 * 会同时跑：前者会移动引用（`git fetch` 改掉 `FETCH_HEAD` 与远程跟踪分支），后者会把
+	 * 工作树 `reset --hard` + `clean -fd`。把 `read()` 写成对着共享暂存 clone 现跑一次
+	 * `git show`、或直接读暂存工作树，读到的就可能是别的项目的内容、更旧的内容，或直接报错。
+	 */
+	read(path: string): Promise<string>;
+
+	/**
+	 * 远端存在、但**不该在那儿**的路径（**远端根相对**，原样保留）。纯报告用：引擎把它抄进
+	 * 同步结果与状态报告，让人知道远端有内容没被同步 —— 有人手工推上来的索引文件、
+	 * 同步范围之外的目录（例如那些永不参与同步的本地状态）、或本前缀底下的嵌套目录都算。
+	 *
+	 * **判据是「异常」，不是「不在本 scope 内」**：远端仓库按设计镜像整个记忆根，而一次会话只
+	 * 同步当前那一个项目，所以**别的项目的记忆是常态**，不属于这里。把它们报出来，条数就随
+	 * 项目数 × 记忆数线性增长，而异常报告一旦和正常数据同量级就等于没有报告 —— 真正那一条信号
+	 * 会被永久埋掉。
+	 *
+	 * **不得静默丢弃异常路径**：丢了用户就永远无从得知远端有内容没进同步。
+	 * 无法廉价判断的 backend 返回 `[]`。
+	 */
+	readonly outOfScope: string[];
+}
+
+/**
+ * 一次初始化的结果。
+ *
+ * `revision` 是远端**真的存在**的那一个（空串 = 远端还没有任何已同步内容）：适配层拿它写首份基线
+ * （`emptyManifest(syncTransport(actualOrigin, branch))` + 这个 revision，`files` 为空集）。不得让适配层自己再 `fetch()` 一遍拼：
+ * 那一来多一次远端往返，二来两次读之间远端可能已经前进，写进基线的就是一个对不上的版本。
+ *
+ * `warnings` 是「已经发生、但不足以拒绝初始化」的情形（例如用户自己把记忆根做成了指向别处的
+ * 仓库），逐条可读、不带凭据，由适配层排进非致命提示。
+ */
+export interface SyncInitResult {
+	revision: string;
+	warnings: string[];
+}
+
+/**
+ * 要发布的**增量**：从 `base`（= 本轮取到的远端那一侧）到合并结果的差异。
+ *
+ * 用增量而不是完整文件集：对象存储这类 backend 只需 PUT/DELETE 变化的对象，不必重传全量。
+ * 增量由引擎算好再交下来 —— backend 不判断该写什么，只负责把这份差异变成远端的新状态。
+ *
+ * `path` 与 `list()` 报出的同域：相对于 `scope.prefix` 的**单层**文件名（不含目录）。
+ * 记忆目录是扁平的，嵌套路径写上去就再也读不回来（下一轮会被归成范围外）。
+ */
+export interface SyncPublishChanges {
+	writes: Array<{ path: string; content: string }>;
+	deletions: string[];
+}
+
+/**
+ * 远端已经不在 `base` 上了（另一台设备在这轮之间推过）。
+ *
+ * 这是**预期内**的失败，不是故障：引擎拿到它就把整轮重跑一次（重新取远端、重算差集），
+ * 仍失败则本轮放弃、基线不前进，留到下次。所以它必须是一个可识别的类型，
+ * 而不是一条只能靠读文案区分的普通错误。
+ */
+export class NonFastForwardError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NonFastForwardError";
+	}
+}
+
+/**
+ * 一个传输后端。实现方只需满足本接口的方法语义，不必也不得假定调用方认识具体存储。
+ *
+ * **并发假设**：backend 可以假定调用方已经把同一份本地状态（同一个 `syncRoot`）上的调用
+ * **串行化**了，但**不是**「一轮从头到尾持有一把锁」。真实形状是引擎把一轮切成三段，每段的锁不同（见设计文档）：
+ *
+ * 1. `ready()`：在根级 sync 锁**之外**被调用（引擎每轮进门先问一次）。`init()` 由适配层触发，
+ *    **引擎自己绝不会调它**；git 实现会在唯一 staging 中初始化，并经同一路径的有界 `withLock`
+ *    串行后原子发布。`setRemote()` 也使用这把管理锁，但两者都不得在引擎 fetch/publish 锁内嵌套调用。
+ *    自动轮遇到未初始化只报一句可读原因，初始化是适配层的事。
+ * 2. `fetch()`：**在根级 sync 锁内**跑（try 语义：拿不到就本轮直接跳过，绝不把传输放进锁外），
+ *    并与 `getRemote()` 同锁取得快照的 transport 身份。
+ *    这一段要读本地文件算基线，而「一次 save 期间没有别的 save」这条不变量正是那把根锁守的。
+ * 3. 落盘合并：**根锁已经放开**，只由本 scope 的逻辑锁（`sync:<scope>`）守着。
+ * 4. `publish()`：**重新抢一次根级 sync 锁**（同样抢不到就本轮报「忙」）。
+ *
+ * 于是 `fetch` 返回的远端视图与落盘之间，本地磁盘**可能被别的写入者改过**：backend 不得跨这道
+ * 边界缓存本地状态；引擎这边则会在发布前重新核对基线，远端已经前进了就抛
+ * {@link NonFastForwardError} 让整轮重跑，而不是硬推。
+ *
+ * 同一次调用内部（一次 `fetch` 或一次 `publish`）是顺序的、且共享那一份 `timeoutMs` 预算。
+ * 因此以独立包实现的 backend **不必**自己再加内部锁；反过来，端口也不承诺任何并发安全，
+ * 直接并行调用同一个实例属于误用。
+ */
+export interface SyncBackend {
+	/**
+	 * 是否已初始化（本地那点状态在不在）。false 时引擎的自动轮直接跳过并报一句可读原因 ——
+	 * **引擎自己不初始化**（首次 clone 可能要几十秒，挂在会话启动上的它必须有独立预算）。
+	 * 初始化由适配层在会话启动时按配置调用 {@link init}；它抛出的失败由适配层降级成一条提示，
+	 * 不影响其余记忆功能。`ready()` 的判据是本地那份传输状态在不在（git: `<syncRoot>/repo/.git`），
+	 * **不得**改成“设备身份在不在”：两者不同时写成（clone 成功之后才写设备身份），
+	 * 拿后者当判据会把“clone 好了、身份写失败”误报成“没初始化”，从而重做一次初始化。
+	 */
+	ready(): Promise<boolean>;
+
+	/**
+	 * 首次初始化：由适配层在启动时按配置触发（显式 pull/push 的恢复路径也可以再调），但不是一条
+	 * 用户要手工输入的命令。失败要抛错让人看见，不静默降级成「没初始化」。幂等：已初始化时不得
+	 * 重做一次会改变远端历史的初始化；已初始化时只复核当前 origin。适配层在 ready 且 manifest
+	 * transport 匹配的快路径上不会再调它，因此这份复核不会成为每次启动的固定远端往返。
+	 *
+	 * 返回远端真的存在的那个 revision 与非致命警告（见 {@link SyncInitResult}）。
+	 * **拒绝初始化时不得留下任何可被认成「已初始化」的产物**：否则 `ready()` 随即变 true，
+	 * 下一次启动会照着那个状态继续同步，拒绝分支就成了假话。
+	 */
+	init(opts: SyncRunOptions): Promise<SyncInitResult>;
+
+	/**
+	 * 本地那份传输状态记录的远端地址（git: 暂存 clone 的 origin）。未初始化或没有 origin 时为
+	 * `null`；其他读取失败（权限、仓库损坏、子进程错误）一律抛错，绝不把「读不出来」伪装成「没配置」。
+	 *
+	 * 它是初始化之后「同步到底去哪儿」的**真相来源**：状态报告里那一行必须来自这里，而不是构造时的
+	 * 配置值（配置里的 remote 只是未初始化时的输入，已初始化后留空也合法）。
+	 */
+	getRemote(): Promise<string | null>;
+
+	/**
+	 * 改本地那份传输状态指向的远端（git: `remote set-url`），**不对远端发任何写操作**。
+	 *
+	 * 已初始化时用（适配层的「换远端」入口走这里）；未初始化时它什么都不改也不报错 ——
+	 * 那时该改的是配置，而本功能不写用户的配置文件。
+	 * 空地址 fail-closed（抛错，origin 原样不动）；错误里的地址必须经凭据脱敏。
+	 */
+	setRemote(remote: string, opts: SyncRunOptions): Promise<void>;
+
+	/** 取远端最新状态。 */
+	fetch(scope: SyncScope, opts: SyncRunOptions): Promise<RemoteView>;
+
+	/**
+	 * 把「从 `base` 到合并结果」的增量发布到远端，返回新的 revision。
+	 *
+	 * 端口不承诺原子，但要求 backend **要么整体成功、要么抛错且不留下半推状态**：
+	 * 抛错之后远端内容与本地状态都原样可解释，引擎才敢下一轮重来。
+	 * `base.revision` 用于乐观并发：远端已经不在 base 上时抛 {@link NonFastForwardError}。
+	 * `base.remote` 若存在，是 fetch 同一把根锁内读到的实际 origin；backend 必须在任何远端 mutation 前
+	 * 复核它，不同则抛 {@link NonFastForwardError}，防止旧进程的 delta 写进新 origin。
+	 * 空串的 base 表示「没有基线」（首次发布），**不算**非快进。
+	 *
+	 * 返回的 revision **必须是远端真的有的那一个**：引擎会原样写进基线，下一轮拿它当 base 比对。
+	 * 返回一个只存在于本地状态的标识（例如「本轮无变化，就把本地 head 交上去」而远端根本没这个分支），
+	 * 会让下一轮的 base 永远对不上远端 —— 看起来只是多一次重跑，实际上是每轮都白跑。
+	 */
+	publish(
+		scope: SyncScope,
+		changes: SyncPublishChanges,
+		base: { revision: string; remote?: string },
+		opts: SyncRunOptions & { message: string; author: { name: string; email: string } },
+	): Promise<string>;
+}

package/src/sync/conflict.ts

@@ -0,0 +1,247 @@
+import { parseEntryFile, serializeEntryFile } from "../store/entry-file.js";
+import { ENTRY_EXT, entryFileName } from "../store/filename.js";
+import { sha256Hex } from "./hash.js";
+import type { SyncFileInfo } from "./types.js";
+
+/**
+ * 冲突收敛：同一个 entry 文件在两侧内容不同时，决定「谁留在原路径、谁另存为新 entry」。
+ *
+ * 策略是**两份都留**：`modified` 新的一方留在原路径（逐字写入），被挤出来的那一份成为一条新记忆，
+ * `name` 带上由它自己的内容派生的后缀，后续的合并交给整理流程（它的既有职责就是合并重复、解决矛盾）。
+ * 「删除 vs 修改」是同一套规则的另一半：删除照办（原路径要删），幸存的那份内容按新 entry 留下 ——
+ * 没有任何一方丢内容，删除的意图也被执行。
+ *
+ * **载重不变量：产物只能是冲突内容的函数。** 两台设备各自解同一次冲突（一台在拉、另一台也在拉），
+ * 必须算出逐字节相同的新文件名与字节。一旦后缀里掺进本地状态 —— hostname、设备 id、当天日期、
+ * 或者目录里恰好有什么 —— 两台设备就各造一份副本，下一轮互相把对方的副本拉过来，
+ * 用户的同一条记忆变成三份、四份，永不收敛。因此这里：
+ * - 不用时钟（`modified` 非法时退回**常量**，不退回今天）；
+ * - 不用主机与设备信息；
+ * - 不用 `resolveUniqueFileName` —— 它的 `-2`/`-3` 取决于本地目录里恰好有什么，
+ *   撞名时改追加**这份内容自己的** sha256 指纹，仍然是内容的函数。
+ *
+ * 纯函数、零 IO：字节由调用方读、文件由调用方写，这里只决定「写什么、写到哪个名字」。
+ */
+
+/** 冲突的一侧：字节 + 它的指纹。`null` = 这一侧已删除（来自 `SyncConflict` 的同一套表示）。两侧不会同时为 null。 */
+export interface ConflictSide {
+	/** 这一侧此刻的完整字节（逐字：行尾与空白都算内容）。 */
+	raw: string;
+	/** 同一份内容的指纹（扫描与清单的口径）。 */
+	info: SyncFileInfo;
+}
+
+/** 一次要收敛的冲突。形状与差集给出的 `SyncConflict` 对齐，只是两侧各自带上了字节。 */
+export interface ConflictInput {
+	/** 冲突所在的 entry 文件名（原路径）。派生名字**不**来自它 —— 只用于报错时指明是哪一条。 */
+	file: string;
+	/** `null` = 本地这一侧已删除。 */
+	ours: ConflictSide | null;
+	/** `null` = 远端这一侧已删除。 */
+	theirs: ConflictSide | null;
+}
+
+export interface ConflictOutcome {
+	/**
+	 * 原路径要写的字节（逐字，不重新序列化）；
+	 * **`null` = 原路径要被删除** —— 删除 vs 修改时删除照办，幸存的那份内容改由 loserEntry 承接。
+	 */
+	winnerRaw: string | null;
+	/**
+	 * 需要另存为新 entry 的那一份（名字已加内容派生的后缀）；
+	 * `null` = 没有需要另存的一方（删除 vs 修改时，被删的那一侧没有内容要留）。
+	 */
+	loserEntry: { name: string; file: string; raw: string } | null;
+}
+
+/** 另存为新 entry 的那一份（`ConflictOutcome.loserEntry` 的非 null 形态）。 */
+type NewEntry = NonNullable<ConflictOutcome["loserEntry"]>;
+
+/** `modified` 取不出日期时用的**常量**。绝不用今天：今天会让两台设备在不同日子算出不同后缀。 */
+const UNKNOWN_DATE = "unknown-date";
+
+/** 后缀与派生文件名里都用 sha256 的前 6 位当内容指纹。 */
+const FINGERPRINT_LENGTH = 6;
+
+/** `modified` 的前 10 字符要正好是 `YYYY-MM-DD` 才算日期。 */
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** 一份内容的「日期 + 指纹」。后缀与派生文件名都由它拼出来，两处同源、不会漂移。 */
+interface ContentStamp {
+	/** `YYYY-MM-DD`，或常量 `unknown-date`。 */
+	date: string;
+	/** 这份内容 sha256 的前 6 位（小写十六进制）。 */
+	fingerprint: string;
+	/** ` (冲突 <date> <fingerprint>)` —— 逐字，是用户看得见的契约。 */
+	suffix: string;
+}
+
+function stampOf(raw: string): ContentStamp {
+	// 解析不出 frontmatter 也要给出确定答案（常量日期），不抛：后缀是内容的函数，坏内容也有坏内容的后缀。
+	const modified = parseEntryFile(raw)?.meta.modified ?? "";
+	const head = modified.slice(0, 10);
+	const date = DATE_RE.test(head) ? head : UNKNOWN_DATE;
+	const fingerprint = sha256Hex(raw).slice(0, FINGERPRINT_LENGTH);
+	return { date, fingerprint, suffix: ` (冲突 ${date} ${fingerprint})` };
+}
+
+/**
+ * 冲突副本 `name` 的后缀：`" (冲突 " + 该份内容 modified 的日期 + " " + 该份内容 sha256 前 6 位 + ")"`。
+ *
+ * 两个成分都只来自**这一份字节**，所以两台设备各自解同一次冲突会得到同一个后缀、同一个派生文件名，
+ * 下一轮就是「两边都新增了同一个路径、内容相同」→ 收敛成一份，而不是越同步越多。
+ */
+export function conflictSuffix(raw: string): string {
+	return stampOf(raw).suffix;
+}
+
+/** 派生出的文件名是否仍以指纹结尾（= 指纹没被 `entryFileName` 的 stem 截断吃掉）。 */
+function keepsFingerprint(file: string, fingerprint: string): boolean {
+	return file.endsWith(ENTRY_EXT) && file.slice(0, -ENTRY_EXT.length).endsWith(fingerprint);
+}
+
+/**
+ * 由「主干 + 指纹」派生 entry 文件名，并保证**指纹留在末尾**。
+ *
+ * `entryFileName` 的截断只保留前缀（100 字节上限），所以指纹若留在主干中间，长名字会把它整段切掉 ——
+ * 而指纹正是「同名不同内容」时唯一的区分位，切掉它等于让两份不同的记忆抢同一个文件名。
+ * 做法：指纹永远拼在主干之后，主干被截断时就从末尾逐个码点回退，直到派生结果重新以指纹结尾。
+ *
+ * 回退用二分找起点（超长 name 上逐码点回退会退化成平方级）。二分的前提是 `fits` 对 `keep` 单调
+ * （能放下的前缀越短越宽松），而它确实单调：**`build(keep)` 的字节长度对 `keep` 单调不减** ——
+ * 多保留一个码点只可能让它更长（空白连写归一会让长度不变，绝不会变短），而 `entryFileName` 截断时
+ * 保留的是**前缀**，所以「截断完还是不是以指纹结尾」只取决于 `build(keep)` 有没有超过上限。
+ * 二分只依赖入参，因此是确定性的。
+ */
+function fileNameEndingWith(head: string, fingerprint: string): string {
+	const points = Array.from(head);
+	const build = (keep: number): string => entryFileName(`${points.slice(0, keep).join("")}-${fingerprint}`);
+	const fits = (keep: number): boolean => keepsFingerprint(build(keep), fingerprint);
+
+	if (fits(points.length)) return build(points.length); // 常见路径：没被截断，一次就够
+
+	let low = 0; // 空主干必然放得下 `-<指纹>`（7 字节）
+	let high = points.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (fits(mid)) low = mid;
+		else high = mid - 1;
+	}
+	// `low` 就是「仍能放下指纹」的最长前缀：它只在 `fits(mid)` 为真时前移，起点 0 恒真
+	// （空主干派生成 `-<指纹>`，7 字节，不可能被截断）。
+	return build(low);
+}
+
+/** 已占用文件名的索引：名字 → 该文件内容的 hash（`undefined` = 调用方不知道 hash）。 */
+function indexOfTaken(
+	takenFileNames: Iterable<string | { file: string; hash?: string }>,
+): Map<string, { hash?: string }> {
+	const index = new Map<string, { hash?: string }>();
+	for (const item of takenFileNames) {
+		const file = typeof item === "string" ? item : item.file;
+		const hash = typeof item === "string" ? undefined : item.hash;
+		const known = index.get(file);
+		// 同名重复时留下「知道 hash」的那条：hash 未知的条目给不出任何判断力。
+		if (known === undefined || (known.hash === undefined && hash !== undefined)) index.set(file, { hash });
+	}
+	return index;
+}
+
+/**
+ * 派生冲突副本的文件名。
+ *
+ * 与 `name` 同源，但把后缀里的指纹**挪到末尾**（右括号提前）：`A (冲突 2026-11-09 abc123)` 派生出
+ * `A-(冲突-2026-11-09)-abc123.md`。这样既保住了「文件名以指纹结尾」（截断时指纹才活得下来），
+ * 也让「这个名字被别的字节占用了」有一个确定性的退路：再追加一次同一份内容的指纹。
+ *
+ * 占用判断只按**逐字文件名**，刻意不做大小写/规范化折叠：折叠要跟 `platform`（本地配置），
+ * 引进来就等于让派生名字依赖本地状态。折叠碰撞由写入口的碰撞跳过兜底。
+ */
+function pickFileName(
+	name: string,
+	stamp: ContentStamp,
+	newRaw: string,
+	taken: Map<string, { hash?: string }>,
+): string {
+	const head = `${name} (冲突 ${stamp.date})`;
+	const base = fileNameEndingWith(head, stamp.fingerprint);
+	const occupant = taken.get(base);
+	// 没被占用 → 直接用。
+	if (occupant === undefined) return base;
+	// 被占用，且占用者的字节与「我们即将写下去的那份」逐字相同 → 复用（幂等）。
+	// 比的是新 entry 的字节而不是败者的原字节：副本的 name 已加后缀，两者 hash 必然不同，
+	// 拿原字节去比会让每一轮重解都再追加一次指纹 —— 副本越同步越多，正是不收敛的那个形状。
+	if (occupant.hash !== undefined && occupant.hash === sha256Hex(newRaw)) return base;
+	// 被不同内容占用，或 hash 未知（证明不了是同一份）→ 追加指纹，绝不写穿别人的文件。
+	// 这里不用 `resolveUniqueFileName`：`-2`/`-3` 取决于本地目录里恰好有什么，两台设备会算出不同名字。
+	return fileNameEndingWith(`${head}-${stamp.fingerprint}`, stamp.fingerprint);
+}
+
+/**
+ * 把一份内容另存为新 entry：`name` 加内容派生的后缀，其余 frontmatter 与正文原样保留。
+ *
+ * 新 entry 由我们**作者化**（重新序列化），所以字节是规范化的；胜者那一份仍然逐字过去 —— 它是别人
+ * 写的文件，重新序列化等于把行尾与空白按我们的口味改掉，会让对端下一轮又判成「变了」。
+ *
+ * 解析不出 frontmatter 时抛错而不是返回 null：null 在这套接口里的意思是「无事可做」，
+ * 用它表示「做不到」会让调用方静默丢掉这一份内容 —— 那是本设计明令要防的丢记忆形状。
+ * 抛出去之后由调用方把本轮变成失败/跳过（fail-closed），内容一份都不少。
+ */
+function keepAsNewEntry(side: ConflictSide, file: string, taken: Map<string, { hash?: string }>): NewEntry {
+	const parsed = parseEntryFile(side.raw);
+	if (!parsed) {
+		throw new Error(`Cannot keep "${file}" as a new entry: unparsable frontmatter in the losing side`);
+	}
+	const stamp = stampOf(side.raw);
+	const name = `${parsed.meta.name}${stamp.suffix}`;
+	const raw = serializeEntryFile({ ...parsed.meta, name }, parsed.body);
+	return { name, file: pickFileName(parsed.meta.name, stamp, raw, taken), raw };
+}
+
+/**
+ * 谁留在原路径：`modified` 新的一方胜；`modified` 相同则 sha256 字典序大的一方胜。
+ *
+ * 两个判据都只依赖内容（字符串比较，不是 locale 序、不是解析成日期再比），所以两台设备独立算出
+ * 同一个胜者 —— 幂等，与谁先推、谁在拉无关。`modified` 是垃圾值时同样确定：比较退化成码点序，
+ * 仍然是「同一份输入 → 同一个胜者」。
+ */
+function pickWinner(ours: ConflictSide, theirs: ConflictSide): ConflictSide {
+	if (ours.info.modified === theirs.info.modified) return ours.info.hash > theirs.info.hash ? ours : theirs;
+	return ours.info.modified > theirs.info.modified ? ours : theirs;
+}
+
+/**
+ * 收敛一次冲突，得到「原路径写什么」与「哪一份另存为新 entry」。
+ *
+ * 返回 `null` 只有一个意思：**无事可做**（两侧字节相同，或两侧都已删除 —— 差集不会送来这两种，
+ * 但调用方送来了也不该抛）。做不到（败者的字节解析不出）时抛错，不借用 null。
+ *
+ * `takenFileNames` 是调用方已知的占用清单，只用于「派生名是否已被同一份内容占用」这一个判断：
+ * 带 hash 才可能复用，只给名字视为 hash 未知、一律走确定性追加。传空数组即可得到「与本地状态完全无关」
+ * 的产物 —— 两台设备各自算出的名字之所以能相同，靠的正是这一点。
+ */
+export function resolveConflict(
+	input: ConflictInput,
+	takenFileNames: Iterable<string | { file: string; hash?: string }>,
+): ConflictOutcome | null {
+	const { ours, theirs } = input;
+
+	const taken = indexOfTaken(takenFileNames);
+
+	// 一、至少一侧已删除。两侧都删 = 无事可做（差集不会送来，但送来也不该抛）；
+	//     一侧删 = 删除照办（原路径要删 → winnerRaw = null），幸存的那份内容另存为新 entry。
+	//     被删的那一侧没有内容可留，所以这里不会出现「两份都留」。
+	if (!ours || !theirs) {
+		const survivor = ours ?? theirs;
+		if (!survivor) return null;
+		return { winnerRaw: null, loserEntry: keepAsNewEntry(survivor, input.file, taken) };
+	}
+
+	// 二、两侧内容相同：不是冲突。判据与差集同源（hash）；raw 逐字相同是它的充分条件，一并认下来。
+	if (ours.info.hash === theirs.info.hash || ours.raw === theirs.raw) return null;
+
+	// 三、改 vs 改：胜者逐字留在原路径，败者另存为新 entry。
+	const winner = pickWinner(ours, theirs);
+	const loser = winner === ours ? theirs : ours;
+	return { winnerRaw: winner.raw, loserEntry: keepAsNewEntry(loser, input.file, taken) };
+}