# 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 的捕获格式。更新时须替换所有同步/清理工作进程；已有错误水位快照造成的目标冲突需审计或重新初始化，不应跳过历史事件。
