MoonSQLiteFile v0.8.1

v0.8.1 提升只读数据库浏览与异步接入的可靠性，完善有界记录预览和报告导出。

主要更新

• 新增有界对象浏览和可续读的原始记录预览，显示 view、trigger 与无根页对象的定义及适用操作。
• 修复回调错误来源、重复关闭等待、取消参数和预览续读预算，导出报告保留实际预算与诊断来源。
• 补齐异步 JS 包常用 TypeScript 结果与可判别类型，统一页号、预算与 signal 校验。
• 改善窄屏、键盘与历史恢复，限制 Worker 展示消息和大值批次；库扫描保留完整原始值。

升级说明

页号和整数预算不再静默截断小数；signal 须传真实 AbortSignal，null/0 不再视为省略。重复 close 等待同次清理，失败后保持拒绝。TypeScript 消费者需按 status/code 缩窄结果，并处理 WAL 偏移的 number/十进制文本联合。详见 v0.8.1 升级说明。

安装

MoonBit 包已发布到 Mooncakes：

moon add prowk/moonsqlitefile@0.8.1

附件 moonsqlitefile-viewer-0.8.1.html 为单文件检查器，通过 HTTP 使用；直接 file:// 打开尚未验收。也可使用 在线检查器。

异步 JS 包以 prowk-moonsqlitefile-async-0.8.1.tgz 附件提供，尚未发布 npm registry；下载后安装：

npm install ./prowk-moonsqlitefile-async-0.8.1.tgz

SHA256SUMS 提供上述两个附件的 SHA-256 校验值。HTML 与候选提交的 pinned CI 产物一致；异步包由该候选已验收的本地构建打包。

验证

发布提交 4777689 的 pinned/latest 完整 CI 均通过，复用该提交旧流程 push 触发的完整验收结果。实际 Mooncakes 安装消费、异步 tarball 消费及正式 Pages 验收通过。

使用边界

输入须为一致的静态 db/WAL 副本。Complete 仅表示声明范围内的结构检查完成，不等同于 SQLite integrity_check；不执行 SQL、写入或在线快照。

相关链接

Mooncakes API · CHANGELOG · 完整差异

MoonSQLiteFile v0.8.0

v0.8.0 完善源码组织、公开契约文档与兼容验证，并精简项目首页，让安装、使用和参与开发的入口更清楚。

主要更新

• MoonBit 源码、同包测试、CLI 和示例迁入 src/，对外仍导入 prowk/moonsqlitefile；保留单核心包，正常库构建不包含测试代码或新的生成依赖。
• 补齐 124 个公开类型/函数契约注释及异步导出说明，明确预算、错误来源、部分报告、游标供给与释放。
• README 从 249 行精简到 90 行；详细 API/CLI 用法迁至使用指南，完整验证命令集中到贡献指南，首页和指南中的六个原文函数继续在四后端运行验证。
• 增加六项公开黑盒回归，保护 v0.7.0 的 237 项核心声明与异步导出/原型；全部 17 个 CLI 命令使用 22 个历史输出/退出码场景作对照。
• 固定已验工具链并独立验证官方 latest；新增支持矩阵、贡献指南、12 个同输入性能对照场景，以及三个历史 fuzz 边界输入的持续重放。

升级说明

外部使用者继续导入 prowk/moonsqlitefile，无需添加 /src。源码贡献者和自动化脚本需更新源文件、CLI 与 MoonBit 示例路径，例如 moon build --target js src/cmd/inspect。公开声明、CLI 历史场景和异步接口已通过兼容检查；既有默认预算与错误映射保持原语义。

固定工具链与已验证宿主见支持矩阵，完整迁移说明见 v0.8.0 升级指南。

安装

moon add prowk/moonsqlitefile@0.8.0

浏览器工具下载本页 moonsqlitefile-viewer.html。异步 JS 包下载 prowk-moonsqlitefile-async-0.8.0.tgz 后执行 npm install ./prowk-moonsqlitefile-async-0.8.0.tgz；该包未发布 npm registry。附件校验值见 SHA256SUMS.txt。

验证

