# MoonTxnWitness 参赛项目说明

**面向数据库与后端开发者的离线事务反例工具。** 读写日志常常能够显示异常现象，却难以说明哪些事务互相冲突、缺了什么观察、删除哪些噪声后仍能复现。MoonTxnWitness 把“采集 → 解释 → 缩减 → 复现 → 修复回归”连接起来。

## 实际交付

生产分析核心使用 MoonBit：唯一版本点读写模型、WR/WW/RW/RT 依赖、强连通分量和全局最短环、有预算的完整串行补全、事务缩减、语义回放、中文报告。Node 提供文件操作和便携入口，Python 可选采集 SQLite/PostgreSQL 真实执行；这些外围工具不替代分析算法。

下载 portable 包后，`node dist/demo.mjs` 完成离线演示。真实数据库使用 `node dist/postgres-demo.mjs`，需要按说明安装可选驱动并配置测试数据库。每次运行保存新目录，缺少数据库时明确未执行。项目同时提供 Mooncakes 库和 JS SDK。

## 可核验的改进

- 连续版本 v0.0.7–v0.0.11 分别建立基线、降低图/报告分配、加入回滚与失败状态缓存、扩大反例缩减和接入真实 PostgreSQL；提交和发布标签保留开发过程。
- v2 证据记录算法、模型、有效预算和版本来源；运行计数与判断证据分离。历史 v1 包保持原搜索顺序、预算和比较规则。
- 边保留完整操作与版本来源；搜索得到的版本顺序标为可能补全，不变成采集事实。预算耗尽返回无法判定；单最小声明要求完成剩余事务的单删检查。
- PostgreSQL 对照采用两连接、唯一版本点读写和同步屏障，保留 SQL 结果、40001 回滚及全新事务重试。异常与修复案例都可缩减/导出/离线回放。

逐版原始性能样本、环境、输入摘要、失败尝试和验收结果在 `verification/releases/`。
测试包括独立串行重放、独立最短环核对、解析器差分、候选缩减核对、篡改拒绝、跨目标核心测试、Linux Native 与独立 PostgreSQL CI。具体数量及实际运行状态以当前版本记录为准，不能把“已配置”视为“已通过”。

## 边界与来源

范围是带唯一版本的点读写寄存器；尚未支持范围/谓词查询、自动 SQL 插桩、任意业务 SQL 或完整隔离级别分类。它检查所提供的历史及约束，不认证采集者或整个数据库。独特性定位是 MoonBit 内完整、可复现的证据流程，不声称提出了全球首个事务分析算法。

概念参考 Elle、Adya 等人的依赖模型和 PostgreSQL/SQLite 官方文档，代码与许可证说明见 `THIRD_PARTY.md`。本项目不调用或嵌入 Elle。性能阈值是工程验收目标，官方未公开量化权重，不把本地达标表述为获奖分数线。

## AI 使用及参赛者验收

AI 协助代码、测试、文档、性能定位和发布操作。独立重放工具采用整个事务的串行枚举，避免用生产依赖规则自证全部结论。参赛者仍须亲自完成 `docs/human-acceptance.md` 中的安装、运行、解释和边界核对；当前未收到该人工验收回执。报名、入群、官方验收和奖项状态单独记录，不能从代码发布推断。

官方依据：[2026 MoonBit 黑客松](https://moonbitlang.github.io/Hackathon2026/)。十月材料只列截止时实际完成并验证的成果；链接章程及报名状态应由参赛者在提交时再次核对。