在理想状态下，CRDT 保证了所有副本的强最终一致性。但在现实当中，数据一致性并不等同于数据有效性。

这句话要怎么理解呢：

• 一致性：所有客户端最终都看到了相同的状态（比如都看到了 ID 为 A 的单元格存在于 Map 中但不在 Order 中）。
• 有效性：这个状态在业务逻辑上是合法的（单元格如果存在，就必须在 Order 中有一席之地，否则它就是孤儿单元格）。

我在设计 Notebook 的时候额外引入了一套完整的体系，包含 Reconciliation、Validation 以及 Auto-Stale 机制。我们的目标是构建一个这样的系统：不仅能容忍错误，还能主动发现并修复错误。

TL;DR;

• 通过 Reconciliation，我们针对实际环境下的不确定性，构建了自动纠错机制来应对熵增。
• 通过 Auto-Stale，我们将业务逻辑中的因果关系（代码变动 -> 结果失效）下沉到底层数据结构的响应机制中，实现了逻辑的自动化与去中心化。

Reconciliation 机制

即使算法（CRDT）是完美的，环境（网络、存储、并发）也是不完美的。

Y.js 的算法保证了在所有操作最终送达时，文档状态是数学上收敛的。但在现实中，我们面临着更复杂的情况：

• 部分更新（Partial Updates）：网络中断可能导致某些 Update 块丢失或乱序。
• 逻辑漏洞（Logical Gaps）：旧版本的客户端可能写入了新版本不兼容的数据结构。
• 并发竞态（Race Conditions）：极端的并发操作可能让应用层逻辑（而非 CRDT 层）陷入不一致状态。

这就导致了系统的“熵增”：随着时间推移，数据结构逐渐变得无序、冗余或逻辑不自洽。为了对抗这种熵增，我们需要一种主动的、确定性的收敛机制，这就是 Reconciliation。

Source of Truth

我们的 Schema 采用了 Map+Order 的分离设计，如果你不太清楚我的 Schema 设计，你可以看我之前的推文：

在这种二元结构中，Reconciliation 的首要哲学是：确定事实。

• Source of Truth（事实）：NB_CELL_MAP。这是数据的物理存储，只要 Map 里有数据，它就客观存在。
• View（视图）：NB_CELL_ORDER。这只是对数据的一种排列方式。

当两者发生冲突——例如 Map 里有单元格 C，但 Order 里没有——Reconciliation 的判定逻辑非常明确：信任事实，修正视图。

因为视图只是数据的投影，视图错了可以重建，但数据丢了就永远丢了。因此，Reconciliation 的核心行为是将 Map 中的“孤儿数据”重新投影到 Order 中，而不是因为 Order 里没有就反向删除 Map 里的数据。

幂等性（Idempotency）与收敛方向

需要注意的是，Reconciliation 必须是一个幂等函数

无论我们在什么时候运行它——文档加载时、迁移后、甚至每次变更后——它都应该产生相同的结果，且不会产生副作用的叠加。

• 收敛方向：将文档状态从“非法”推向“合法”。
• 无副作用：如果文档已经是合法的（Map 和 Order 一一对应），Reconciliation 应该什么都不做（No-op），不产生任何新的 Y.js 事务。

这种特性使得我们可以放心地在系统的各个生命周期节点（Bootstrap, Migration, Runtime）挂载这个机制，将其作为一种常驻的免疫系统，而不是一次性的修复脚本。

Principle of Least Surprise

当系统自动修复数据时，最危险的事情是“自作聪明”。

场景：用户 A 删除了单元格 C，但由于网络问题，删除操作只成功了一半（移除了 Order，没来得及打墓碑标记）。Reconciliation 发现了这个处于“中间态”的 C（在 Map 中，不在 Order 中，没墓碑）。

• 激进策略：认为这是未完成的删除，帮用户删掉 Map 里的 C。
  • 风险：如果这其实是用户 B 刚创建但还没来得及插入 Order 的新单元格呢？由于误判，用户 B 的数据被系统删除了。
• 保守策略（我们的选择）：认为这是意外丢失的显示，帮用户把 C 找回来，追加到文档末尾。
  • 结果：用户 A 可能会看到一个本该删除的单元格“复活”了。这虽然令人困惑，但只是体验问题，不是数据事故。用户可以再次点击删除。

我们选择保守策略，遵循“宁可复活僵尸，不可错杀活人”的原则。在自动化处理当中，保护用户数据的安全性永远高于维持 UI 的整洁性。

工程实现：Origin 隔离

Reconciliation 的操作本质上是系统行为，而非用户行为。因此，我们严格使用 MAINT_ORIGIN 来执行所有修复操作。

这意味着：

1. 不污染撤销栈：用户按 Ctrl+Z 时，不会意外地“撤销”系统的修复操作，导致文档退回到非法状态。
2. 不触发用户侧副作用：其他协同端的 UndoManager 也会忽略这些变更。

自动化维护：Auto-Stale 机制

Notebook 的核心价值在于代码与执行结果的对应关系。如果用户修改了代码，旧的执行结果就失去了意义，甚至会误导用户。这种关系称为因果一致性（Causal Consistency）。

在传统的服务端架构中，这通常由后端状态机管理。但在我们的协同架构中，没有中心服务器来时刻监控状态。我们需要在客户端实现一套维护机制。

观察者模式

我们实现了 enableAutoStaleOnSource 机制，这是一个基于 Y.js 细粒度观察者的自动化系统。

1. 细粒度监听：我们直接监听 Y.Text 对象的变更事件，而不是监听整个 Map。这意味着无论用户是在打字、粘贴还是通过协同接收了远程修改，事件都会被精确捕获。
2. 副作用隔离：markCellOutputStale 操作使用 EXECUTION_ORIGIN。这意味着当系统自动将结果标记为“过期（Stale）”时，这一操作不会进入用户的撤销栈。用户撤销代码修改时，不会意外地把“过期标记”撤销掉。
3. 生命周期管理：该机制被封装在一个 MaintenanceCoordinator 中，随组件挂载启动，随组件卸载销毁，杜绝内存泄漏。

防御性编程：Validation Layer

除了自动修复，我们还引入了被动校验机制。validateNotebook 函数定义了一套严格的数据完整性规则：

• 引用完整性：Order 中的 ID 必须在 Map 中存在。
• 类型安全：Output 中的 running 必须是布尔值，result 必须符合 Schema。
• 逻辑一致性：如果有 runId，则必须有 startedAt。

• 开发阶段：作为 Debug 工具，快速定位 Schema 变更引入的 Bug。
• 迁移阶段：在执行版本迁移（Migration）前后运行，确保迁移脚本没有破坏数据。
• 运行时：配合埋点系统，抽样上报线上文档的健康度。

这套数据治理体系，使得 Notebook 不再是一个脆弱的数据容器，而是一个能够自我维持、自我修复的有机体。它能够从混乱的分布式编辑中，始终收敛到一个有序、合法且符合业务逻辑的状态。