# MoonCDC 运行自查与修复记录（2026-11-07）

本轮在 0.2.0 基线上复跑验证，并使用独立 SQLite 连接、并发进程及异常输入检查未覆盖的边界；首轮修复版本为 **0.3.0**，后续交叉检查的补丁版本为 **0.3.1**。

| 已复现问题 | 处理结果 |
| --- | --- |
| 过滤目标漏传计划时可能先补齐源端确认 | 普通同步在任何确认前拒绝过滤目标，正确传入计划后可恢复 |
| 无穷值写入后生成不可消费事件，阻塞后续日志 | 捕获触发器以 ABORT 拒绝整条写语句，数据和日志均回滚 |
| 后加业务触发器可能使 UPDATE 事件先于 INSERT | 拒绝源表的其他触发器，检测新增触发器并阻止受影响写入 |
| 非法 UTF-8 TEXT 被底层绑定转码，快照和审计漏报 | 先读取原始 UTF-8 字节再严格解码；异常会失败且不登记/推进消费者 |
| 合法 TEXT 开头的 BOM 在 UTF-16 绑定时被 SQLite 剥除 | 参数以 UTF-8 BLOB 绑定并在对应参数位置 CAST 为 TEXT，值不插入 SQL 文本 |
| 负零在部分列类型仍保留，但捕获无法识别其符号 | 将数据库零规范化契约写明并统一快照与事件；核心 wire 仍保留符号 |
| CLI/诊断只显示错误类型，缺少实际原因 | 输出捕获、参数、SQLite 约束和编码错误的具体消息 |
| 直接构造的过滤对象可以绕过序列化预算 | 编码也限制深度和宽度，并拒绝递归引用形成的循环 |

## 验证方式

0.3.0 本地验证结果：原生后端 **41/41**，JavaScript 与 wasm-gc 各 **14/14** 通过；原生构建、原有集成测试、5,134 样本 REAL 回归及 200 次提交并发测试均通过。有效生产 MoonBit 代码为 **4,547 行**，统计口径见仓库脚本；这些结果不等同于赛事官方验收结论。

- `python scripts/verify.py`：格式、编译、native/JS/wasm-gc 适用测试、API 生成差异、代码统计及独立进程验证。
- `scripts/real_regression.py`：5,134 个有限 REAL 样本的非零位模式与实际数据库值比较；正负零的数据库规范化另有独立回归。
- `scripts/concurrency_regression.py`：200 次外部提交、两个共享消费者的同步任务和并发清理；核对全部最终行、类型、源/目标/确认游标、日志连续性及审计。
- 新增回归验证非法 UTF-8、BOM/NUL/emoji、负零、非有限数整句回滚、额外触发器、漏传计划及旧捕获升级的幂等性和状态保持。
- 畸形 JSONL 的头尾、计数、顺序、游标、行宽及非法值，以及深嵌套 JSON，均要求在目标数据和游标变化前拒绝。

## 升级与适用边界

0.3.0 支持在维护窗口对完整的 0.2.0 捕获执行 `upgrade-capture`，验证后原子替换已知触发器，不重置日志或消费者。未知定义、结构漂移、编码不符及不可解码的历史事件会拒绝升级；该命令不修复历史数据损坏。

数据库捕获支持 UTF-8 数据库和有效 Unicode TEXT，任意字节应使用 BLOB。SQLite 零按规范化后的数值语义处理；要求保留零符号的应用应使用显式二进制表示。源表的其他业务触发器不在支持范围，不能通过删除触发器来忽略其业务含义。完整步骤见 [使用手册](OPERATIONS.md)。

## 针对 0.3.0 的交叉检查

0.3.1 本地验证：原生后端 **47/47**，JavaScript 与 wasm-gc 各 **14/14**，同一全量验证脚本内的原生构建、集成、REAL 逐位回归和并发测试通过；有效生产 MoonBit 代码 **4,552 行**。