• 发布 tag 指向 cf7bdc5d9c9dd808640190d7f6904be4a21de8f9；该提交的 GitHub CI 中 pinned/latest 两个完整作业均通过。本地两个通道各 34 项检查通过，四后端各 127 项测试通过；本次官方 latest 与固定版本一致，已核对实际二进制与标准库。
• 公开 API、17 个 CLI 命令、六个文档函数、实际打包库、异步 tarball、浏览器 File/Blob/Worker 与取消释放验收通过；浏览器覆盖 HTTP 载入后断网。
• SQLite 对照包含 29 组同步/异步 WAL 快照、5470 条恢复记录；大 payload、高位 WAL、12 个同输入成本场景、历史 fuzz 重放与 512 次固定种子变更通过。Linux CI 启用 dbstat。
• 发布后从真实 Mooncakes registry 安装 0.8.0，在独立消费项目中完成四后端 check/build/test，并运行范围源、WAL 和游标 API。

使用边界

只读同一时刻且使用期间不变的 SQLite 主文件与 WAL 副本；不执行 SQL、写入、checkpoint、在线锁或 shm 协议，不提供恢复。返回磁盘存储值，不提供完整 SQL 列映射，也不验证索引排序/collation 或表与索引内容一致性。Complete 仅表示声明范围完成，不等于 SQLite integrity_check。

64 位寻址不等于常量内存：页号仍为 Int，单条 payload 完整解码，全局报告、遍历状态和 WAL 索引分别需要预算。浏览器直接 file:// 打开仍未验收，建议通过本机静态 HTTP 服务载入 HTML 后离线使用。

相关链接

• Mooncakes API 文档
• 此版本 CHANGELOG
• v0.7.0 → v0.8.0 完整差异
• 使用指南 · 贡献与验证

MoonSQLiteFile v0.7.0

v0.7.0 从 v0.5.0 直接升级，合入原 v0.6.0 内部里程碑，提供 64 位 db/WAL 范围读取、异步宿主与浏览器分块检查；v0.6.0 不单独发布。

主要更新

• 新增 RangeSource、CachedSource、RangeWalSource，以 64 位长度和偏移按需读取主文件及 WAL，分别限制缓存、帧数、覆盖索引和报告页数。
• 新增无 I/O 的 BTreeCursor、WalCursor、InspectionCursor，同步和异步入口复用同一核心校验状态机。
• 提供独立 JS 异步适配包：Node BigInt/Blob 范围源、异步迭代器及 visitor 背压、AbortSignal 取消、部分报告和句柄释放。包作为本页 tarball 附件提供，尚未发布 npm registry。
• 单文件 HTML 使用 File/Blob Worker 分块检查 db/WAL，保留页面导航，新增进度、取消和可调整预算。移除 64 MiB 文件长度限制，默认累计 payload 仍为 64 MiB，时间预算调整为 120 秒。
• CLI 改用只读范围 I/O，新增资源预算和 I/O 统计选项；修复合法碎片被误拒、非根空 B-tree 页被漏检，以及错误信息丢失；适配器准确区分越界、短读和宿主失败。

升级说明

历史公开声明继续接受兼容检查，但检查行为有变化：非根空页现在拒绝，碎片不一致统一定位为 FragmentCount，超过 Int 的页指针返回 LimitExceeded。使用大文件时须改用范围入口；超过 Int 长度的旧 Database.source 视图不支持读取，应使用 source64()。单条/累计 payload 默认仍为 16 MiB / 64 MiB，完整扫描大 payload 库须单独调整预算。

异步宿主验证范围为 Node 22 与 Chrome/Chromium；异步 WAL JSON 的 64 位字段为十进制文本。详情见 v0.5.0 → v0.7.0 升级说明及其中链接的同步范围迁移文档。

安装

moon add prowk/moonsqlitefile@0.7.0

浏览器检查器下载本页 moonsqlitefile-viewer.html。异步 JS 包下载 prowk-moonsqlitefile-async-0.7.0.tgz 后执行 npm install ./prowk-moonsqlitefile-async-0.7.0.tgz；附件校验值见 SHA256SUMS.txt。

验证

• 发布 tag 指向 8a3a4c79ecd54c893604839f9136081289b8f21b，该提交的 GitHub CI 全部通过；本地 27 项检查通过，Wasm、WasmGC、JavaScript、native 各 121 项测试通过。
• SQLite 对照覆盖 1063 行普通表、4407 条索引/WITHOUT ROWID 记录、2412 页归属及 54 组 SQL 操作回归；Linux CI 启用 dbstat。同步和异步均对照 29 组 WAL 快照、5470 条恢复记录，另有六组数据库同步/异步差分。
• 验证超过 2 GiB 的主文件/WAL 偏移、超过 64 MiB 的 payload 预算、重复更新 WAL 成本及 512 次固定种子模糊测试。
• 实际 HTML、独立 npm tarball 消费及真实浏览器的 File/Blob、Worker、取消、释放、WAL 与大库预算验收通过。72663040 字节数据库提高预算后检查 17740 页、1101 条记录，最大读取块为 4096 字节。
• 发布后从真实 Mooncakes registry 安装 0.7.0，独立项目在四后端完成 check/build/test 并实际运行同步范围、WAL 和游标 API。

