# 从快照构造、合并和跟踪 JSON0 操作

在任务看板中，两端可以各从一个确定版本开始编辑。以下接口用标准 JSON0 表达编辑结果，可以把生成的操作交给固定版本的 JavaScript JSON0。接口本身由 opgrain 提供。

## 旧值检查与构造

删除卡片时，操作保存即将删除的卡片，用于求逆。对 `{"tasks":["Review","Publish"]}` 执行 `[{"p":["tasks",0],"ld":"Publish"}]` 时，`Engine::apply_verified` 返回 `StalePreimage`，其中包含组件下标、路径、声明的旧值和实际旧值。纯 `oi` 校验属性缺失，`null` 算已存在。列表插入可以使用列表长度作为下标。其他路径、文本及子类型失败带有组件下标和原始错误。

`engine.draft(Some(board))` 创建一个独立的工作副本。每次编辑使用草稿当下的坐标和旧值。`set`、`remove` 编辑对象属性或根，列表使用 `insert_item`、`replace_item`、`remove_item`、`move_item`。数值编辑使用 `add_number`。`splice_text` 接受 UTF-16 起点和删除长度，保存被删文本并写入给定内容，默认生成显式 `text0`。覆盖内置 `text0` 时可以通过 `append` 提交自己构造的操作。

`Draft::append` 先验证整个操作，成功后才更新草稿。`read`、`snapshot` 和 `operation` 可分别读取路径、快照和累计操作。快照、可变 JSON 值与路径均不共享可变容器。

## 快照差量

`engine.diff(before, after)` 从两份快照生成 JSON0 操作，可以创建或删除根，也可以生成空操作。`DiffOptions` 提供以下选项。

| 选项 | 行为 |
| --- | --- |
| `alignment_cells` | 列表和文本共享的最长公共子序列矩阵格数预算，默认 16,384。剩余预算不足时仍保留相同的前后缀，对中段生成较粗的编辑。值小于等于零时关闭中段矩阵。|
| `list_identity_key` | 若两个列表都由具有指定唯一字符串键的对象组成，以该键匹配卡片并生成 `lm`。缺少键、键重复或键的值非字符串时，按值对齐该列表。|
| `text_encoding` | 默认使用 `Text0`，也可选择 `Legacy`。比对和切片均按 UTF-16 代码单元进行。引擎覆盖了内置 `text0` 时，变动的字符串使用普通值替换。|
| `prefer_number_add` | 默认关闭。开启后，仅在增量及其反向计算均能精确得到目标值时，生成 `na`。其余情况生成带旧值的替换。|

为保持输出稳定，对象属性按键排序，列表对齐平局时先推进源序列。唯一键匹配会重新定位卡片，然后递归编辑内容。差量保留旧值和匹配到的公共区段，其组件数可能多于全局最短差量。矩阵预算只限制中段对齐；匹配长列表的唯一键仍可能因移动与查找达到平方量级。

## 批次合并与撤销

`engine.transform_histories(left, right)` 将基于同一起点的两个顺序操作数组交叉转换。每个左侧批次逐次穿过右侧各批次，每次同时更新两侧的对应操作。结果保留两边的批次顺序和空批次。左侧在冲突中沿用 JSON0 的左优先级。

`engine.merge_histories(base, left, right)` 校验两个原始历史和两个转换后的应用方向，只在结果一致时返回快照与转换后的批次。失败包含阶段、分支、批次和组件下标，或包含舍入等原因造成的两份不一致快照。只需改变文本表示时，`Engine::reencode_text` 为内置文本保留顺序和 UTF-16 坐标。合并时指定 `text_encoding=Some(Text0)` 或 `Some(Legacy)` 可以统一两边的表示。

`engine.journal(base)` 创建内存历史，起点版本号为零。`append_all` 先验证整个批次，再为每条操作保存检查点。`operations(start, end)` 取版本区间 `(start, end]` 的操作。`integrate(base_revision, incoming)` 将从旧版本产生的新分支转换到当前版本，已有历史作为左侧。`undo_operation(start, end)` 会用旧检查点验证逆操作确实恢复起点。`revert(start, end)` 进一步将这条逆操作穿过后续编辑，再追加到历史。成功时原版本仍可读，失败时版本不推进。检查点通过不透明快照共享未编辑分支，路径上的容器发生变化时复制。可用 `compact` 保留指定版本及之后的历史，绝对版本号继续递增。句柄生命周期与压缩行为见 [快照与版本管理](snapshots.md)。

自定义子类型应保持引擎注册表稳定，回调应对相同输入给出一致结果。合并与撤销可能重复调用回调，库无法撤销回调造成的外部副作用。

## 跟随路径和 UTF-16 位置

`apply_tracked` 和 `apply_tracked_batches` 在验证并应用操作的同时更新调用方提供的位置。节点路径随列表插入、删除和移动而变化。位置所在的节点或父节点被删除、替换，或被不透明的自定义子类型编辑时，位置失效。`losses()` 按位置输入顺序报告首次失效的批次、组件和原因，两个下标均从零开始。

字符串节点的位置可以是单个 `Cursor` 或具有两个端点的 `TextRange`。插入发生在位置处时，由该端点的 `InsertionAffinity` 决定留在插入内容之前还是之后。被删除片段中的位置收缩到删除起点。如果两个端点收缩后因相反的插入附着方向而交叉，范围收缩到更新后的起点。原始位置必须指向已存在的值，光标和范围端点使用 UTF-16 坐标。

[看板示例](../examples/board/main.mbt) 展示了这条链路：从两份看板推导卡片移动，合并另一端的标题编辑，跟随该标题的光标，最后撤销移动并保留编辑。