- 文本参数内部 CAST 会赋予表达式 TEXT affinity，导致 `1 = ?` 在绑定文本 `"1"` 时从假变真，可能误更新数据。现以 SQLite 无操作的一元 `+` 去除该 affinity，保留 UTF-8 字节绑定和原生参数的比较语义；新增查询、更新、NULL/类型与列 affinity 回归。
- 原先按 DDL 全文查找 `VIRTUAL TABLE` 会误拒绝普通表的同名列、表名或字符串默认值。现读取 SQLite 的实际表类型。常规用例可完成安装、快照、更新、同步与审计；FTS 虚拟表分支仅在运行时实际编译了相应模块时执行。
- 升级失败测试验证：预算不足、坏日志、未知触发器定义均不改变旧触发器、日志、源标识、游标、消费者确认或保留水位；增加预算后可重试成功。
- 外键级联更新/删除、复合 DESC 主键和 WITHOUT ROWID 场景通过。目标新增 UNIQUE 约束导致批内第二条失败时，首条和游标一并回滚，移除外部约束后可重试。
- 独立副本运行 24 个固定种子、每个 180 次变更，比较 raw、相邻压缩、分批/合批/JSONL、过滤与过滤后压缩五种路径；混合类型主键、跨类型主键更新、过滤进出及列重排均无分歧。
- TEMP 业务触发器能绕过持久 main-schema 的触发器枚举；这是不支持的业务触发器场景，现明确由调用方禁止，而不再声称写保护可以完整检测它。

0.3.1 不改变捕获触发器格式；完整 0.3.0 捕获无需再次升级。以上结果限定于实际执行的范围，不代表对所有 SQL、外部组件和任意并发调度作无缺陷保证。

## 针对 0.3.1 的进一步复查

0.3.2 修复了以下独立复现的问题：