使用边界

只读同一时刻且使用期间不变的 SQLite 主文件及 WAL 副本；不执行 SQL、写入、checkpoint、在线锁或 shm 协议，不提供任意历史事务或损坏/删除数据恢复。结构检查 Complete 不等于 SQLite integrity_check，不验证索引排序/collation 或表与索引内容一致性。

64 位范围读取仍以 Int 表示页号，最多 2147483647 页；单条 payload 完整解码，全局报告与 WAL 索引仍需要独立内存预算。浏览器已验证本机 HTTP 载入后断网，直接 file:// 打开尚未验收；建议通过本机静态 HTTP 服务载入 HTML。

相关链接

• Mooncakes API 文档
• 此版本 CHANGELOG
• v0.5.0 → v0.7.0 完整差异
• 同步范围读取 · 异步适配契约

MoonSQLiteFile v0.5.0

v0.5.0 新增 WAL 帧检查与最新已提交快照的只读覆盖，库和 CLI 可读取一致的 db/WAL 静态副本。

主要更新

• 新增 parse_wal_header、inspect_wal，验证 header/frame、两种累计 checksum 字节序与 salt，报告连续有效帧、提交边界及首个停止原因。
• 新增 WalSource、open_wal_source、open_wal_database，复用原有检查器，采用最新已提交页版本与提交后的逻辑页数；隔离未提交更新及缩小、再次增长后的旧页版本。
• 默认拒绝异常尾部；显式 UseValidPrefix 只读取此前最后一个完整提交，不跳过中间坏帧。帧预算不足保留限额错误，不作为旧快照成功返回。
• CLI 新增 --wal WAL [--wal-prefix]、wal-inspect 与 wal-info；原有查询、页面、检查及中文摘要命令可使用同一 WAL 覆盖视图。
• 扩展真实 SQLite 恢复对照和配对模糊测试；失败样本同时保留主文件并自动配对重放。修正模糊工具对 65536 字节页长的定位。

升级说明

重新生成接口后，核对 v0.3.0 的 85 项和 v0.4.0 的 123 项公开声明，原有签名、结构字段及枚举分支保持原有形式。普通 open_database / open_source 仍只读取主文件；WAL 视图必须使用专用打开入口，其逻辑边界以 page_count() 为准。默认严格策略可能拒绝 reset 后残留的旧 salt 尾部；检查报告后可显式采用前缀策略。详见 v0.5.0 升级说明。

安装

moon add prowk/moonsqlitefile@0.5.0

验证

• 发布 tag 指向 06b7ecada2ae08dbbddf96e98c37e8ea258a2b5b，该提交的 GitHub CI 全部通过；Wasm、WasmGC、JavaScript、native 各 98 项测试通过。
• WAL 独立 SQLite 恢复对照通过：29 组快照、5470 条记录，覆盖双 checksum 字节序、三种文本编码、512/4096/65536 字节页、多事务、未提交尾帧、中间损坏、reset 及页数缩小/增长；原始输入未被改写。
• 原有 1063 行普通表、4407 条索引/WITHOUT ROWID 记录及 18 个数据库 2412 页对照继续通过；Linux CI 对全部数据库启用 dbstat 对照。
• 固定种子 512 次变更及同一提交的 额外 5000 次模糊验收 通过，覆盖数据库与配对 WAL。这是 JavaScript 后端的有界字节变更测试，没有覆盖率引导。
• 历史 API、独立打包消费及实际 HTML 内嵌解析器/导航数据验证通过。发布后从真实 Mooncakes registry 安装 0.5.0，独立项目在四后端完成 check/build/test 并实际运行 WAL API 与第三方 PageSource。

使用边界

支持静态 SQLite 3 主文件与最新已提交 WAL 快照，复用四种 B-tree、索引及 WITHOUT ROWID 原始记录、overflow、freelist、三种文本编码和 auto-vacuum Ptrmap 检查。结构检查完成不等同于 SQLite integrity_check。

宿主必须提供同一数据库、同一时刻且使用期间不变的 db/WAL 副本；salt/checksum 不能验证主文件身份。不执行 SQL、写事务、checkpoint、在线锁或 shm 协议，不提供任意历史事务、损坏/删除数据恢复，也不验证索引排序/collation 或表与索引内容一致性。

输入仍采用同步 Int 寻址，WAL 默认最多验证 100000 帧；64 位及异步读取属于后续版本。附带 HTML 仍只读取单个静态主文件，限制 64 MiB 和单次 30 秒，不接收 WAL；需要 WAL 的场景使用库或 CLI。

相关链接

• Mooncakes API 文档
• 此版本 CHANGELOG
• v0.4.0 → v0.5.0 完整差异
• WAL 契约与 CLI
• 模糊测试与配对重放

MoonSQLiteFile v0.4.0

v0.4.0 补齐静态 B-tree 页空间校验，并提供可定位诊断、页面与对象统计、中文摘要及单文件离线页面导航。

主要更新

• 校验四种 B-tree cell 的完整空间覆盖、最小填充、cell/freeblock 重叠、未登记空闲区间和碎片计数；修复空叶页跳过树深度验证的问题。
• 新增 inspect_page、PageStatistics 和 PageDiagnostic，提供页内空间分项、声明 payload 与实际错误页/偏移/cell 下标。
• 新增 inspect_btree_details、inspect_database_details，在同一次检查中保存树、overflow、record/schema、freelist、归属及 Ptrmap 的失败位置；保留原报告进度与诊断上限。
• 新增 DatabaseInspection.summarize()、中文 summary 和 summary-json，汇总八类页及每对象 B-tree/overflow 占页，不重复读取数据库或计入冲突引用。
• 新增 viewer-data 和离线 HTML 检查器，支持对象根页、父子页和 overflow 跳转、空间分布、cell 定位、原始字节与诊断位置。下方附件可直接保存到本地使用。
• 新增有界、可重放的持续模糊测试：日常 CI 固定种子 512 次变更，每日任务 5000 次并更换种子；异常保存输入和重放元数据。

升级说明

现有 v0.3.0 公开签名、结构字段与枚举分支保持原有形式，但页面校验更严格：以前接受的空间损坏现在可能返回 Invalid；小 limit 读取前缀也会验证所访问页面的全部 cell。新单页接口的读取失败为 Incomplete，旧树/全库报告仍沿用原错误映射；请结合读取阶段判断，不能仅凭宿主 Invalid 宣称文件损坏。详见 v0.4.0 升级说明。

安装

moon add prowk/moonsqlitefile@0.4.0

验证

• 发布 tag 指向 1155d786580b971768fec18267a357a16ed2606f，该提交的 GitHub CI 全部通过；Wasm、WasmGC、JavaScript、native 各 86 项测试通过。
• SQLite 对照通过：1063 行普通表数据、4407 条索引/WITHOUT ROWID 记录，18 个数据库共 2412 页；Linux CI 对全部数据库使用 dbstat 核实逐页空间及每对象占页。
• 固定种子 512 次变更及发布提交的 额外 5000 次模糊验收 通过；此项是 JavaScript 后端的字节变更测试，没有覆盖率引导。
• 85 项 v0.3.0 公开声明对照、实际 HTML 内嵌解析器/导航数据与独立打包消费通过；浏览器本地预览验证对象、子页、overflow 和损坏诊断跳转。
• 发布后从真实 Mooncakes registry 安装 0.4.0，独立项目的四后端 check/build/test 和 JS 运行通过，覆盖第三方 PageSource、新报告及旧结构直接构造。

使用边界

支持静态 SQLite 3 文件、四种 B-tree、索引内部页与 WITHOUT ROWID 原始记录、overflow、freelist、三种文本编码及 auto-vacuum Ptrmap。结构完成状态不等同于 SQLite integrity_check；单页统计不验证外部链或 record 内容，未完成报告的汇总仅表示已观察结果。

不执行 SQL、不写入文件、不合并 WAL，也不验证索引排序/collation、表与索引内容一致性或恢复损坏/删除数据。PageSource 为同步 Int 偏移接口；离线演示完整读取最多 64 MiB，单次检查最多 30 秒，使用 Blob Worker，不包含网络资源。大文件、64 位及异步读取仍属于后续版本范围。

相关链接

• Mooncakes API 文档
• 此版本 CHANGELOG
• v0.3.0 → v0.4.0 完整差异
• 离线检查器使用说明
• 模糊测试与重放

MoonSQLiteFile v0.3.0

v0.3.0 增加数据库结构检查，追踪全局页归属、校验 auto-vacuum 反向指针并输出有界诊断报告。

主要更新