- 同名 TEMP 表/视图优先于 main 对象解析，可能使目标数据只写入临时表，但持久游标和源端确认已经推进。现在捕获、快照、投影和消费者状态入口拒绝遮蔽的业务对象及保留元数据名；无关 TEMP staging 表仍可使用。
- 普通表 `pragma_recursive_triggers` 可以伪造原保护查询的返回值。实际复现关闭 recursive triggers 后的 `REPLACE` 漏记隐式删除，留下已确认的多余目标行。新触发器使用函数调用语法读取 PRAGMA，同名普通表无法冒充；冲突写入整句回滚。表类型检查也改为 `PRAGMA main.table_list(...)`，避免同名普通表/临时表干扰检查。
- 128 列表原先生成 `json_array` 的 128 个参数，超过 SQLite 3.48.0 以前通常为 127 的参数上限。使用内置引擎安装后，外部 SQLite 3.45.3 写入端会报 malformed database schema，影响同库其他表。现在以 `json_insert` 追加末列，保持 wire 内容；独立脚本强制上限为 127，使较新 SQLite 的 CI 也能复现该兼容条件。[SQLite 官方参数上限说明](https://www.sqlite.org/limits.html#max_function_arg)解释了版本间的默认值变化。
- 持久表清单为空或含重复表名时，原状态检查可能报告一个不存在的空投影。现在统一校验 1..128 张表及名称唯一性；非法清单拒绝验证、状态查询和批次应用，原数据、游标及损坏证据保持不变。这是损坏检测加固，不构成恶意元数据防护承诺。

新增测试覆盖遮蔽后的数据/确认不变及移除遮蔽后恢复、源端视图遮蔽、元数据遮蔽、初始化失败回滚、PRAGMA 名称碰撞、128 列外部写入及旧触发器升级。升级测试覆盖完整 0.2.0、0.3.0/0.3.1 的普通宽度和 128 列定义，保留历史日志、源标识、消费者和水位，且重复升级为零变更。

本地验证：原生 **55/55**，JavaScript 与 wasm-gc 各 **15/15**；`python scripts/verify.py` 内的格式/编译/构建、独立集成、5,134 个 REAL 样本、200 次外部提交并发同步/清理，以及新增兼容性回归通过。有效生产 MoonBit 代码为 **4,671 行**。另使用外部 SQLite 3.45.3 验证宽表写入；全量脚本所用 Python SQLite 为 3.53.2，并显式设置函数参数上限 127。

0.3.2 变更了全部捕获触发器的 PRAGMA 保护。已有完整 0.2.0/0.3.0/0.3.1 源须在维护窗口运行 `upgrade-capture`；升级不恢复已经遗漏的事件或误确认的目标数据，须追平后审计，有分歧时从可信快照重建目标。0.1.0 仍使用原有新捕获代际迁移流程。

## 针对 0.3.2 的进一步复查

0.3.3 修复三项独立复现的问题，并补充一个连接配置边界：

- 无关 TEMP 自增 staging 表会自动生成 `temp.sqlite_sequence`。此前未限定 schema 的源水位查询会误读临时序列表，实际主库已有事件时仍报告零。查询现在显式读取 `main.sqlite_sequence`，回归覆盖建立快照、同步、清理与后续新写入。
- `INSERT OR FAIL`、`UPDATE OR FAIL` 可在语句报错后保留成功前缀；外部应用随后提交是合法 SQLite 行为，见[官方 FAIL 语义](https://www.sqlite.org/lang_conflict.html)。实测早期行及捕获事件已提交，但 `sqlite_sequence` 条目可能缺失或仍为旧值。水位现在取主库序列表与已保留事件最大序号的较大值；两种清理方式均在删除前于同一写事务封存水位，避免日志清空后复用已确认的事件序号。新增独立脚本用八种插入/更新、初始序列缺失/落后、全量/分批清理组合核对原始数据、类型和游标。
- JSONL 每次接收小片段时，原实现会拼接并重新扫描整个未完成行，产生平方级开销。现使用 builder 缓存片段，每次只扫描新输入。新增三后端回归覆盖 80KB 长行逐字符输入、Unicode 标量边界、CRLF、无结尾换行、精确资源限额和失败状态。独立原生探针的 80KB 单字符分块从约 8.23 秒降至 0.081 秒；新实现 20/40/80/160KB 三次运行中位数约为 0.046/0.056/0.081/0.125 秒，均含进程启动，仅表示本地探针结果。
- `trusted_schema=OFF` 会使 SQLite 拒绝捕获触发器内的表值 PRAGMA，写入报 unsafe use。当前捕获模式需要可信 schema，现已在 README、使用手册及 `plan.required_writer_pragmas` 明确列出；测试确认拒绝时没有部分数据或事件提交，恢复 ON 后可正常捕获。该限制与 SQLite 的[可信 schema 设置](https://www.sqlite.org/pragma.html#pragma_trusted_schema)有关，要求保持 OFF 的应用不适用此捕获模式。

另独立验证五类主键声明下的 REPLACE、UPDATE REPLACE、UPSERT、DO NOTHING、IGNORE、显式回滚及 ROLLBACK 冲突，共 35 个业务阶段；逐阶段核对行、存储类型和审计结果，未发现新分歧。Unicode 分块测试排除了调用方将 UTF-16 代理对切成无效字符串导致的数据丢弃，正式测试使用完整 Unicode 标量构造合法片段。

本地全量验证通过：原生 **62/62**、JavaScript 与 wasm-gc 各 **19/19**，格式/编译/构建、独立集成、5,134 个 REAL 样本、200 次外部提交并发同步/清理，以及兼容性与 FAIL 部分提交回归均通过。有效生产 MoonBit 代码为 **4,707 行**。FAIL 回归已分别在 Python 所带 SQLite 3.45.3 和 3.53.2 上运行。

本轮不改变 0.3.2 的捕获格式。更新时须替换所有同步/清理工作进程；已有错误水位快照造成的目标冲突需审计或重新初始化，不应跳过历史事件。

## 针对 0.3.3 的进一步复查

0.3.4 增加外键更新动作环检查，并修复诊断及名称匹配问题：

- 自引用 `ON UPDATE CASCADE` 可产生无法按序应用的事件。实测 `nodes(1,1)` 更新主键后，源行为 `(2,2)`，日志却先记录内部的 `(2,1) → (2,2)`，再记录外层 `(1,1) → (2,1)`，导致目标 before-image 冲突。现在根据 main 全部表的外键元数据，对 `ON UPDATE CASCADE / SET NULL / SET DEFAULT` 建图，以迭代遍历拒绝能返回捕获表的路径，包括未捕获的中间表；安装、验证、计划和诊断均检查。此策略按表结构保守判定，属于明确的功能边界，并未实现此类更新环的事件重排。普通无环级联、NO ACTION/RESTRICT 自引用及仅有删除动作的关系仍可用。
- 新增业务触发器后，原验证命令会拒绝，但诊断可能报告 `healthy:true`。诊断现列出每个额外触发器，并继续检查缺失/变化的捕获触发器；测试确认不会修复或删除原对象。
- `NOT LIKE 'sqlite_%'` 中的下划线通配符导致合法的 `sqliteX`、`sqlitexyz` 表被漏列，现按字面前缀匹配。安装、初始化及计划的保留命名空间检查也统一为不区分大小写，与 SQLite 对象名称规则一致；测试覆盖拒绝后的事务回滚和正常捕获/同步。

新增原生回归覆盖自引用三类修改动作、跨表环、未捕获中间表、合法级联、额外触发器，以及未改变捕获表 DDL 的后续新表成环。外部 Python SQLite 回归验证拒绝发生在元数据创建/消费者登记之前，原数据与已有消费者保持不变，并确认无环级联仍可逐事件同步和审计。另在独立 0.3.3 副本运行 12 个固定种子、每个 260 轮的三表交错测试，对比七种压缩/过滤/分批/JSONL 路径，未发现新分歧。

本地原生 **71/71**，JavaScript 与 wasm-gc 各 **19/19**；格式/编译/构建、独立集成、5,134 个 REAL 样本、200 次外部提交并发同步/清理、宽表兼容性及 FAIL 部分提交回归均通过。新增 schema 回归在 SQLite 3.45.3 与 3.53.2 通过。有效生产 MoonBit 代码为 **4,811 行**，公开 API 签名保持不变。

0.3.4 保留 0.3.2/0.3.3 触发器格式。已有含不支持更新环的捕获必须先评估应用和表结构，再从可信数据建立符合要求的新捕获；本次检查不修复已经错序的日志。

相关 SQLite 语义已与官方说明交叉核对：[外键动作在 AFTER 触发器之前执行](https://www.sqlite.org/foreignkeys.html#fk_actions)，[LIKE 下划线为单字符通配符](https://www.sqlite.org/lang_expr.html#like)。动作环是否可捕获是本项目基于实测和重放契约作出的保守限制。

## 针对 0.3.4 的进一步复查

0.3.5 补充了删除动作返入主键的结构检查：

- 最小复现为 `nodes(id INTEGER PRIMARY KEY DEFAULT 1 REFERENCES nodes(refkey) ON DELETE SET DEFAULT, refkey INTEGER UNIQUE)`，初始行为 `(1,2)` 与 `(2,1)`。删除第一行后源库合法提交为 `(1,1)`；原日志先记录第二行主键 `2→1`，再记录原主键 1 的删除，目标因此先遇到尚未删除的主键 1 并失败。此结构没有 ON UPDATE 动作环，原 0.3.4 检查无法识别。
- 已独立复现跨表 `DELETE CASCADE → SET DEFAULT → 主键移动` 的同类问题。新检测从每个捕获表的 DELETE 状态出发，迭代跟踪 DELETE CASCADE、SET NULL/DEFAULT 及后续 ON UPDATE 动作，拒绝返回同一捕获表并修改主键列的路径；包括未捕获的中间表。它是保守结构检查，未实现这类日志的事件重排。
- 纯删除 CASCADE、只改非主键的自引用 SET NULL/DEFAULT、无环复合外键和安全捕获子集仍通过。跨表示例中捕获不安全主键所在的 A 表被拒绝；只捕获 B 表时，实际删除、同步及审计仍一致。新增回归也验证未改变原捕获表 DDL 的新表创建会被验证、快照及诊断检测，失败时消费者及游标保持不变。

新增并纳入 CI 的错误路径覆盖：快照包含 INTEGER 1/REAL 1 主键而触发 SQLite 唯一约束时，新增表、首行与元数据全部回滚，已有无关表保留，同连接可重试；批次第 2 条出现未知表、NULL 键、行宽错误、重复键、before-image 类型冲突或删除不存在行时，第 1 条变更及游标一并回滚。独立进程测试持有真实目标读锁，使目标在 COMMIT 阶段超时，确认目标数据/游标与源端确认不前进；释放锁后恢复同步且重放不重复。

另独立验证复合父主键 WITHOUT ROWID、三类删除动作、更新级联、SAVEPOINT 回滚、延迟约束先子后父提交，以及延迟约束提交失败后回滚，未发现新分歧。

`python scripts/verify.py` 全部通过：原生 **78/78**，JavaScript 与 wasm-gc 各 **19/19**，包括 5,134 个 REAL 样本、200 次外部提交并发同步/清理及全部独立脚本。结构回归分别在 SQLite 3.45.3 与 3.53.2 通过。有效生产 MoonBit 代码 **4,886 行**，公开 API 签名保持不变。

0.3.5 沿用 0.3.2–0.3.4 的触发器格式。已有不符合新结构检查的捕获须先评估应用/表结构；本次检查不修复已经错序的历史日志。

## 针对 0.3.5 的进一步复查

0.3.6 修复两项新的错误路径：

- 目标 before-image 原先通过普通 SQLite 文本读取进入 UTF-16，可能将非法 UTF-8 与合法字符串读成相同值。实测目标 `X'80'` 与源合法 `U+0080`、目标 `C0AF/EDA080/FF` 与源合法 `U+FFFD` 均可误通过比较；仅更新源的另一列时同步成功并推进确认，目标非法字节被静默规范化。现在按主键筛选后复用原有 tagged SQL 与严格 UTF-8 解码，遇非法字节会拒绝预演、应用及同步，原字节、数据和游标不变；批次前缀也回滚。无新增公开 API，独立查询计划确认仍使用主键索引。
- 公共 `Database.query` 执行两行 `INSERT ... RETURNING` 且 `max_rows=1` 时，原实现抛行数超限错误，但两行已提交。现在 INSERT/UPDATE/DELETE/REPLACE/WITH 查询在自有事务或调用者事务的内部保存点执行，先关闭结果 statement 再提交或回滚。测试覆盖超限重试、已有 BEGIN 及同名外层保存点的前置写入保留、注释/BOM/前导分号、WITH DML/SELECT、PRAGMA 和事务指令兼容、OR FAIL 及 OR ROLLBACK。另以真实双连接读锁造成公共 query 的 COMMIT BUSY，确认无残留事务/数据，释放读锁后可重试。

事务保证针对上述结果查询。`execute` 继续按 SQLite 原生规则处理语句，OR FAIL 可以保留成功前缀；未绑定参数为 NULL 也是 SQLite 的既有语义，不作为缺陷更改。显式 OR ROLLBACK 仍可结束整个调用者事务；PRAGMA 设置的副作用不纳入查询回滚承诺。清理失败会明确报错，不静默留下未知事务状态。

新增严格文本测试还覆盖过滤投影、引号表名、复合 BOM/NUL/emoji 文本键，以及合法更新、主键移动、删除与修复后重试。普通全量读取路径沿用原 SQL，主键读取通过私有 CTE 复用统一解码。

本轮独立验证多路径菱形级联（同一叶节点连续修改）、纯跨表 DELETE CASCADE 环、引用 NOCASE 非主键唯一列的外键、父子列不同 affinity 的复合外键及无关 FTS5/影子表，均未发现新分歧。未扩大之前明确拒绝的外键动作边界。

`python scripts/verify.py` 全部通过：原生 **88/88**、JavaScript 与 wasm-gc 各 **19/19**，包括原有独立集成、5,134 个 REAL 样本、并发同步/清理、兼容性、部分提交及提交锁失败脚本。原 before-image 外部复现已确认改为拒绝，原始字节与两端游标保持不变。有效生产 MoonBit 代码 **5,051 行**，公开 API 签名及捕获触发器格式保持不变。