• 新增 Database.inspect_database：发现 schema 根页，扫描表、索引、overflow 和 freelist，报告跨对象重复占页、freelist 冲突与未认领页；全程共享记录、页数、累计 payload 和诊断预算。
• 新增 Database.ptrmap_entries：支持 FULL / INCREMENTAL auto-vacuum 五类反向指针，并在全局检查中核对类型、父页、largest root 与根页排列。
• 新增 Database.inspect_btree 与 BTreeInspection：保留单树检查状态、原始错误和此前成功解码的记录数。
• 新增 inspect JSON CLI，退出码 0/1/2 分别表示完整、失败和未完成；报告明确标记归属遍历、Ptrmap 检查与诊断截断。根页发现不完整时，未知页不会被判作孤儿。

升级说明

公开的 Header 新增 largest_root_page : UInt 与 incremental_vacuum : Bool 字段；直接构造 Header 的消费代码需要补齐字段。从 parse_header 或 Database.header() 获取头部的代码可继续使用。检查调用方需同时处理完成状态与覆盖标记，具体含义见本版本架构说明。

安装

moon add prowk/moonsqlitefile@0.3.0

验证

• Wasm、WasmGC、JavaScript、native 四后端各 55 项测试通过，包含 192 次确定性字节变更回归扫描。
• SQLite 对照通过：1063 行普通表数据、4407 条索引及 WITHOUT ROWID 原始记录。
• 页归属对照覆盖 13 个数据库、1765 页，验证 FULL / INCREMENTAL auto-vacuum、别名根页、孤儿页、Ptrmap 类型与父页错误及诊断截断。
• 独立打包消费验证通过，覆盖新检查 API 和第三方 PageSource。
• 发布 tag 指向 1159951e72a4ac6d4b2e2a4de6dc42f9788b75f5，其GitHub CI 全部通过。

使用边界

只读静态 SQLite 3 数据库文件，支持普通表、索引、WITHOUT ROWID 和 auto-vacuum 页结构；不执行 SQL、不写数据库、不合并 WAL、不恢复删除记录。返回原始存储值，不提供 SQL 列映射。结构检查尚不验证索引排序与 collation、表/索引记录一致性或完整 cell 空间覆盖，不等同于 SQLite integrity_check。同步 PageSource 使用 Int 偏移，不提供异步 I/O 或快照获取协议；全局页归属检查仅覆盖逻辑数据库页。

相关链接

• Mooncakes API 文档
• 本版本 CHANGELOG
• 与 v0.2.0 的完整差异

MoonSQLiteFile v0.2.0

v0.2.0 补齐 SQLite 索引与 WITHOUT ROWID 表的原始记录读取，并增加有界逐条扫描和宿主静态数据源接口。

主要更新

• 统一四类 B-tree 遍历，读取索引内部页记录，支持 WITHOUT ROWID 表的磁盘存储记录。
• 新增 BTreeRecord、read_btree、table_records、index_records 和 scan_btree；扫描支持回调提前停止，并区分完整、记录上限和主动停止。
• 增加累计 payload 和跨 B-tree/overflow 页预算，拒绝重复占页。
• 新增同步 PageSource 与 open_source，供宿主按需读取同一份静态快照；保留 open_database(Bytes) 和普通 rowid 表 API。
• JSON CLI 新增 records、index、scan 命令。

升级说明

扫描现在累计限制 payload 与 B-tree/overflow 页数；超预算或重复占页的输入会被拒绝。需要调整预算时，请参考本版本资源边界与扫描完成状态。PageSource 必须在整个读取期间保持静态快照；WITHOUT ROWID 表请改用 table_records 读取原始存储记录。

安装

moon add prowk/moonsqlitefile@0.2.0

验证

• Wasm、WasmGC、JavaScript、native 四后端各 42 项测试通过，包含 192 次确定性字节变更回归扫描。
• SQLite 对照通过：1063 行普通表数据、4407 条索引及 WITHOUT ROWID 原始记录。
• 独立打包消费验证通过，包含第三方 PageSource 实现。
• 发布 tag 指向 a8a324a6c7780abd71ebc7d8b51512a5298e6f0f，其GitHub CI 全部通过。

使用边界

只读静态 SQLite 3 数据库文件，不执行 SQL、不写数据库、不合并 WAL、不恢复删除记录。返回磁盘字段顺序和存储值，不推断 SQL 列映射；索引排序、collation 和全局页归属报告尚未实现。同步 PageSource 使用 Int 偏移，不提供异步 I/O 或快照获取协议；扫描完成不等同于 SQLite integrity_check。

相关链接

• Mooncakes API 文档
• 本版本 CHANGELOG
• 与 v0.1.0 的完整差异