MetonaTeam/MetonaSqlark
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(v0.8.0): 全量回归审查 —— 1 处 P0 数据丢失 + 4 处 P1 + 9 处 P2 根因修复

Browse Source 
方法：四个对抗性子代理分头审查（数据正确性 / 文档宣称 vs 实现 / 公共 API 契约 /
测试质量），每条结论要求可复现证据；逐条复核 + 探针确认 + 变异验证（40 项全部
被对应用例拦住）。

P0：事务活跃期间 repair()/close()/周期 checkpoint 推进 WAL 水位 → 已 COMMIT 的
事务整批消失且恢复报告"干净"。根因 hasPendingFlushData()/computeDurableLsn()
不看 txnSnapshot；守卫此前只在 CheckpointManager 两个回调里。修复：守卫下沉到
computeDurableLsn() 与 advanceWalCheckpoint() 入口（唯一实现）。

P1：
- WAL 前缀缺失丢弃整段活分片（回退上一代 manifest 时 kept 为空）→ 前缀缺失单独
  记录，后缀照常重放；仅 fromLsn === 0 时才算真异常
- 孤儿回收门槛只看引擎层 dataLossSuspected，漏掉 LSM 层被丢的 SSTable →
  统一 describeRecoveryDamage() 聚合判定（损坏时绝不删"引用不到"的文件）
- vacuum() 逐层压缩绕过维护链 → vacuumLevels() 每层作为维护链任务执行
- reclaimRetiredNow() 无视在途读者（读者把"已退休"读成"文件损坏"）→ 有读者时
  退化为延迟回收

P2：WAL 记录级 CRC 损坏不计数不上报；旧格式表结构记录形状损坏静默当空库；
bloomFilterBitsPerKey 配置被接受却完全不生效（构建器写死默认值，实现缺陷）；
幽灵 meta；介质读故障等于文件损坏的语义无用例；manifest 回读校验两条守卫无用例；
文件名≠载荷世代判定无用例；pageIdWatermark 单调性无用例；分片号两条真实不变量
无用例。

覆盖率口径（第二处漏洞）：interface.ts 混着三个运行时函数（cloneRow 等）却被
描述为"纯类型、不纳入统计" → 实现搬到 src/engine/row_clone.ts；搬完门禁真的
失败（functions 93.84% < 94%），补测退化路径后通过。

测试质量：3 条空壳用例改值级断言；1 条"全损坏"用例实际只走缓存 → 拆成两条真
用例；5 秒墙钟 race 改门控 + 失败上限；setTimeout 改 whenIdle()；<= 收紧为 <。

变异脚本加固：正控（干净基线必须全绿）、编译失败/0 用例单独归类、300s 超时、
逐字节 sha256 恢复校验、O_EXCL 进程锁、锚点唯一性；变异 22 → 40 项。

文档两轮订正（16 + 11 条不成立宣称）：MVCC 快照隔离、backup 一致性快照、
"空洞检测截断"、体积（251,109 B / gzip 63,145 B）、测试与覆盖率数字、
"5 种存储引擎"、Tree-shakable、错误码表补 16 个码、恢复报告字段、已知限制
（回退单向 / 多实例依赖 Web Locks / manifest 体积 / 尾部 WAL 分片不可识别）。

验证：常规套件 92 套件 / 1980 用例全绿；覆盖率 90.59 / 82.59 / 94.14 / 93.50
（阈值 90/82/94/93）；e2e 14/14（真实 Chromium + OPFS + CDP 崩溃）；
重型套件 4 套件 / 27 用例；变异 40/40；lint + 两份 tsc 干净；dist 已重建。
This commit is contained in:
thzxx
2026-09-15 16:33:40 +08:00
parent c3757f486c
commit 0b44620721
34 changed files with 4026 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -11,3 +11,6 @@ coverage/
# Playwright e2e 产物 # Playwright e2e 产物
test-results/ test-results/
playwright-report/ playwright-report/
# 变异验证进程锁（运行时产物，勿提交）
.mutation-b6.lock
CHANGELOG.md
+150 -13
View File
@@ -2,7 +2,7 @@
All notable changes to MetonaSqlark will be documented in this file. All notable changes to MetonaSqlark will be documented in this file.
## [0.8.0] - 2026-08-16 ## [0.8.0] - 2026-09-15
### 根治性迭代 —— 统一语义 / 消灭复发结构 / 验证基础设施 ### 根治性迭代 —— 统一语义 / 消灭复发结构 / 验证基础设施
@@ -11,8 +11,9 @@ All notable changes to MetonaSqlark will be documented in this file.
> 必然复发的结构**：多处并存的语义实现被收敛为唯一实现，并第一次让崩溃语义、 > 必然复发的结构**：多处并存的语义实现被收敛为唯一实现，并第一次让崩溃语义、
> 错误码一致性、入口等价性变成可机器验证的门禁。 > 错误码一致性、入口等价性变成可机器验证的门禁。
> >
> 测试规模 1304 → **1935（91 套件）+ 14 项 e2e**（另 4 个重型套件在独立 CI > 测试规模 1304 → **1980（92 套件）+ 14 项 e2e**（另 4 个重型套件在独立 CI
> job 串行运行）；B-6 的全部修复另有 **22 项变异验证**（`scripts/mutation-b6.py`，全部通过）。 > job 串行运行）；B-6 与审查轮的全部修复另有 **40 项变异验证**（`scripts/mutation-b6.py`，
> 全部通过，且脚本自带正控 / 编译失败区分 / 超时 / 逐字节恢复校验 / 进程锁）。
### 工作流 B · 结构根治（消除整类缺陷） ### 工作流 B · 结构根治（消除整类缺陷）
@@ -53,11 +54,28 @@ All notable changes to MetonaSqlark will be documented in this file.
- **元数据损坏不再静默空库**：此前 `__aria_lsm_meta*` 是裸 JSON，解析失败即 - **元数据损坏不再静默空库**：此前 `__aria_lsm_meta*` 是裸 JSON，解析失败即
`[]` → 看不到任何表，随后 `repair()` 还会把"没人引用"的活页删光（不可逆）。 `[]` → 看不到任何表，随后 `repair()` 还会把"没人引用"的活页删光（不可逆）。
现在全部世代校验失败抛 `ARIA_MANIFEST_CORRUPT`，旧格式迁移遇到坏 JSON 抛 现在全部世代校验失败抛 `ARIA_MANIFEST_CORRUPT`，旧格式迁移遇到坏 JSON 抛
`ARIA_LEGACY_META_CORRUPT`。 `ARIA_LEGACY_META_CORRUPT`。表结构记录的**形状**坏掉（数组 / null / 表名映射到
非对象 / 列定义不是对象）此前被静默忽略（打开后"看不到任何表"）—— 现在与坏 JSON
同一条路径显式报错（v0.8.0 审查修复）。
- **WAL**：LSN 改为一库一条单调水位（manifest 记账）；按水位删除旧分片； - **WAL**：LSN 改为一库一条单调水位（manifest 记账）；按水位删除旧分片；
**分片号只增不减**（修复前全量截断后重置为 0，会与 manifest 记录的 **分片号绝不回退、也绝不低于 manifest 水位**（修复前全量截断后重置为 0，
`startSegment` 错位，实测造成"删掉的行复活"与"已确认写入丢失"两个方向的损坏）； 会与 manifest 记录的 `startSegment` 错位，实测造成"删掉的行复活"与
分片空洞（含前缀缺失）显式报 `ARIA_WAL_GAP` 而不是静默丢弃尾部。 "已确认写入丢失"两个方向的损坏；整体清空后允许复用**最后用过的那个号** ——
记录自带 LSN，旧世代记录按水位跳过，这一点在审查轮做了语义澄清）；
分片内部空洞显式上报，水位从未推进时的前缀缺失同样按空洞上报，
水位已推进时的前缀缺失视为"已清理的前缀"（回退上一代 manifest 的正常情况）。
另修：前缀缺失此前会把**整段活分片**丢掉（`kept = segments.filter(seq < firstGap)`
在只有前缀缺失时结果为空的连带后果）。
- **WAL 记录级损坏**：CRC 失败的记录此前只打一条日志 —— 现在计数并进入恢复报告
（`droppedWALRecords` + `dataLossSuspected = true`），"少了几条已提交写入"不再
不可观测。
- **checkpoint 不再把 LSN 归零**：LSN 是 manifest 记录的全库单调水位，归零会让
"跳过 `lsn <= startLsn`"的判定与历史分片冲突（同一段 LSN 区间对应两批不同记录）。
- **`vacuum()` 报告真实层数**：修复前硬编码返回 6 且**底部层永不压缩**
（墓碑与历史版本在最底层永久累积）；现在逐层尝试（含底部层原地合并）并只统计
真正合并了的层，同时把逐层压缩挂到维护链上串行执行。
- **`close()` 在落盘失败时也必须释放资源**：修复前会卡在 flush 上，后端/锁/状态
都不复位（现在 `try/finally` 保证清理，错误照常抛出）。
- **LSM**：冻结表成为一等状态（失败可重试，`flush()` 先入链再报错，修复前 - **LSM**：冻结表成为一等状态（失败可重试，`flush()` 先入链再报错，修复前
一次后台失败会让之后每次 flush 直接抛错、数据永远等不到落盘）；compaction 一次后台失败会让之后每次 flush 直接抛错、数据永远等不到落盘）；compaction
不再"先摘整层再合并"（窗口内该层对读者不可见 → 少行）；底部层原地合并 不再"先摘整层再合并"（窗口内该层对读者不可见 → 少行）；底部层原地合并
@@ -72,9 +90,10 @@ All notable changes to MetonaSqlark will be documented in this file.
不再被折叠成 null 从而误删元数据。 不再被折叠成 null 从而误删元数据。
- **恢复报告**：`engine.getRecoveryReport()` 返回 - **恢复报告**：`engine.getRecoveryReport()` 返回
`{droppedSSTables, dataLossSuspected, walGaps, legacyImported, manifestFallback}`。 `{droppedSSTables, dataLossSuspected, walGaps, legacyImported, manifestFallback}`。
- 新增 `tests/v080-b6-single-commit-point.test.ts`（63 项：含 manifest 严格校验 - 新增 `tests/v080-b6-single-commit-point.test.ts`（审查轮后扩到 **96 项**：
表驱动 25 例）与 manifest 严格校验表驱动 24 例 + 事务水位 P0 + 前缀空洞语义 + 在途读者与退休文件 +
`scripts/mutation-b6.py`（22 项变异验证：把修复回退到修复前行为，对应用例 孤儿回收门槛 + 稀疏/损坏分支 + 旧格式形状校验 + bloom 配置透传）与
`scripts/mutation-b6.py`（**40 项**变异验证：把修复回退到修复前行为，对应用例
必须失败 —— 全部被拦住）。 必须失败 —— 全部被拦住）。
- **B-6 存储提交点（KVStore 侧止血）** — 两处 P0：① `open()` 遇损坏日志尾部会**清空整个 - **B-6 存储提交点（KVStore 侧止血）** — 两处 P0：① `open()` 遇损坏日志尾部会**清空整个
日志**（写 3 条 → 第 4 条撕裂 → 重开可见 → 再重开全空）；② 自动 checkpoint 日志**（写 3 条 → 第 4 条撕裂 → 重开可见 → 再重开全空）；② 自动 checkpoint
@@ -116,8 +135,8 @@ All notable changes to MetonaSqlark will be documented in this file.
（statements 90 / branches 82 / functions 94 / lines 93）；CI 常规 job 带 （statements 90 / branches 82 / functions 94 / lines 93）；CI 常规 job 带
`--coverage`；lint 去掉 `continue-on-error`；新增 `tests/` 类型检查 `--coverage`；lint 去掉 `continue-on-error`；新增 `tests/` 类型检查
（修复 **103 个**被 babel 剥离类型掩盖的测试类型错误）；CI 校验 dist 与源码同步。 （修复 **103 个**被 babel 剥离类型掩盖的测试类型错误）；CI 校验 dist 与源码同步。
→ 实测 Statements 90.43% / Branches 82.21% / Functions 94.27% / Lines 93.44% → 实测（v0.8.0 收尾复测）Statements 90.59% / Branches 82.59% / Functions 94.14% /
（命令与 CI 常规 job 完全一致，可复现）。 Lines 93.50%（命令与 CI 常规 job 完全一致，可复现）。
- **测试介质忠实性修正**（两处同源缺陷，此前让所有多实例/多库验证跑在错误语义上） - **测试介质忠实性修正**（两处同源缺陷，此前让所有多实例/多库验证跑在错误语义上）
- `SharedMemoryBackend` 的读缓存是每实例私有的 → 介质退化为"每实例一份快照"， - `SharedMemoryBackend` 的读缓存是每实例私有的 → 介质退化为"每实例一份快照"，
跨实例写入不可见（这正是陈旧实例覆盖新实例写入那条 bug 起初查不出来的原因）； 跨实例写入不可见（这正是陈旧实例覆盖新实例写入那条 bug 起初查不出来的原因）；
@@ -140,12 +159,130 @@ All notable changes to MetonaSqlark will be documented in this file.
→ 现构建 `dist/react.js` / `dist/vue.js` 并配套**手写精确类型声明**； → 现构建 `dist/react.js` / `dist/vue.js` 并配套**手写精确类型声明**；
补 `peerDependencies`（react / vue，均可选）。 补 `peerDependencies`（react / vue，均可选）。
### 全量回归审查（发版前最后一轮，独立复现 + 变异验证）
> 方法：四个对抗性子代理分头审查（数据正确性 / 文档宣称 vs 实现 / 公共 API 契约 /
> 测试质量），**每一条结论都要求可复现证据**；我再逐条复核并用探针确认。共确认
> 14 项实现缺陷（1 项 P0、4 项 P1、9 项 P2）与 16 条不成立的文档宣称。
**P0 · 事务活跃期间推进 WAL 水位会让已 COMMIT 的事务整批消失**
- 复现：`BEGIN` → `INSERT` → `repair()` → `COMMIT` → 崩溃 → 重开 →
已提交的行不见了，而 `getRecoveryReport()` 报告"干净"（`dataLossSuspected:false`、
`walGaps:[]`）。
- 根因：`hasPendingFlushData()` / `computeDurableLsn()` 只看 memtable/frozen，
而事务内的写入只落在 `txnSnapshot`（内存）+ WAL —— 于是"没有未落盘数据"成立，
水位被推到当前 LSN 并按该水位删掉旧分片；随后 `COMMIT` 返回成功，但那些
INSERT 记录已因 `lsn <= startLsn` 被跳过。此前只有 `CheckpointManager` 的两个
回调带事务守卫，`repair()` / `close()` / 周期 checkpoint 三条路径都能踩到。
- 修复：守卫下沉到 `computeDurableLsn()` 与 `advanceWalCheckpoint()` 入口（唯一实现），
三条路径同时覆盖；新增回归用例与变异验证（R1）。
**P1**
1. **WAL 前缀缺失丢弃整段活分片** — 前缀缺失与内部空洞被混为一谈时，
`kept = segments.filter(s => s.seq < firstGap)` 的结果为空 → 回退到上一代
manifest（`startSegment` 比现存最小分片更小）时**所有活分片被丢掉**。
现在前缀缺失单独记录（`missingPrefix`），后缀照常重放；只有"水位从未推进
（`fromLsn === 0`）"时前缀缺失才算真异常（R4）。
2. **孤儿回收门槛漏掉 LSM 层损坏** — 门槛只看引擎层 `dataLossSuspected`
（只在 WAL 无兜底时才置位），于是"manifest 已推进 + 某 SSTable 因损坏被丢"
这类真损坏下，`repair()` 仍会把"引用不到"的页面（含在途读者持有的退休文件）
当作孤儿删掉（不可逆）。现在统一用 `describeRecoveryDamage()` 聚合引擎层与
各 LSM 的全部损坏迹象（被丢的 SSTable / WAL 空洞 / 记录损坏 / 回退世代）（R3）。
3. **`vacuum()` 绕过维护链** — 逐层压缩改为 `vacuumLevels()`：每层作为维护链任务
执行（复用 `compacting` 防重入），不再与后台 compaction 并发向同一目标层写产物
（产物一律 `unshift` 到队首，层内顺序 = 新旧顺序，交错会读到旧值 / 底部层丢墓碑
导致已删除行复活）。**如实说明**：引擎层 `vacuum()` 开头的 `lsm.flush()` 本来就会
drain 维护链，所以"引擎层调用"这条路径恰好被顺带串行化 —— 真正被测试锁定的是
LSM 层不变量（R 系列未覆盖 `drainMaintenance` 那一行，它在实现上只是优化：
抢在链前重算层内文件数，去掉后仍串行，只是会多排几个空任务）。
4. **`reclaimRetiredNow()` 无视在途读者** — 读者的快照可能正持有被"退休"的文件，
强制回收会让它读不到数据（并被误判为"文件损坏"）。现在有活跃读者时退化为
延迟回收，读者退出后再物理删除（R2）。
**P2**
- WAL 记录级 CRC 损坏只打日志（`droppedWALRecords` + 数据丢失标记，R9）。
- 旧格式表结构记录的**形状**损坏（数组 / null / 非对象条目）静默当空库
→ 与坏 JSON 走同一条显式报错路径（R16）。
- **`bloomFilterBitsPerKey` 配置被接受却完全不生效**：`SSTableBuilder` 始终用默认
位数构造 Bloom Filter —— 这是实现缺陷，修的是实现（配置透传到构建器）而不是文档；
新增"位数改变落盘 bloom 段大小 + 任意位数都不产生 false negative"的测试（R17/R18）。
- `pageIdWatermark` 只做单调 max 的断言此前不存在（白盒水位回退用例，R7）。
- manifest 提交的**回读校验**此前无用例覆盖（吞写 → 必须 `ARIA_MANIFEST_WRITE_FAILED`，
且世代号不前进；覆盖"文件读不回"与"内容读回来是坏的"两条守卫，R8）。
- "文件名世代 ≠ 载荷世代"的世代无效判定无用例（R6）。
- `dropInvalidSSTable` 丢弃文件后不同步 `levels` 会留幽灵 meta；"介质读故障 ≠
文件损坏"此前无用例（读故障必须让 compaction 失败且一个 meta 都不许丢，R11）。
- 旧格式迁移的失败分支（`__aria_schemas` 坏 JSON / 非数组 / 条目形状非法）只有
坏 JSON 一条有用例。
- WAL 整体清空后"分片号绝不回退到 0"与"新写入绝不低于 manifest 水位"两条不变量
此前无用例（R13 / R14）。
**覆盖率口径（审查发现的第二处口径问题）**
- README / `jest.config.cjs` / PLAN 都声称 `collectCoverageFrom` 只排除了**两个纯类型文件**
（`engine/interface.ts`、`query/ast.ts`，"可执行语句为 0"）。审查实测：`interface.ts`
里有三个**运行时函数**（`cloneRow` / `cloneRowFallback` / `cloneRows`，约 18 条语句），
被 Memory 引擎与 AriaEngine 的读路径调用 —— 也就是说这块真实实现代码一直逃过覆盖率
统计，正是 G5 门禁要根治的"口径虚高"。
- 根因修复（而不是改文档）：实现搬到新模块 `src/engine/row_clone.ts`，
`interface.ts` 回到**纯类型**（`query/ast.ts` 本来就是）。搬完覆盖率门禁立刻**失败**
（functions 94% 阈值 → 实测 93.84%），暴露出退化路径 `cloneRowFallback` 从未被测试；
补 `tests/engine/row-clone.test.ts`（8 项：structuredClone 可用/不可用/抛错三条路径、
Date/TypedArray/ArrayBuffer、深拷贝不泄漏、批量拷贝）后门禁恢复通过。
- 最终数字（口径修正后，含新增的 8 项测试）：92 套件 / 1980 用例，
语句 90.59% / 分支 82.59% / 函数 94.14% / 行 93.50%。
**测试质量修正（"绿"不等于"有保护"）**
- 3 条空壳用例改为值级断言（孤儿回收门槛、强制回收、页面映射退休）；
- 1 条"整层文件全损坏"用例实际上走的是**缓存**（根本没读介质，等于什么都没测）
→ 拆成"介质读故障 = compaction 必须失败且不许丢 meta"与"文件真残缺 = 丢弃必须
进恢复报告"两条真用例；
- 5 秒墙钟 `Promise.race` 改为门控信号 + 失败上限（超时只会让测试失败，绝不会让
它在实现错误时"碰巧通过"）；`setTimeout` 睡眠改为 `whenIdle()` 确定性等待；
- `<=` 收紧为严格 `<`（冻结意图的水位必须**严格低于**意图起点）；删掉死代码
（`const inner`、`void manifest`）与误名的"非 JSON"用例。
### 文档订正（第二轮 G6：16 条不成立的宣称）
- **MVCC**：`site/docs.html`（表格、事务行、能力表）与 `site/demo.html` 仍写
"MVCC 快照隔离"，而实现是"版本链仅作事务内 undo + 事务串行"；`mvcc.ts` 的文件头
同样写错 → 全部改为如实描述。
- **`backup()`**：`interface.ts` 注释仍写"一致性快照" → 改为"逐表读取（非跨表快照）"。
- **WAL 空洞**：`docs.html` 写"空洞检测截断" → 改为"内部空洞如实上报并拒绝静默继续"。
- **体积**：README 与 docs.html 写"~105KB / gzip ~27KB" → 实测 min 产物
251,109 字节 / gzip 63,145 字节（`stat -c%s dist/metona-sqlark.min.js`；
`gzip -c dist/metona-sqlark.min.js | wc -c`）。
- **测试与覆盖率**：README badge/正文、site 徽标与数字卡、CHANGELOG 全部更新为
实测值（1980 / 92 套件 / 90.59% / 82.59% / 94.14% / 93.50%）。
- **存储模式**：site 仍写"5 种存储引擎" → 改为"4 种模式 + 3 种后端"；
"Tree-shakable"改为"UMD/ESM/CJS 多格式输出"（单文件 bundle + 未声明
`sideEffects`，不宜宣称可摇树）。
- **错误码表**：site 文档缺 **16 个**错误码（`ARIA_MANIFEST_NOT_LOADED`、
`ARIA_SSTABLE_SAVE_CONTRACT`、`ARIA_DB_NOT_OPEN`、`ARIA_OPEN_ERROR`、
`DB_NOT_OPEN`、`KV_*`、`TX_*`、`SAVEPOINT_*`、`UNKNOWN_STATEMENT`、
`COLUMN_EXISTS`、`FOREIGN_KEY_VIOLATION`）→ 全部补齐。
- **维护脚本与门禁**：CONTRIBUTING 的变异数量 17 → 40，并补上脚本自身的保证
（正控 / 编译失败区分 / 超时 / 逐字节恢复校验 / 进程锁）；PLAN 附录 G 的
"12 项事故级"改为 11 项（与总账 A1~A11 一致）、G4 的"零丢失"限定为"故障注入
矩阵覆盖范围内"（并记录矩阵之外发现的那处 P0）、H.1 的"25 例"改为 24 例。
### 已知限制（v0.8.0 新增/变更） ### 已知限制（v0.8.0 新增/变更）
- `backup()` 不是跨表一致性快照（逐表读取） - `backup()` 不是跨表一致性快照（逐表读取）
- 复合主键仍不支持（建表时 `SCHEMA_ERROR`） - 复合主键仍不支持（建表时 `SCHEMA_ERROR`）
- 简单 CASE 形式（`CASE <表达式> WHEN <值>`）不支持，仅支持搜索式 - 简单 CASE 形式（`CASE <表达式> WHEN <值>`）不支持，仅支持搜索式
（`CASE WHEN <条件> THEN ...`） （`CASE WHEN <条件> THEN ...`）
- **回退旧版本是单向的**：迁移后新写入只进 manifest，旧的 `__aria_lsm_meta*` /
`__aria_schemas` 停留在迁移那一刻；用旧版本打开会看到迁移时刻的旧视图
- **多实例写入依赖 Web Locks**：无 Web Locks 时降级为提交点冲突检测
（`STALE_INSTANCE`），只保证不静默覆盖别人的提交，不保证多实例写入的数据完整性
- **manifest 体积随 SSTable 数量增长**（单文件整体重写、保留两代，无增量/分层机制）
- **尾部 WAL 分片丢失无法从介质自身识别**（无"它本该存在"的证据；`ARIA_WRITE_LOST`
只兜住"有未落盘冻结表却重放不到任何记录"的情况）
## [0.7.4] - 2026-08-15 ## [0.7.4] - 2026-08-15
@@ -1096,7 +1233,7 @@ All notable changes to MetonaSqlark will be documented in this file.
- **SSTable 构建器/读取器** (`index/sstable_builder.ts`, `sstable.ts`): 二分查找 + 范围扫描 - **SSTable 构建器/读取器** (`index/sstable_builder.ts`, `sstable.ts`): 二分查找 + 范围扫描
- **Merge Iterator** (`index/merge_iterator.ts`): 最小堆多路归并，去重保留最新值 - **Merge Iterator** (`index/merge_iterator.ts`): 最小堆多路归并，去重保留最新值
- **WAL** (`wal/`): 二进制日志格式 (LSN/type/txnId/table/key/json/CRC) + Checkpoint 管理 - **WAL** (`wal/`): 二进制日志格式 (LSN/type/txnId/table/key/json/CRC) + Checkpoint 管理
- **MVCC** (`transaction/mvcc.ts`): 版本链 + 快照隔离 + GC - **MVCC** (`transaction/mvcc.ts`): 版本链 + GC（**v0.8.0 澄清**：此处当时宣称的「快照隔离」从未实现 —— 版本链仅作事务内 undo，事务串行）
- **存储后端** (`store/`): IndexedDB / Memory 双后端抽象 - **存储后端** (`store/`): IndexedDB / Memory 双后端抽象
- **LZ4 压缩** (`compression/lz4.ts`): 简易页面级压缩 - **LZ4 压缩** (`compression/lz4.ts`): 简易页面级压缩
- **`mode: 'aria'`** — 新增存储模式，可通过 `MetonaSqlark.create({ mode: 'aria' })` 激活 - **`mode: 'aria'`** — 新增存储模式，可通过 `MetonaSqlark.create({ mode: 'aria' })` 激活
CONTRIBUTING.md
+18 -3
View File
@@ -75,7 +75,7 @@ src/
├── plugin/ # Plugin system (14 lifecycle hooks) ├── plugin/ # Plugin system (14 lifecycle hooks)
└── integrations/ # React & Vue hooks └── integrations/ # React & Vue hooks
tests/ # Test suite (1304 test cases, 76 suites + 12 e2e) tests/ # Test suite (1980 test cases, 92 suites + 14 e2e)
tests/helpers/ # 共享测试工具（OPFS mock 等） tests/helpers/ # 共享测试工具（OPFS mock 等）
tests/e2e/ # Playwright e2e（真实 Chromium + OPFS） tests/e2e/ # Playwright e2e（真实 Chromium + OPFS）
site/ # Documentation site (index / docs / demo) site/ # Documentation site (index / docs / demo)
@@ -155,7 +155,7 @@ npm run build
# Output in dist/ # Output in dist/
# ├── metona-sqlark.js UMD # ├── metona-sqlark.js UMD
# ├── metona-sqlark.min.js UMD minified (~105KB / ~27KB gzip) # ├── metona-sqlark.min.js UMD minified (251,109 B / gzip 63,145 B)
# ├── metona-sqlark.esm.js ES Module # ├── metona-sqlark.esm.js ES Module
# ├── metona-sqlark.cjs CommonJS # ├── metona-sqlark.cjs CommonJS
# └── metona-sqlark.d.ts TypeScript declarations # └── metona-sqlark.d.ts TypeScript declarations
@@ -237,7 +237,7 @@ Open an issue at [git.metona.cn/MetonaTeam/MetonaSqlark/issues](https://git.meto
不会失败的用例等于没有保护。 不会失败的用例等于没有保护。
```bash ```bash
# B-6（存储单一提交点 / LSM 结构根治）17 项变异验证 # 全部 40 项变异（存储单一提交点 / LSM 结构根治 / v0.8.0 全量审查修复）
python3 scripts/mutation-b6.py python3 scripts/mutation-b6.py
# 只跑其中一条（按名字子串匹配） # 只跑其中一条（按名字子串匹配）
@@ -246,3 +246,18 @@ python3 scripts/mutation-b6.py "WAL 分片号复用"
脚本会临时改写 `src/`、运行对应用例、再恢复源码（收到 SIGINT/SIGTERM 也会恢复）， 脚本会临时改写 `src/`、运行对应用例、再恢复源码（收到 SIGINT/SIGTERM 也会恢复），
最后打印每一条是"被拦住"还是"仍然通过"。**出现任何一条"仍然通过"，本次提交不算完成。** 最后打印每一条是"被拦住"还是"仍然通过"。**出现任何一条"仍然通过"，本次提交不算完成。**
### 脚本自身的保证（v0.8.0 审查后加固）
| 机制 | 为什么需要 |
| --- | --- |
| **正控** | 先跑一遍未变异的干净基线（B-6 套件 + 分片 WAL 套件必须全绿）。没有正控就无法区分"变异被测试拦住"与"这套件本来就是红的" |
| **编译失败 ≠ 被拦住** | `Test suite failed to run` / `error TS####` 单独归类为 `BAD(变异破坏编译)`：一个把源码改成语法错误的"变异"什么都没验证 |
| **用例未匹配 ≠ 被拦住** | `Tests: 0 total` / `No tests found` 归类为 `BAD(用例未匹配)`（模式写错时最容易被误读成"测试通过了"） |
| **锚点唯一性** | 锚点在文件里出现多次时拒绝变异（否则可能改到另一处、验错位置） |
| **超时** | 单条变异 300s 上限，超时归类为 `BAD(超时)` 而不是放过 |
| **逐字节恢复校验** | 每条变异跑完用 sha256 比对恢复结果；不一致立即 `FATAL` 退出 |
| **进程锁** | `.mutation-b6.lock`（`O_EXCL`）：并发运行会互相踩掉对方的源码，直接拒绝启动 |
判定顺序固定为：编译失败 → 用例未匹配 → `✕`/`Tests: N failed`（= 被拦住）→ 其余为"仍然通过"。
只有 `OK(变异被拦住)` 计入成功，其余任何状态都会让脚本以非零退出码结束。
PLAN-v0.7.5.md
+122 -12
View File
@@ -836,7 +836,7 @@ SSTable / 跨库搬迁），必须在 `save()` 之前补校验**。
- PC-2 真崩溃注入（CDP `Page.crash`）+ OPFS `createWritable` 的两个写入窗口； - PC-2 真崩溃注入（CDP `Page.crash`）+ OPFS `createWritable` 的两个写入窗口；
- `FaultyBackend` 字节级故障注入（撕裂/bit-flip/掉电/写失败）； - `FaultyBackend` 字节级故障注入（撕裂/bit-flip/掉电/写失败）；
- **变异验证**成为回归套件的标准做法：把修复回退到修复前的行为，对应用例 - **变异验证**成为回归套件的标准做法：把修复回退到修复前的行为，对应用例
必须失败。本轮 A15/A13/A38/A39 与 **B-6 全量 17 项**均通过该检查（可执行脚本 必须失败。本轮 A15/A13/A38/A39 与 **B-6 全量 + 审查轮共 40 项**均通过该检查（可执行脚本
`scripts/mutation-b6.py`，逐项打印"变异是否被拦住"）—— `scripts/mutation-b6.py`，逐项打印"变异是否被拦住"）——
这是"测试真能拦住回归"与"测试只是陪跑"的分界线。 这是"测试真能拦住回归"与"测试只是陪跑"的分界线。
- 测试介质的两处**忠实性**缺陷已被修正（`SharedMemoryBackend` 跨实例可见性、 - 测试介质的两处**忠实性**缺陷已被修正（`SharedMemoryBackend` 跨实例可见性、
@@ -850,12 +850,12 @@ SSTable / 跨库搬迁），必须在 `save()` 之前补校验**。
| 门禁 | 内容 | 验证方式与实测结果 | 状态 | | 门禁 | 内容 | 验证方式与实测结果 | 状态 |
|---|---|---|---| |---|---|---|---|
| **G1** | 事故级缺陷全部修复，且每项有**值级**回归测试（非行数断言） | 12 项事故级（A1~A10、A15）+ 全部 P1 已修；每项均有独立回归套件，断言值/结构而非行数：`v080-sql-three-valued`（26 条 SQL 语义矩阵 × 4 引擎）、`v080-query-layer`（8 项 × 4 引擎）、`v080-column-resolution`、`v080-foreign-key`、`v080-aria-ddl-atomicity`、`v080-unified-validation`、`v080-case-expression`（54 项）、`v080-output-ordinals`（68 项）、`v080-kvstore-commit-point`、`v080-single-pipeline`、`v080-savepoint`、`v080-atomicity`、`v080-subscribe`、`v080-correlated` | ✅ | | **G1** | 事故级缺陷全部修复，且每项有**值级**回归测试（非行数断言） | 11 项事故级（A1~A11，与 §2 总账一致）+ 全部 P1 已修；每项均有独立回归套件，断言值/结构而非行数：`v080-sql-three-valued`（26 条 SQL 语义矩阵 × 4 引擎）、`v080-query-layer`（8 项 × 4 引擎）、`v080-column-resolution`、`v080-foreign-key`、`v080-aria-ddl-atomicity`、`v080-unified-validation`、`v080-case-expression`（54 项）、`v080-output-ordinals`（68 项）、`v080-kvstore-commit-point`、`v080-single-pipeline`、`v080-savepoint`、`v080-atomicity`、`v080-subscribe`、`v080-correlated` | ✅ |
| **G2** | 入口等价性：同一 SQL 经 `query`/`queryStream`/`QueryBuilder`/事务内四条入口**逐值相等** | `v080-single-pipeline`（TABLE API 与 SQL API 逐值等价，4 引擎 × 12 项 + 跨引擎 1 项，共 57 断言）；`queryStream` 与 `query` 在 16 形态 × 4 引擎逐值相等（`752bdea`）；事务内入口经同一 Executor（`b20d47b`） | ✅ | | **G2** | 入口等价性：同一 SQL 经 `query`/`queryStream`/`QueryBuilder`/事务内四条入口**逐值相等** | `v080-single-pipeline`（TABLE API 与 SQL API 逐值等价，4 引擎 × 12 项 + 跨引擎 1 项，共 57 断言）；`queryStream` 与 `query` 在 16 形态 × 4 引擎逐值相等（`752bdea`）；事务内入口经同一 Executor（`b20d47b`） | ✅ |
| **G3** | 跨引擎一致性：同 schema + 同操作在 memory/disk/hybrid/aria 行为一致（含错误码） | 全部新增套件均按 `describe.each(ENGINES)` 参数化到四引擎：`v080-unified-validation`（41）、`v080-sql-three-valued`（104）、`v080-query-layer`（111）、`v080-single-pipeline`（57）、`v080-column-resolution`（32）、`v080-foreign-key`（32）、`v080-output-ordinals`（64）、`v080-case-expression` 等；错误码断言用 `rejects.toMatchObject({ code })` | ✅ | | **G3** | 跨引擎一致性：同 schema + 同操作在 memory/disk/hybrid/aria 行为一致（含错误码） | 全部新增套件均按 `describe.each(ENGINES)` 参数化到四引擎：`v080-unified-validation`（41）、`v080-sql-three-valued`（104）、`v080-query-layer`（111）、`v080-single-pipeline`（57）、`v080-column-resolution`（32）、`v080-foreign-key`（32）、`v080-output-ordinals`（64）、`v080-case-expression` 等；错误码断言用 `rejects.toMatchObject({ code })` | ✅ |
| **G4** | 故障注入下崩溃不变量恒成立：已确认写入零丢失 + 索引与主表一致 + 唯一约束仍生效 | 单元层：`FaultyBackend`（撕裂写 / bit-flip / 掉电丢弃 / 写失败）+ `TransactionalFileStore`（pending/commit/crash 语义）+ `CrashableStoreBackend`；`v080-kvstore-commit-point`（19 项，含三处 P0 的变异验证）；`v080-atomicity`；`v080-savepoint`。e2e 层：CDP `Page.crash` 真崩溃 + OPFS `createWritable` 的 write/commit 两个窗口（`tests/e2e/opfs.spec.ts`，14 项） | ✅ | | **G4** | 故障注入下崩溃不变量恒成立（**限定于矩阵覆盖的窗口**）+ 索引与主表一致 + 唯一约束仍生效 | 单元层：`FaultyBackend`（撕裂写 / bit-flip / 掉电丢弃 / 写失败）+ `TransactionalFileStore`（pending/commit/crash 语义）+ `CrashableStoreBackend`；`v080-kvstore-commit-point`（19 项，含三处 P0 的变异验证）；`v080-atomicity`；`v080-savepoint`。e2e 层：CDP `Page.crash` 真崩溃 + OPFS `createWritable` 的 write/commit 两个窗口（`tests/e2e/opfs.spec.ts`，14 项）。<br>**⚠️ 限定说明（v0.8.0 审查修正）**：矩阵覆盖的是"介质/进程在写入窗口内崩溃"这一类故障；它**不能**证明"任何情况下零丢失"。全量回归审查在矩阵覆盖范围之外发现 1 处**已确认写入丢失**（事务活跃期间 `repair()`/checkpoint 推进 WAL 水位 → 已 COMMIT 的事务整批消失，见附录 I），已修复并补上回归测试与变异验证。因此本门禁的结论按"矩阵范围内成立"表述，不宣称普遍零丢失 | ✅（有限定） |
| **G5** | 覆盖率真实且不倒退：`collectCoverageFrom` 无实现文件被排除；CI 有 `coverageThreshold`；README 数字与产出一致 | `jest.config.cjs` 仅排除两个**纯类型**文件（`engine/interface.ts`、`query/ast.ts`）；阈值 statements 90 / branches 82 / functions 94 / lines 93；CI 常规 job 带 `--coverage`；README 写明产出命令与四个实测数字（90.43 / 82.21 / 94.27 / 93.44），且本轮经历"阈值真的失败 → 补测/删死代码"的闭环（见 `d14663e`） | ✅ | | **G5** | 覆盖率真实且不倒退：`collectCoverageFrom` 无实现文件被排除；CI 有 `coverageThreshold`；README 数字与产出一致 | `jest.config.cjs` 仅排除两个**纯类型**文件（`engine/interface.ts`、`query/ast.ts`）；阈值 statements 90 / branches 82 / functions 94 / lines 93；CI 常规 job 带 `--coverage`；README 写明产出命令与四个实测数字（最终值见 README「项目指标」表），且本轮经历"阈值真的失败 → 补测/删死代码"的闭环（见 `d14663e`） | ✅ |
| **G6** | 文档与实现一致：README/CHANGELOG/site 中每一条能力宣称都有对应测试或已删除 | §8 的 **12 条**全部收口：订阅（已接线）、LZ4 页面压缩（A38 已修）、`./migration` 导出、react/vue 产物+d.ts+peerDeps、`disconnect` 进类型、priority（改为实现符合文档）、MVCC 快照隔离（改为如实描述）、backup 一致性快照（改为如实描述并列入已知限制）、"5 种引擎"（改为 4 模式 + 3 后端）、`diskEngine` 生效范围（改为仅 aria）、"在线一致性快照"（改为全库导出）、钩子契约（CONTRIBUTING 写明返回值语义） | ✅ | | **G6** | 文档与实现一致：README/CHANGELOG/site 中每一条能力宣称都有对应测试或已删除 | **第一轮**：§8 的 **12 条**收口：订阅（已接线）、LZ4 页面压缩（A38 已修）、`./migration` 导出、react/vue 产物+d.ts+peerDeps、`disconnect` 进类型、priority（改为实现符合文档）、MVCC 快照隔离（改为如实描述）、backup 一致性快照（改为如实描述并列入已知限制）、"5 种引擎"（改为 4 模式 + 3 后端）、`diskEngine` 生效范围（改为仅 aria）、"在线一致性快照"（改为全库导出）、钩子契约（CONTRIBUTING 写明返回值语义）。<br>**第二轮（v0.8.0 全量回归审查）**：文档宣称 vs 实现逐条核对又发现 **16 条不成立**（MVCC 快照隔离、backup 一致性快照、`bloomFilterBitsPerKey` 配置项无效、gzip 体积、测试/覆盖率/套件数陈旧、错误码表缺 16 个码、WAL 空洞语义、mutation 数量、"分片号只增不减"等），全部在附录 I 中逐条订正；其中 `bloomFilterBitsPerKey` 是**实现缺陷**（配置被接受却不生效），已修实现而非改文档 | ✅（两轮） |
**额外要求**：CI lint 已去掉 `continue-on-error`（真正阻断）；`tsconfig.test.json` 对 `tests/` 做类型检查并修复了 **103 个**被 babel 剥离类型掩盖的类型错误。 ✅ **额外要求**：CI lint 已去掉 `continue-on-error`（真正阻断）；`tsconfig.test.json` 对 `tests/` 做类型检查并修复了 **103 个**被 babel 剥离类型掩盖的类型错误。 ✅
@@ -876,13 +876,14 @@ SSTable / 跨库搬迁），必须在 `save()` 之前补校验**。
| `src/engine/aria/store/manifest.ts`（新增） | `__aria_manifest_<generation>`：magic + formatVersion + generation + 头部 CRC + 载荷 CRC；`ManifestStore.load/claimOwnership/commit`；先写后验；保留两代；损坏世代**显式失败** | | `src/engine/aria/store/manifest.ts`（新增） | `__aria_manifest_<generation>`：magic + formatVersion + generation + 头部 CRC + 载荷 CRC；`ManifestStore.load/claimOwnership/commit`；先写后验；保留两代；损坏世代**显式失败** |
| `src/engine/aria/index/lsm.ts` | 冻结表一等状态（id/LSN/重试/提交窗口）；读路径 epoch + 结构版本重试；compaction 不再摘整层、底部层原地合并回收墓碑、按层 `compacting` 集合；flush/maintenance 双链；恢复报告 | | `src/engine/aria/index/lsm.ts` | 冻结表一等状态（id/LSN/重试/提交窗口）；读路径 epoch + 结构版本重试；compaction 不再摘整层、底部层原地合并回收墓碑、按层 `compacting` 集合；flush/maintenance 双链；恢复报告 |
| `src/engine/aria/index.ts` | manifest 装载 → 旧格式迁移 → 认领所有权；`commitManifest()`（唯一提交入口）；`advanceWalCheckpoint()`（先算边界 → 提交 → 再删除）；表结构随 manifest 提交；恢复报告 `getRecoveryReport()`；删除引擎层全部 `prefetch*` 依赖 | | `src/engine/aria/index.ts` | manifest 装载 → 旧格式迁移 → 认领所有权；`commitManifest()`（唯一提交入口）；`advanceWalCheckpoint()`（先算边界 → 提交 → 再删除）；表结构随 manifest 提交；恢复报告 `getRecoveryReport()`；删除引擎层全部 `prefetch*` 依赖 |
| `src/engine/aria/wal/log.ts` / `segmented_store.ts` | LSN 全库单调（manifest 记高水位）；`planKeepFrom` / `truncateBefore`；**分片号只增不减**；空洞（含前缀缺失）如实上报；按水位清理旧格式键 | | `src/engine/aria/wal/log.ts` / `segmented_store.ts` | LSN 全库单调（manifest 记高水位）；`planKeepFrom` / `truncateBefore`；**分片号绝不回退、也绝不低于 manifest 水位**（整体清空后允许复用最后用过的号 —— 见附录 I 的语义澄清）；内部空洞与记录级 CRC 损坏如实上报（`gaps` / `corruptRecords`），水位从未推进时的前缀缺失同样按空洞上报；按水位清理旧格式键 |
| `src/engine/aria/store/page_sstable_store.ts` | 活跃 + 退休两张页面映射（在途读者按 id 读取不再被 compaction 摘除影响）；`registerPageIds` | | `src/engine/aria/store/page_sstable_store.ts` | 活跃 + 退休两张页面映射（在途读者按 id 读取不再被 compaction 摘除影响）；`registerPageIds` |
| `src/engine/aria/store/file_manager.ts` | 页面水位取 manifest / 旧 meta / 现存最大 id 三者最大（单调、永不复用）；`__aria_meta` 降级为兼容提示 | | `src/engine/aria/store/file_manager.ts` | 页面水位取 manifest / 旧 meta / 现存最大 id 三者最大（单调、永不复用）；`__aria_meta` 降级为兼容提示 |
| `src/engine/aria/index/sstable.ts` | 三份解析循环合并为 `iterEntries()` 一份，越界策略统一 | | `src/engine/aria/index/sstable.ts` | 三份解析循环合并为 `iterEntries()` 一份，越界策略统一 |
| `src/engine/aria/index/merge_iterator.ts` | 胜出来源的补充推迟到下一次 `next()`（提前终止不多算） | | `src/engine/aria/index/merge_iterator.ts` | 胜出来源的补充推迟到下一次 `next()`（提前终止不多算） |
| `src/engine/aria/wal/checkpoint.ts` | checkpoint 只落 memtable（`flushMemtables?`），不等 compaction | | `src/engine/aria/wal/checkpoint.ts` | checkpoint 只落 memtable（`flushMemtables?`），不等 compaction |
| `tests/v080-b6-single-commit-point.test.ts`（新增 63 项） | 上述每一条的回归 + manifest 严格校验表驱动 25 例；`scripts/mutation-b6.py`（22 项变异验证，全部被拦住） | | `tests/v080-b6-single-commit-point.test.ts` | 上述每一条的回归 + manifest 严格校验表驱动 **24** 例；v0.8.0 审查后扩到 **96 项**（新增事务水位 P0、前缀空洞语义、在途读者与退休文件、孤儿回收门槛、稀疏/损坏分支、形状校验等）|
| `scripts/mutation-b6.py` | **40 项**变异验证（B-6 的 22 项 + 审查轮的 18 项），全部被对应用例拦住；脚本自带正控、编译失败区分、超时、逐字节恢复校验与进程锁（见 CONTRIBUTING）|
### H.2 提交顺序（唯一不变量） ### H.2 提交顺序（唯一不变量）
@@ -920,10 +921,10 @@ __aria_manifest_<gen> 提交（单文件原子写 + 回读校验）
### H.4 验收（可复现） ### H.4 验收（可复现）
```bash ```bash
# 1) B-6 回归（63 项） # 1) B-6 回归（96 项）
npx jest tests/v080-b6-single-commit-point.test.ts npx jest tests/v080-b6-single-commit-point.test.ts
# 2) 变异验证：把每个修复回退到修复前行为，对应用例必须失败（22 项） # 2) 变异验证：把每个修复回退到修复前行为，对应用例必须失败（40 项）
python3 scripts/mutation-b6.py python3 scripts/mutation-b6.py
# 3) 随机压力 / 检查点崩溃恢复（发现缺陷 1 的套件） # 3) 随机压力 / 检查点崩溃恢复（发现缺陷 1 的套件）
@@ -933,13 +934,122 @@ npx jest tests/engine/aria-repair-hardening.test.ts tests/engine/aria-kv-backend
npx jest --testPathIgnorePatterns='/node_modules/|/tests/e2e/|aria-prod-load|kvstore-stress|aria-matrix-audit|aria-idx-flush-race' npx jest --testPathIgnorePatterns='/node_modules/|/tests/e2e/|aria-prod-load|kvstore-stress|aria-matrix-audit|aria-idx-flush-race'
``` ```
**实测数字**：常规套件 **1935 通过 / 91 套件**；覆盖率 语句 90.34% / 分支 82.16% / **实测数字**（审查轮收尾复测，详见附录 I）：常规套件 **1980 通过 / 92 套件**；
函数 94.06% / 行 93.23%（阈值 90/82/94/93，全部通过）。 覆盖率 语句 90.59% / 分支 82.59% / 函数 94.14% / 行 93.50%（阈值 90/82/94/93，全部通过）；
e2e 14/14；变异验证 **40/40** 被拦住。
**恢复报告**：`engine.getRecoveryReport()` 返回 **恢复报告**：`engine.getRecoveryReport()` 返回
`{droppedSSTables, dataLossSuspected, walGaps, legacyImported, manifestFallback}` —— `{droppedSSTables, dataLossSuspected, walGaps, droppedWALRecords, legacyImported, manifestFallback}` ——
"损坏被自愈了多少、有没有真正丢数据"从此是**可读的返回值**，而不是只能翻日志。 "损坏被自愈了多少、有没有真正丢数据"从此是**可读的返回值**，而不是只能翻日志。
**新增错误码**：`ARIA_MANIFEST_CORRUPT`、`ARIA_MANIFEST_WRITE_FAILED`、 **新增错误码**：`ARIA_MANIFEST_CORRUPT`、`ARIA_MANIFEST_WRITE_FAILED`、
`ARIA_MANIFEST_NOT_LOADED`、`ARIA_LEGACY_META_CORRUPT`、`ARIA_SSTABLE_READ_FAILED`、 `ARIA_MANIFEST_NOT_LOADED`、`ARIA_LEGACY_META_CORRUPT`、`ARIA_SSTABLE_READ_FAILED`、
`ARIA_SSTABLE_SAVE_CONTRACT`、`ARIA_WAL_GAP`、`ARIA_WRITE_LOST`、`STALE_INSTANCE`。 `ARIA_SSTABLE_SAVE_CONTRACT`、`ARIA_WAL_GAP`、`ARIA_WRITE_LOST`、`STALE_INSTANCE`。
---
## 附录 I · v0.8.0 全量回归审查（发版前最后一轮）
> 触发：用户要求"做完整全量的回归 review"。方法：**四个对抗性子代理**分头审查
> （① 数据正确性与崩溃语义 ② 文档宣称 vs 实现 ③ 公共 API 契约 ④ 测试质量与
> 覆盖盲区），每一条结论都要求**可复现证据**；我再逐条复核、写探针确认、并在
> `src/` 上做**变异验证**（把修复回退 → 对应用例必须失败）。
> 详细缺陷叙述见 `CHANGELOG.md` 的 v0.8.0「全量回归审查」一节；本节只列结论与证据。
### I.1 确认缺陷（14 项：1×P0 / 4×P1 / 9×P2）
| 级别 | 缺陷 | 证据（可复现） | 变异 |
| --- | --- | --- | --- |
| **P0** | 事务活跃期间 `repair()` / `close()` / 周期 checkpoint 推进 WAL 水位 → 已 `COMMIT` 的事务整批消失，且恢复报告"干净" | `tests/v080-b6-single-commit-point.test.ts` ›「BEGIN → INSERT → repair() → COMMIT → 崩溃」；根因 `hasPendingFlushData()` 不看 `txnSnapshot` | R1 |
| P1 | WAL 前缀缺失把**整段活分片**丢掉（回退上一代 manifest 时 `kept` 为空） | 同套件「fromLsn > 0 时前缀缺失只记诊断，后缀分片照常重放」 | R4 |
| P1 | 孤儿回收门槛只看引擎层 `dataLossSuspected` → LSM 层丢过 SSTable 时仍会删"引用不到"的活页（不可逆） | 「有损坏迹象时：引用不到的东西一律保留」；统一判定 `describeRecoveryDamage()` | R3 |
| P1 | `vacuum()` 逐层压缩绕过维护链（与后台 compaction 并发写同一目标层） | 「vacuumLevels 的逐层压缩必须挂在维护链上」；**注意**：引擎层 `vacuum()` 的 `flush()` 已会 drain 维护链，故该用例锁定的是 LSM 层不变量 | — |
| P1 | `reclaimRetiredNow()` 无视在途读者（读者把"已退休"读成"文件损坏"） | 「有在途读者时强制回收必须退化为延迟回收」 | R2 |
| P2 | WAL 记录级 CRC 损坏只打日志（恢复报告无感） | 「一条记录 CRC 失败 → corruptRecords > 0 且标记丢数据」 | R9 |
| P2 | 旧格式表结构记录**形状**损坏（数组 / null / 非对象条目）静默当空库 | 「旧格式表结构记录的形状校验」5 条 | R16 |
| P2 | **`bloomFilterBitsPerKey` 配置被接受却完全不生效**（构建器写死默认位数） | 「bloomFilterBitsPerKey 必须真的生效」2 条（段大小 + 无 false negative） | R17 / R18 |
| P2 | 丢弃损坏文件后不同步内存层数组（幽灵 meta） | 「compaction 丢弃损坏文件后 levels 不留幽灵 meta」 | R5 |
| P2 | 介质读故障被折叠成"文件损坏"的路径无用例 | 「介质读故障 ≠ 文件损坏：compaction 必须失败且一个 meta 都不许丢」 | R11 |
| P2 | manifest 回读校验两条守卫无用例（吞写 / 内容坏） | 「写成功但读不回来」「写下去的内容读回来是坏的」 | R8 |
| P2 | "文件名世代 ≠ 载荷世代"的世代无效判定无用例 | 「文件名世代与载荷世代不一致 → 该世代无效」 | R6 |
| P2 | `pageIdWatermark` 单调性无用例（水位可回退 → 页面 id 复用） | 「水位是单调下限：计数器回退也不许把 manifest 水位带回低值」 | R7 |
| P2 | 分片号两条真实不变量无用例（清空后不回退到 0 / 新写入不低于 manifest 水位） | 「整体清空后分片号绝不回退」「写入永不落到 manifest 水位下限之下」 | R13 / R14 |
**语义澄清（不是缺陷，但此前文档与实现不一致）**：
- **"分片号只增不减"** 的准确语义是"**绝不回退、绝不低于 manifest 水位**"，
整体清空（`truncate()`）后允许复用**最后用过的那个号** —— 记录自带 LSN，
旧世代记录按水位跳过，因此复用安全；真正致命的是"回退到 0"（新记录落在
`startSegment` 之下 → 恢复时被过滤掉）。已同步 README / H.1 / CHANGELOG。
- **尾部 WAL 分片丢失**无法从介质自身识别（没有"它本该存在"的证据），
`ARIA_WRITE_LOST` 只兜住"有未落盘冻结表却重放不到任何记录"的情况 —— 已写入已知限制。
- **`vacuumLevels()` 里 `drainMaintenance()` 那一行未被变异验证**：它在实现上只是
优化（抢在链前重算层内文件数），去掉后仍然串行，只是会多排几个空任务。
### I.2 测试质量修正（"绿"≠"有保护"）
- 3 条空壳用例（孤儿回收门槛 / 强制回收 / 页面映射退休）改为**值级断言**；
- 1 条"整层文件全损坏"用例实际**走的是缓存**（从未读介质）→ 拆成两条真用例
（介质读故障 / 文件真残缺）；
- 5 秒墙钟 `Promise.race` → 门控信号 + **失败上限**（超时只让测试失败，
不会让它在实现错误时"碰巧通过"）；`setTimeout` 睡眠 → `whenIdle()` 确定性等待；
- `<=` 收紧为严格 `<`（冻结意图水位必须**严格低于**意图起点）；
- 删除死代码（`const inner` / `void manifest`）与误名的"非 JSON"用例。
### I.2b 覆盖率口径的第二处漏洞（已根因修复）
审查发现 README / `jest.config.cjs` / 本附录 G5 都声称"只排除两个纯类型文件、
可执行语句为 0"，但 `engine/interface.ts` 内含三个运行时函数
（`cloneRow` / `cloneRowFallback` / `cloneRows`）并被 Memory 引擎与 AriaEngine 调用
—— 即真实实现代码一直在覆盖率统计之外（与 G5 声称根治的问题同类）。
处理：实现搬到 `src/engine/row_clone.ts`，`interface.ts` 变回纯类型；
搬完后门禁**真的失败了**（functions 93.84% < 94%），被迫补测退化路径
（`tests/engine/row-clone.test.ts`，8 项），随后全绿。这是"口径修正 → 门禁真的咬人"的闭环。
### I.3 文档订正（第二轮 G6：16 条不成立的宣称）
MVCC 快照隔离（docs.html ×3 + demo.html + `mvcc.ts` 文件头）、`backup()`
"一致性快照"（`interface.ts` 注释）、"空洞检测截断"、"~105KB / gzip ~27KB"
（实测 251,109 字节 / gzip 63,145 字节）、测试与覆盖率数字（README badge/正文、site 徽标与数字卡、
CHANGELOG）、"5 种存储引擎"（→ 4 模式 + 3 后端）、"Tree-shakable"（→ 多格式输出）、
错误码表缺 **16 个**码、CONTRIBUTING 变异数量（17 → 40）、PLAN 附录 G 的
"12 项事故级"（→ 11 项，A1~A11）、G4"零丢失"（限定为矩阵覆盖范围内）、
H.1"25 例"（→ 24 例）、"分片号只增不减"（→ 准确语义）。
**第二轮核对（独立子代理，只读审计）**：修正后再做一次"宣称 vs 实现"逐条核对，
又发现 11 条不一致（CONTRIBUTING 的旧体积/旧测试数、README 的"空洞检测截断"残留、
`getRecoveryReport()` 字段枚举漏 `droppedWALRecords`、PLAN 的 94-vs-96、
CHANGELOG 历史段落的"快照隔离"表述、docs.html 缺记录级 CRC 上报、
以及上面 I.2b 的覆盖率口径问题）——**全部已订正**，其中覆盖率口径是改实现而非改文档。
### I.4 验证（v0.8.0 收尾复测，全部可复现）
```bash
# 1) B-6 + 分片 WAL 套件（96 + 15 项）
npx jest tests/v080-b6-single-commit-point.test.ts tests/engine/aria-wal-segment.test.ts
# 2) 全量常规套件（不含重型与 e2e）
npx jest --testPathIgnorePatterns='/node_modules/|/tests/e2e/|aria-prod-load|kvstore-stress|aria-matrix-audit|aria-idx-flush-race'
# → 92 套件 / 1980 用例全绿
# 3) 覆盖率（与 CI 常规 job 完全相同的命令）
npx jest --coverage --coverageReporters=text-summary --testPathIgnorePatterns='/node_modules/|/tests/e2e/|aria-prod-load|kvstore-stress|aria-matrix-audit|aria-idx-flush-race'
# → Statements 90.59% / Branches 82.59% / Functions 94.14% / Lines 93.50%（阈值 90/82/94/93）
# 4) e2e（真实 Chromium + 真实 OPFS + CDP Page.crash）
npx playwright test # → 14/14
# 5) 变异验证（40 项；脚本自带正控、编译失败区分、超时、逐字节恢复校验、进程锁）
python3 scripts/mutation-b6.py # → 40/40 全部被拦住
# 6) 静态门禁
npm run lint && npx tsc -p tsconfig.json --noEmit && npx tsc -p tsconfig.test.json --noEmit
```
### I.5 未修复 / 保留项（诚实清单）
| 项 | 现状 | 为什么保留 |
| --- | --- | --- |
| e2e 未覆盖"manifest 写入窗口"崩溃 | 现有 e2e 覆盖 OPFS 的 `write()`/`commit()` 两个窗口（数据文件），未按**文件名**门控 manifest 的写入窗口 | 需要 harness 支持按 key 名门控 OPFS 写（`getFileHandle` 名追踪 + `armCrashOnOpfsWrite({file})`）；收益有限（manifest 的先写后验 + 两代保留已在单测层用字节级损坏覆盖） |
| `clearAll()` 重置 `manifest.namespaces` 时 `nextSstableId` 归零 | 页面水位保留（媒体可能仍有页面），SSTable 编号在介质已清空的前提下重新开始 | 介质被整体抹掉，编号复用无冲突对象；真要严格只需把 `nextSstableId` 也纳入单调水位 —— 当前无收益 |
| 无 Web Locks 环境的多实例并发写 | 降级为提交点冲突检测（`STALE_INSTANCE`），**不支持**并发写 | 客户端没有跨标签页互斥原语时无法保证；已写入已知限制 |
| manifest 体积随 SSTable 数增长 | 单文件整体重写 + 保留两代，无增量/分层 | 属设计取舍（单一提交点的代价），已写入已知限制；收敛手段是 `vacuum()` 合并层级 |
README.md
+43 -17
View File
@@ -3,8 +3,8 @@
<p align="center"> <p align="center">
<img src="https://img.shields.io/badge/version-0.8.0-blue?style=flat-square" alt="version"> <img src="https://img.shields.io/badge/version-0.8.0-blue?style=flat-square" alt="version">
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license"> <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
<img src="https://img.shields.io/badge/coverage-90.34%25%20stmts-brightgreen?style=flat-square" alt="coverage"> <img src="https://img.shields.io/badge/coverage-90.59%25%20stmts-brightgreen?style=flat-square" alt="coverage">
<img src="https://img.shields.io/badge/tests-1935%20passed-success?style=flat-square" alt="tests"> <img src="https://img.shields.io/badge/tests-1980%20passed-success?style=flat-square" alt="tests">
</p> </p>
> 基于 TypeScript 的**前端关系型数据库**：完整 SQL + Query Builder 双 API， > 基于 TypeScript 的**前端关系型数据库**：完整 SQL + Query Builder 双 API，
@@ -55,7 +55,7 @@
**生产级可靠性** **生产级可靠性**
- **崩溃恢复** — WAL 原子写入 + CRC-32 完整性校验（SSTable 整文件 + WAL 记录）、空洞检测截断、打开时损坏自愈、`repair()` 清理重建 - **崩溃恢复** — WAL 原子写入 + CRC-32 完整性校验（SSTable 整文件 + WAL 记录）、分片空洞与记录损坏**如实上报**（`ARIA_WAL_GAP` / `droppedWALRecords`，拒绝静默截断）、打开时损坏自愈、`repair()` 清理重建
- **全库加密** — AES-256-GCM 透明加密（PBKDF2 密钥派生 + 密码验证 + 篡改检测），`encryption.password` 一键启用 - **全库加密** — AES-256-GCM 透明加密（PBKDF2 密钥派生 + 密码验证 + 篡改检测），`encryption.password` 一键启用
- **多标签页独占锁** — Web Locks API，第二个标签页打开同一库抛 `ARIA_LOCKED` - **多标签页独占锁** — Web Locks API，第二个标签页打开同一库抛 `ARIA_LOCKED`
- **数据安全** — 输入校验（`required` / `maxLength` / `min` / `max`）、SQL 注入防护、Bloom Filter 快速否定 - **数据安全** — 输入校验（`required` / `maxLength` / `min` / `max`）、SQL 注入防护、Bloom Filter 快速否定
@@ -91,7 +91,7 @@ npm install @metona-team/metona-sqlark
<script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script> <script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script>
``` ```
或从 [`dist/`](./dist/) 下载：`metona-sqlark.js`（UMD 开发版）/ `metona-sqlark.min.js`（压缩版，gzip ~27KB）/ `metona-sqlark.esm.js` / `metona-sqlark.cjs` / `metona-sqlark.d.ts` 或从 [`dist/`](./dist/) 下载：`metona-sqlark.js`（UMD 开发版）/ `metona-sqlark.min.js`（压缩版：实测 251,109 字节 / gzip 63,145 字节）/ `metona-sqlark.esm.js` / `metona-sqlark.cjs` / `metona-sqlark.d.ts`
--- ---
@@ -371,9 +371,9 @@ const rows = await db.query('SELECT * FROM users');
|------|------| |------|------|
| **LSM-Tree** | MemTable（红黑树）→ 多级 SSTable，异步 Compaction（从存储兜底加载），写背压 | | **LSM-Tree** | MemTable（红黑树）→ 多级 SSTable，异步 Compaction（从存储兜底加载），写背压 |
| **页面化存储** | SSTable 存为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），`pageStorage` 在 opfs/kv 后端默认启用 | | **页面化存储** | SSTable 存为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），`pageStorage` 在 opfs/kv 后端默认启用 |
| **WAL** | 分片文件 `__wal_%06d.bin` + 真追加；标准 CRC32 记录校验；full/batch/none 三模式；**LSN 全库单调**（manifest 记高水位）；分片号只增不减；空洞（含前缀缺失）显式上报 `ARIA_WAL_GAP`；16MB 阈值自动 checkpoint（活跃事务期间不截断） | | **WAL** | 分片文件 `__wal_%06d.bin` + 真追加；标准 CRC32 记录校验（记录级 CRC 失败会计数并上报 `droppedWALRecords`）；full/batch/none 三模式；**LSN 全库单调**（manifest 记高水位）；分片号**绝不回退、也绝不低于 manifest 水位**（整体清空后允许复用最后用过的号）；内部空洞与记录损坏显式上报（`gaps` / `corruptRecords`），水位从未推进时的前缀缺失同样按空洞上报，水位已推进时前缀缺失视为"已清理的前缀"；16MB 阈值自动 checkpoint（活跃事务期间不截断） |
| **单一提交点** | `__aria_manifest_<gen>`：页面水位 + 各命名空间 SSTable 元数据 + 表结构 + WAL 起始位置 + 待落盘冻结表意图，一次原子提交（头部/载荷双 CRC，先写后验，保留两代）。顺序固定为**数据落盘 → manifest 提交 → 才允许截断 WAL / 删除旧文件**；恢复只认最后一份 CRC 通过的世代，元数据损坏抛 `ARIA_MANIFEST_CORRUPT`（不再静默当空库） | | **单一提交点** | `__aria_manifest_<gen>`：页面水位 + 各命名空间 SSTable 元数据 + 表结构 + WAL 起始位置 + 待落盘冻结表意图，一次原子提交（头部/载荷双 CRC，先写后验，保留两代）。顺序固定为**数据落盘 → manifest 提交 → 才允许截断 WAL / 删除旧文件**；恢复只认最后一份 CRC 通过的世代，元数据损坏抛 `ARIA_MANIFEST_CORRUPT`（不再静默当空库） |
| **崩溃恢复** | 打开时完整性校验（整文件 CRC-32；**介质读故障不再被当成"文件不存在"**，抛 `ARIA_SSTABLE_READ_FAILED` 且不误删元数据）、按 LSN 水位重放 WAL、恢复后自动重建二级索引；`getRecoveryReport()` 返回 `{droppedSSTables, dataLossSuspected, walGaps, legacyImported, manifestFallback}`；`repair()` 只在 manifest 健康时回收孤儿页面 | | **崩溃恢复** | 打开时完整性校验（整文件 CRC-32；**介质读故障不再被当成"文件不存在"**，抛 `ARIA_SSTABLE_READ_FAILED` 且不误删元数据）、按 LSN 水位重放 WAL、恢复后自动重建二级索引；`getRecoveryReport()` 返回 `{droppedSSTables, dataLossSuspected, walGaps, droppedWALRecords, legacyImported, manifestFallback}`；`repair()` 只在 manifest 健康时回收孤儿页面 |
| **Compaction** | 整层合并不再"先摘层再合并"（合并期间该层对读者始终可见）；底部层原地合并**回收墓碑**（删除密集场景空间不再无界增长）；按层 `compacting` 集合（跨层触发不丢失）；被取代的 SSTable 进入**退休表**，等更早的读者退出后才物理删除 | | **Compaction** | 整层合并不再"先摘层再合并"（合并期间该层对读者始终可见）；底部层原地合并**回收墓碑**（删除密集场景空间不再无界增长）；按层 `compacting` 集合（跨层触发不丢失）；被取代的 SSTable 进入**退休表**，等更早的读者退出后才物理删除 |
| **全库加密** | `encryption.password` → EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）；PBKDF2 派生 + salt 持久化；密码错误/篡改 → `ARIA_DECRYPT_ERROR` | | **全库加密** | `encryption.password` → EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）；PBKDF2 派生 + salt 持久化；密码错误/篡改 → `ARIA_DECRYPT_ERROR` |
| **MVCC** | 版本链仅作事务内 undo（提交即清理，**无快照隔离**；事务串行）；自动 GC | | **MVCC** | 版本链仅作事务内 undo（提交即清理，**无快照隔离**；事务串行）；自动 GC |
@@ -391,6 +391,7 @@ const rows = await db.query('SELECT * FROM users');
| `memtableSizeThreshold` | `number` | `4MB` | MemTable 刷盘阈值 | | `memtableSizeThreshold` | `number` | `4MB` | MemTable 刷盘阈值 |
| `levelSizeMultiplier` | `number` | `10` | LSM 层级容量倍数 | | `levelSizeMultiplier` | `number` | `10` | LSM 层级容量倍数 |
| `bloomFilterBitsPerKey` | `number` | `10` | Bloom Filter 每 key 位数 | | `bloomFilterBitsPerKey` | `number` | `10` | Bloom Filter 每 key 位数 |
| `maxMemoryMB` | `number` | `64` | 内存预算（MB）：主 LSM 估算内存超限时触发 flush + MVCC GC |
| `walEnabled` | `boolean` | `true` | 是否启用 WAL | | `walEnabled` | `boolean` | `true` | 是否启用 WAL |
| `walSyncMode` | `'full' \| 'batch' \| 'none'` | `'full'` | WAL 同步模式 | | `walSyncMode` | `'full' \| 'batch' \| 'none'` | `'full'` | WAL 同步模式 |
| `checkpointInterval` | `number` | `1000` | Checkpoint 间隔（操作数） | | `checkpointInterval` | `number` | `1000` | Checkpoint 间隔（操作数） |
@@ -422,7 +423,7 @@ const { data, loading, error, refresh } = useSqlarkQuery(db, 'SELECT * FROM user
npm install # 安装依赖 npm install # 安装依赖
npm run dev # 开发模式（localhost:3001） npm run dev # 开发模式（localhost:3001）
npm run build # 生产构建（生成 dist/） npm run build # 生产构建（生成 dist/）
npm test # 运行测试（1935 用例 · 91 套件；+4 个重型套件） npm test # 运行测试（1980 用例 · 92 套件；+4 个重型套件）
python3 scripts/mutation-b6.py # 变异验证：把 B-6 的修复逐项回退，对应用例必须失败 python3 scripts/mutation-b6.py # 变异验证：把 B-6 的修复逐项回退，对应用例必须失败
npm run test:e2e # Playwright e2e（真实 Chromium + OPFS + 崩溃注入，需先 build） npm run test:e2e # Playwright e2e（真实 Chromium + OPFS + 崩溃注入，需先 build）
npm run lint # 代码检查 npm run lint # 代码检查
@@ -435,11 +436,11 @@ npm run typecheck # 类型检查
| 指标 | 数值 | | 指标 | 数值 |
|------|------| |------|------|
| 测试用例 | 1935（91 套件）+ 14 Playwright e2e，另 4 个重型套件在独立 CI job 串行运行 | | 测试用例 | 1980（92 套件）+ 14 Playwright e2e，另 4 个重型套件在独立 CI job 串行运行 |
| 语句覆盖率 | 90.34%（8391/9288） | | 语句覆盖率 | 90.59%（8532/9418） |
| 分支覆盖率 | 82.16%（4367/5315） | | 分支覆盖率 | 82.59%（4452/5390） |
| 函数覆盖率 | 94.06%（1204/1280） | | 函数覆盖率 | 94.14%（1223/1299） |
| 行覆盖率 | 93.23%（7606/8158） | | 行覆盖率 | 93.50%（7727/8264） |
| SQL 关键字 | 72 | | SQL 关键字 | 72 |
| 存储模式 | 4（`memory` / `disk` / `hybrid` / `aria`） | | 存储模式 | 4（`memory` / `disk` / `hybrid` / `aria`） |
| 存储后端 | 3（OPFS / KVStore / Memory），Aria 引擎另有 LSM-Tree + WAL + 页面化 | | 存储后端 | 3（OPFS / KVStore / Memory），Aria 引擎另有 LSM-Tree + WAL + 页面化 |
@@ -447,7 +448,10 @@ npm run typecheck # 类型检查
> **覆盖率口径**：`collectCoverageFrom = src/**/*.ts`，仅排除两个**纯类型声明**文件 > **覆盖率口径**：`collectCoverageFrom = src/**/*.ts`，仅排除两个**纯类型声明**文件
> （`engine/interface.ts`、`query/ast.ts` —— 它们只有 interface/type，可执行语句为 0， > （`engine/interface.ts`、`query/ast.ts` —— 它们只有 interface/type，可执行语句为 0，
> 纳入统计只会稀释分母）。CI 常规 job 带 `--coverage` 运行， > 纳入统计只会稀释分母）。v0.8.0 审查曾发现 `interface.ts` 里混着三个运行时函数
> （`cloneRow`/`cloneRowFallback`/`cloneRows`）—— 已搬到 `src/engine/row_clone.ts`
> 并纳入统计（搬完门禁立刻因 functions 93.84% < 94% 失败，补测退化路径后通过）。
> CI 常规 job 带 `--coverage` 运行，
> `jest.config.cjs` 的 `coverageThreshold` 为 statements 90 / branches 82 / > `jest.config.cjs` 的 `coverageThreshold` 为 statements 90 / branches 82 /
> functions 94 / lines 93，任一项不达标即失败 —— **门槛不达标不允许发版**。 > functions 94 / lines 93，任一项不达标即失败 —— **门槛不达标不允许发版**。
> >
@@ -462,9 +466,13 @@ npm run typecheck # 类型检查
- **存储布局在 v0.8.0 变更** — 元数据从"每个命名空间一份裸 JSON"（`__aria_lsm_meta*` / - **存储布局在 v0.8.0 变更** — 元数据从"每个命名空间一份裸 JSON"（`__aria_lsm_meta*` /
`__aria_schemas`）收敛为 `__aria_manifest_<generation>`（带世代号与双 CRC）。 `__aria_schemas`）收敛为 `__aria_manifest_<generation>`（带世代号与双 CRC）。
旧库**首次用 v0.8.0 打开时自动迁移**（旧键保留不删，可回退旧版本），迁移遇到损坏 旧库**首次用 v0.8.0 打开时自动迁移**（旧键保留不删），迁移遇到损坏的旧元数据会
的旧元数据会明确报 `ARIA_LEGACY_META_CORRUPT` 而不是当成空库。直接读取这些内部 明确报 `ARIA_LEGACY_META_CORRUPT` 而不是当成空库。直接读取这些内部 key 的外部
key 的外部脚本需要跟着改（引擎侧无公开 API 依赖它们）。 脚本需要跟着改（引擎侧无公开 API 依赖它们）。
* **回退是单向的**：迁移后所有新写入只进 manifest，旧的 `__aria_lsm_meta*` /
`__aria_schemas` 停留在迁移那一刻。用旧版本打开同一个库会看到**迁移时刻的旧
视图**（不是"数据都在"），继续写入还会让两套布局分叉 —— 需要回退旧版本时，
先用 v0.8.0 导出数据，不要指望旧键是新数据的镜像。
- **单列主键** — 复合主键暂不支持（建表时显式 `SCHEMA_ERROR`），列入 v0.8 路线图 - **单列主键** — 复合主键暂不支持（建表时显式 `SCHEMA_ERROR`），列入 v0.8 路线图
- **写语句关联引用** — UPDATE/DELETE 的 WHERE 支持非关联子查询（`IN (SELECT)` / 标量子查询），关联引用（`$col` / 关联 EXISTS）显式抛 `NOT_SUPPORTED`（不静默） - **写语句关联引用** — UPDATE/DELETE 的 WHERE 支持非关联子查询（`IN (SELECT)` / 标量子查询），关联引用（`$col` / 关联 EXISTS）显式抛 `NOT_SUPPORTED`（不静默）
- **`backup()` 不是跨表一致性快照** — 实现为**逐表读取**（Aria 走引擎级 `backup()`， - **`backup()` 不是跨表一致性快照** — 实现为**逐表读取**（Aria 走引擎级 `backup()`，
@@ -476,6 +484,23 @@ npm run typecheck # 类型检查
- **建表 UNIQUE 约束** — 不可经 `DROP INDEX` 解除（对齐 SQLite，需重建表）；仅 `CREATE UNIQUE INDEX` 添加的约束可随索引删除 - **建表 UNIQUE 约束** — 不可经 `DROP INDEX` 解除（对齐 SQLite，需重建表）；仅 `CREATE UNIQUE INDEX` 添加的约束可随索引删除
- **唯一值交换更新** — 同一语句内两行互换唯一列值（A:x→y, B:y→x）保守拒绝（最终状态合法但报 `UNIQUE_VIOLATION`） - **唯一值交换更新** — 同一语句内两行互换唯一列值（A:x→y, B:y→x）保守拒绝（最终状态合法但报 `UNIQUE_VIOLATION`）
- **主键非空** — 主键列强制非空（SQL 语义 PK 隐含 NOT NULL），`INSERT`/`UPDATE` 置 null/undefined 抛 `VALIDATION_ERROR` - **主键非空** — 主键列强制非空（SQL 语义 PK 隐含 NOT NULL），`INSERT`/`UPDATE` 置 null/undefined 抛 `VALIDATION_ERROR`
- **多实例写入保护依赖 Web Locks** — AriaEngine 用 Web Locks 做库级独占：第二个实例
打开同一个库时抛 `ARIA_LOCKED`，这是**唯一受支持**的多标签页写入方式。运行环境
没有 Web Locks 时该保护会自动降级为"提交点冲突检测"（manifest 世代号单调 + 提交前
检查是否存在别的实例提交的更新世代 → 抛 `STALE_INSTANCE`），但降级只保证
**不静默覆盖别人的提交**，不保证多实例写入的数据完整性：被拒绝的那一方此前
已写入自己 WAL 分片的记录，可能被胜出实例的 checkpoint 当作可回收前缀清掉。
结论：**不要在没有 Web Locks 的环境里让两个实例同时写同一个库**；需要并发访问时
由应用层串行化（如 SharedWorker / 主标签页代理）。
- **manifest 体积随 SSTable 数量增长** — 单一提交点把全部命名空间的 SSTable 元数据
（键范围、页面 id 列表、大小）+ 表结构 + WAL 水位写进**同一个文件**，每次提交
整体重写（保留两代）。因此元数据量与已落盘 SSTable 数成正比：长期高频写入、
层级很多且迟迟不合并的库，其 manifest 会明显大于数据本身之外的一般预期。当前
没有"元数据分层/增量"机制，`vacuum()` 合并层级是唯一的收敛手段（列入后续版本）。
- **尾部 WAL 分片丢失无法从介质自身识别** — 分片内部空洞（中间缺号）与记录级 CRC
损坏都会被上报；但如果**最后一个**分片整个消失，介质上没有任何"它本该存在"的证据
（manifest 只记 `startSegment`/`nextLsn`，不记最后分片号），此时只能靠
`ARIA_WRITE_LOST`（有未落盘冻结表却重放不到任何记录）兜住"确定丢数据"的情况。
### 浏览器兼容性 ### 浏览器兼容性
@@ -487,7 +512,8 @@ npm run typecheck # 类型检查
| Node.js | 16+ | ✅ | ✅（内存介质） | ✅（内存介质） | | Node.js | 16+ | ✅ | ✅（内存介质） | ✅（内存介质） |
> **OPFS**：基础 API（`createWritable` 原子写）在 Chromium 102+ / Firefox 111+ / Safari 15.2+ 均支持。 > **OPFS**：基础 API（`createWritable` 原子写）在 Chromium 102+ / Firefox 111+ / Safari 15.2+ 均支持。
> 无跨文件事务，AriaEngine 以 WAL 分片单文件原子写 + 空洞检测截断保证崩溃一致性。 > 无跨文件事务，AriaEngine 以 WAL 分片单文件原子写 + manifest 单一提交点保证崩溃一致性；
> 分片空洞与记录级损坏都会被**显式上报**（恢复报告 + 告警），不做静默截断。
> >
> **多标签页保护**：AriaEngine 通过 Web Locks 获取库级独占锁，第二个标签页打开同一库抛 `ARIA_LOCKED`。 > **多标签页保护**：AriaEngine 通过 Web Locks 获取库级独占锁，第二个标签页打开同一库抛 `ARIA_LOCKED`。
dist/metona-sqlark.cjs
Vendored
+365 -75
View File
@@ -320,12 +320,15 @@ function stripUndefined(updates) {
} }
/** /**
* metona-sqlark Engine Interface — 存储引擎抽象接口 * metona-sqlark — 行所有权（row ownership）工具
* @module engine/interface * @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/ */
// ---------------------------------------------------------------------------
// v0.8.0: 行所有权（row ownership）约定
// ---------------------------------------------------------------------------
/** /**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 * 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
* *
@@ -337,12 +340,18 @@ function stripUndefined(updates) {
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是 * 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。 * 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
* *
* 约定（写入 interface 文档，所有引擎必须遵守）： * 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部， * **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。 * 也不得持有调用方传入的行对象引用。
* *
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）； * 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。 * 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/ */
function cloneRow(row) { function cloneRow(row) {
if (row === null || typeof row !== 'object') if (row === null || typeof row !== 'object')
@@ -4856,9 +4865,18 @@ const SSTABLE_MAGIC_V1 = 0x53535442;
const SSTABLE_MAGIC_V2 = 0x53535443; const SSTABLE_MAGIC_V2 = 0x53535443;
const SSTABLE_FOOTER_SIZE = 32; const SSTABLE_FOOTER_SIZE = 32;
class SSTableBuilder { class SSTableBuilder {
constructor(blockSizeLimit = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(blockSizeLimit = 4096, bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY) {
this.entries = []; this.entries = [];
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
add(key, value) { add(key, value) {
@@ -4878,7 +4896,7 @@ class SSTableBuilder {
valueBytes: encoder.encode(JSON.stringify(value)), valueBytes: encoder.encode(JSON.stringify(value)),
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
const blockOffsets = []; const blockOffsets = [];
@@ -5498,6 +5516,8 @@ const BACKPRESSURE_FILES = 8;
* 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。 * 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// LSM // LSM
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -5565,6 +5585,9 @@ class LSM {
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && config.bloomBitsPerKey > 0
? Math.floor(config.bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -5767,7 +5790,7 @@ class LSM {
return; return;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -5863,6 +5886,45 @@ class LSM {
} }
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels() {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level))
await this.drainMaintenance();
if (this.levels[level].length < minFiles)
continue;
this.compacting.add(level);
await new Promise((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles))
compacted++;
}
finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
enqueueCompact(level) { enqueueCompact(level) {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level))
@@ -5986,6 +6048,45 @@ class LSM {
} }
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders() {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds)
out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas)
out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle() {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount() { getRetiredCount() {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -5999,6 +6100,13 @@ class LSM {
reclaimRetiredNow() { reclaimRetiredNow() {
if (this.retired.length === 0) if (this.retired.length === 0)
return; return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -6214,7 +6322,7 @@ class LSM {
return true; return true;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -6384,6 +6492,11 @@ class LSM {
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -6544,6 +6657,13 @@ class LSM {
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
async dropInvalidSSTable(meta, reason) { async dropInvalidSSTable(meta, reason) {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -6819,10 +6939,12 @@ class WAL {
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data; let data;
let gaps = []; let gaps = [];
let missingPrefix = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} }
else { else {
const exists = await this.store.exists(); const exists = await this.store.exists();
@@ -6834,7 +6956,8 @@ class WAL {
throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` + throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` +
'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP'); 'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP');
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -6853,7 +6976,11 @@ class WAL {
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
/** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */ /** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */
@@ -6989,6 +7116,7 @@ class WAL {
} }
decodeAllRecords(data) { decodeAllRecords(data) {
const records = []; const records = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
while (offset + 15 <= data.byteLength) { while (offset + 15 <= data.byteLength) {
@@ -7033,7 +7161,10 @@ class WAL {
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -7052,7 +7183,7 @@ class WAL {
break; break;
} }
} }
return records; return { records, corrupt };
} }
} }
@@ -7151,25 +7282,36 @@ class SegmentedWALStore {
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment = 0) { async readAllFrom(fromSegment = 0, fromLsn = 0) {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) for (let missing = fromSegment; missing < segments[0].seq; missing++)
gaps.push(missing); missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -7235,6 +7377,7 @@ class SegmentedWALStore {
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -7247,8 +7390,14 @@ class SegmentedWALStore {
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -7289,8 +7438,11 @@ class SegmentedWALStore {
*/ */
async planKeepFrom(durableLsn, latestLsn) { async planKeepFrom(durableLsn, latestLsn) {
const segments = await this.listSegments(); const segments = await this.listSegments();
// v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) if (segments.length === 0)
return 0; return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
// - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -7343,9 +7495,9 @@ class SegmentedWALStore {
} }
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
const obsolete = segments.filter((s) => s.seq < keepFrom); const obsolete = segments.filter((s) => s.seq < keepFrom);
@@ -8942,8 +9094,11 @@ class ManifestStore {
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// MVCCManager // MVCCManager
@@ -9485,6 +9640,7 @@ class AriaEngine {
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -9664,6 +9820,15 @@ class AriaEngine {
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)');
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -9920,27 +10085,34 @@ class AriaEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
async cleanupOrphanPages() { async cleanupOrphanPages() {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + console.warn(`[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)'); 'unreferenced data is kept, never deleted blindly');
return;
}
// v0.8.0（review 修复）：**有在途读者时一律不回收**。
// 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
// 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return; return;
} }
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
if (pgKeys.length === 0)
return;
const used = new Set(); const used = new Set();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds)
for (const pid of m.pageIds) for (const pid of m.pageIds)
used.add(pid); used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) if (meta.pageIds)
@@ -9948,7 +10120,11 @@ class AriaEngine {
used.add(pid); used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds())
used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -9957,6 +10133,48 @@ class AriaEngine {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables)
usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level)
usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds())
usedSstIds.add(id);
}
const orphanSstKeys = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m)
continue;
if (!usedSstIds.has(Number(m[1])))
orphanSstKeys.push(key);
}
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
sstableKeyPrefixes() {
const out = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main')
out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
getLsmLevels(lsm) { getLsmLevels(lsm) {
@@ -11281,6 +11499,47 @@ class AriaEngine {
async persistSchemas() { async persistSchemas() {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
parseSchemaRecord(raw, source) {
let parsed;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
}
catch (error) {
throw new DatabaseError(`${source} is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
validateSchemaShape(parsed, source) {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, 'ARIA_LEGACY_META_CORRUPT');
}
const out = {};
for (const [tableName, columns] of Object.entries(parsed)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`, 'ARIA_LEGACY_META_CORRUPT');
}
for (const [colName, def] of Object.entries(columns)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`, 'ARIA_LEGACY_META_CORRUPT');
}
}
out[tableName] = columns;
}
return out;
}
async loadSchemas() { async loadSchemas() {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -11289,17 +11548,9 @@ class AriaEngine {
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
}
catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError(`Schema record is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error); data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
} this.manifest.schemas = data;
} }
} }
for (const [tableName, columns] of Object.entries(data)) { for (const [tableName, columns] of Object.entries(data)) {
@@ -11311,6 +11562,40 @@ class AriaEngine {
// ======================================================================= // =======================================================================
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
describeRecoveryDamage() {
const reasons = [];
if (this.recoveryReport.manifestFallback)
reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected)
reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected)
reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -11333,6 +11618,7 @@ class AriaEngine {
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -11436,6 +11722,18 @@ class AriaEngine {
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
computeDurableLsn(intents) { computeDurableLsn(intents) {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null)
return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -11451,6 +11749,15 @@ class AriaEngine {
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
async advanceWalCheckpoint() { async advanceWalCheckpoint() {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)');
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -11520,17 +11827,10 @@ class AriaEngine {
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)); this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
}
catch (error) {
throw new DatabaseError(`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) { if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) {
@@ -11563,9 +11863,6 @@ class AriaEngine {
return; // WAL 覆盖到了这些数据（重放会重建） return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) if (!this.config.walEnabled)
return; // 未启用 WAL：本来就没有日志兜底（配置语义） return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0)
return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` + throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` +
'but no WAL record was replayed — confirmed writes are missing ' + 'but no WAL record was replayed — confirmed writes are missing ' +
@@ -12139,18 +12436,11 @@ class AriaEngine {
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level) => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles)
continue;
if (await this.lsm.compactLevel(level, minFiles))
compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
dist/metona-sqlark.cjs.map
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
dist/metona-sqlark.d.ts
Vendored
+38 -1
View File
@@ -341,7 +341,13 @@ interface IStorageEngine {
rollbackToSavepoint?(name: string): Promise<void>; rollbackToSavepoint?(name: string): Promise<void>;
/** 释放 Savepoint */ /** 释放 Savepoint */
releaseSavepoint?(name: string): Promise<void>; releaseSavepoint?(name: string): Promise<void>;
/** 在线备份：导出全库一致性快照 */ /**
* 在线备份：导出全库数据快照。
*
* v0.8.0（review 修正文档）：返回的是**调用时刻逐表读取的结果**，不构成
* "跨表一致性快照" —— 实现没有冻结全局版本（读取期间不会有并发写入时结果
* 是一致的，但并发写入下不同表可能落在不同时间点）。
*/
backup?(): Promise<Record<string, Record<string, unknown>[]>>; backup?(): Promise<Record<string, Record<string, unknown>[]>>;
/** 崩溃恢复自愈：校验并清理损坏数据、恢复一致性（检测到异常后调用，无需删库重建） */ /** 崩溃恢复自愈：校验并清理损坏数据、恢复一致性（检测到异常后调用，无需删库重建） */
repair?(): Promise<void>; repair?(): Promise<void>;
@@ -1652,6 +1658,8 @@ interface AriaRecoveryReport {
dataLossSuspected: boolean; dataLossSuspected: boolean;
/** WAL 活跃区间内的分片空洞（已提交事务记录缺失） */ /** WAL 活跃区间内的分片空洞（已提交事务记录缺失） */
walGaps: number[]; walGaps: number[];
/** v0.8.0：CRC 校验失败被跳过的 WAL 记录数（它们承载的写入已丢失） */
droppedWALRecords: number;
/** 本次打开是否从旧格式（__aria_lsm_meta/__aria_schemas）迁移而来 */ /** 本次打开是否从旧格式（__aria_lsm_meta/__aria_schemas）迁移而来 */
legacyImported: boolean; legacyImported: boolean;
/** 是否从更早的 manifest 世代回退（最新世代损坏） */ /** 是否从更早的 manifest 世代回退（最新世代损坏） */
@@ -1739,6 +1747,8 @@ declare class AriaEngine implements IStorageEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
private cleanupOrphanPages; private cleanupOrphanPages;
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
private sstableKeyPrefixes;
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
private getLsmLevels; private getLsmLevels;
/** /**
@@ -1860,7 +1870,34 @@ declare class AriaEngine implements IStorageEngine {
* 数据里没有"或反之的分裂状态。现在两者在同一次原子提交里生效。 * 数据里没有"或反之的分裂状态。现在两者在同一次原子提交里生效。
*/ */
private persistSchemas; private persistSchemas;
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
private parseSchemaRecord;
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
private validateSchemaShape;
private loadSchemas; private loadSchemas;
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
private describeRecoveryDamage;
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
dist/metona-sqlark.esm.js
Vendored
+365 -75
View File
@@ -316,12 +316,15 @@ function stripUndefined(updates) {
} }
/** /**
* metona-sqlark Engine Interface — 存储引擎抽象接口 * metona-sqlark — 行所有权（row ownership）工具
* @module engine/interface * @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/ */
// ---------------------------------------------------------------------------
// v0.8.0: 行所有权（row ownership）约定
// ---------------------------------------------------------------------------
/** /**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 * 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
* *
@@ -333,12 +336,18 @@ function stripUndefined(updates) {
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是 * 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。 * 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
* *
* 约定（写入 interface 文档，所有引擎必须遵守）： * 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部， * **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。 * 也不得持有调用方传入的行对象引用。
* *
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）； * 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。 * 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/ */
function cloneRow(row) { function cloneRow(row) {
if (row === null || typeof row !== 'object') if (row === null || typeof row !== 'object')
@@ -4852,9 +4861,18 @@ const SSTABLE_MAGIC_V1 = 0x53535442;
const SSTABLE_MAGIC_V2 = 0x53535443; const SSTABLE_MAGIC_V2 = 0x53535443;
const SSTABLE_FOOTER_SIZE = 32; const SSTABLE_FOOTER_SIZE = 32;
class SSTableBuilder { class SSTableBuilder {
constructor(blockSizeLimit = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(blockSizeLimit = 4096, bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY) {
this.entries = []; this.entries = [];
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
add(key, value) { add(key, value) {
@@ -4874,7 +4892,7 @@ class SSTableBuilder {
valueBytes: encoder.encode(JSON.stringify(value)), valueBytes: encoder.encode(JSON.stringify(value)),
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
const blockOffsets = []; const blockOffsets = [];
@@ -5494,6 +5512,8 @@ const BACKPRESSURE_FILES = 8;
* 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。 * 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// LSM // LSM
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -5561,6 +5581,9 @@ class LSM {
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && config.bloomBitsPerKey > 0
? Math.floor(config.bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -5763,7 +5786,7 @@ class LSM {
return; return;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -5859,6 +5882,45 @@ class LSM {
} }
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels() {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level))
await this.drainMaintenance();
if (this.levels[level].length < minFiles)
continue;
this.compacting.add(level);
await new Promise((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles))
compacted++;
}
finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
enqueueCompact(level) { enqueueCompact(level) {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level))
@@ -5982,6 +6044,45 @@ class LSM {
} }
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders() {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds)
out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas)
out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle() {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount() { getRetiredCount() {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -5995,6 +6096,13 @@ class LSM {
reclaimRetiredNow() { reclaimRetiredNow() {
if (this.retired.length === 0) if (this.retired.length === 0)
return; return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -6210,7 +6318,7 @@ class LSM {
return true; return true;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -6380,6 +6488,11 @@ class LSM {
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -6540,6 +6653,13 @@ class LSM {
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
async dropInvalidSSTable(meta, reason) { async dropInvalidSSTable(meta, reason) {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -6815,10 +6935,12 @@ class WAL {
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data; let data;
let gaps = []; let gaps = [];
let missingPrefix = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} }
else { else {
const exists = await this.store.exists(); const exists = await this.store.exists();
@@ -6830,7 +6952,8 @@ class WAL {
throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` + throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` +
'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP'); 'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP');
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -6849,7 +6972,11 @@ class WAL {
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
/** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */ /** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */
@@ -6985,6 +7112,7 @@ class WAL {
} }
decodeAllRecords(data) { decodeAllRecords(data) {
const records = []; const records = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
while (offset + 15 <= data.byteLength) { while (offset + 15 <= data.byteLength) {
@@ -7029,7 +7157,10 @@ class WAL {
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -7048,7 +7179,7 @@ class WAL {
break; break;
} }
} }
return records; return { records, corrupt };
} }
} }
@@ -7147,25 +7278,36 @@ class SegmentedWALStore {
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment = 0) { async readAllFrom(fromSegment = 0, fromLsn = 0) {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) for (let missing = fromSegment; missing < segments[0].seq; missing++)
gaps.push(missing); missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -7231,6 +7373,7 @@ class SegmentedWALStore {
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -7243,8 +7386,14 @@ class SegmentedWALStore {
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -7285,8 +7434,11 @@ class SegmentedWALStore {
*/ */
async planKeepFrom(durableLsn, latestLsn) { async planKeepFrom(durableLsn, latestLsn) {
const segments = await this.listSegments(); const segments = await this.listSegments();
// v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) if (segments.length === 0)
return 0; return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
// - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -7339,9 +7491,9 @@ class SegmentedWALStore {
} }
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
const obsolete = segments.filter((s) => s.seq < keepFrom); const obsolete = segments.filter((s) => s.seq < keepFrom);
@@ -8938,8 +9090,11 @@ class ManifestStore {
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// MVCCManager // MVCCManager
@@ -9481,6 +9636,7 @@ class AriaEngine {
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -9660,6 +9816,15 @@ class AriaEngine {
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)');
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -9916,27 +10081,34 @@ class AriaEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
async cleanupOrphanPages() { async cleanupOrphanPages() {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + console.warn(`[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)'); 'unreferenced data is kept, never deleted blindly');
return;
}
// v0.8.0（review 修复）：**有在途读者时一律不回收**。
// 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
// 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return; return;
} }
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
if (pgKeys.length === 0)
return;
const used = new Set(); const used = new Set();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds)
for (const pid of m.pageIds) for (const pid of m.pageIds)
used.add(pid); used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) if (meta.pageIds)
@@ -9944,7 +10116,11 @@ class AriaEngine {
used.add(pid); used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds())
used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -9953,6 +10129,48 @@ class AriaEngine {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables)
usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level)
usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds())
usedSstIds.add(id);
}
const orphanSstKeys = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m)
continue;
if (!usedSstIds.has(Number(m[1])))
orphanSstKeys.push(key);
}
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
sstableKeyPrefixes() {
const out = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main')
out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
getLsmLevels(lsm) { getLsmLevels(lsm) {
@@ -11277,6 +11495,47 @@ class AriaEngine {
async persistSchemas() { async persistSchemas() {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
parseSchemaRecord(raw, source) {
let parsed;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
}
catch (error) {
throw new DatabaseError(`${source} is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
validateSchemaShape(parsed, source) {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, 'ARIA_LEGACY_META_CORRUPT');
}
const out = {};
for (const [tableName, columns] of Object.entries(parsed)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`, 'ARIA_LEGACY_META_CORRUPT');
}
for (const [colName, def] of Object.entries(columns)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`, 'ARIA_LEGACY_META_CORRUPT');
}
}
out[tableName] = columns;
}
return out;
}
async loadSchemas() { async loadSchemas() {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -11285,17 +11544,9 @@ class AriaEngine {
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
}
catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError(`Schema record is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error); data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
} this.manifest.schemas = data;
} }
} }
for (const [tableName, columns] of Object.entries(data)) { for (const [tableName, columns] of Object.entries(data)) {
@@ -11307,6 +11558,40 @@ class AriaEngine {
// ======================================================================= // =======================================================================
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
describeRecoveryDamage() {
const reasons = [];
if (this.recoveryReport.manifestFallback)
reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected)
reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected)
reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -11329,6 +11614,7 @@ class AriaEngine {
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -11432,6 +11718,18 @@ class AriaEngine {
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
computeDurableLsn(intents) { computeDurableLsn(intents) {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null)
return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -11447,6 +11745,15 @@ class AriaEngine {
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
async advanceWalCheckpoint() { async advanceWalCheckpoint() {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)');
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -11516,17 +11823,10 @@ class AriaEngine {
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)); this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
}
catch (error) {
throw new DatabaseError(`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) { if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) {
@@ -11559,9 +11859,6 @@ class AriaEngine {
return; // WAL 覆盖到了这些数据（重放会重建） return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) if (!this.config.walEnabled)
return; // 未启用 WAL：本来就没有日志兜底（配置语义） return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0)
return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` + throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` +
'but no WAL record was replayed — confirmed writes are missing ' + 'but no WAL record was replayed — confirmed writes are missing ' +
@@ -12135,18 +12432,11 @@ class AriaEngine {
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level) => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles)
continue;
if (await this.lsm.compactLevel(level, minFiles))
compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
dist/metona-sqlark.esm.js.map
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
dist/metona-sqlark.js
Vendored
+365 -75
View File
@@ -322,12 +322,15 @@
} }
/** /**
* metona-sqlark Engine Interface — 存储引擎抽象接口 * metona-sqlark — 行所有权（row ownership）工具
* @module engine/interface * @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/ */
// ---------------------------------------------------------------------------
// v0.8.0: 行所有权（row ownership）约定
// ---------------------------------------------------------------------------
/** /**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 * 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
* *
@@ -339,12 +342,18 @@
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是 * 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。 * 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
* *
* 约定（写入 interface 文档，所有引擎必须遵守）： * 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部， * **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。 * 也不得持有调用方传入的行对象引用。
* *
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）； * 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。 * 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/ */
function cloneRow(row) { function cloneRow(row) {
if (row === null || typeof row !== 'object') if (row === null || typeof row !== 'object')
@@ -4858,9 +4867,18 @@
const SSTABLE_MAGIC_V2 = 0x53535443; const SSTABLE_MAGIC_V2 = 0x53535443;
const SSTABLE_FOOTER_SIZE = 32; const SSTABLE_FOOTER_SIZE = 32;
class SSTableBuilder { class SSTableBuilder {
constructor(blockSizeLimit = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(blockSizeLimit = 4096, bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY) {
this.entries = []; this.entries = [];
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
add(key, value) { add(key, value) {
@@ -4880,7 +4898,7 @@
valueBytes: encoder.encode(JSON.stringify(value)), valueBytes: encoder.encode(JSON.stringify(value)),
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
const blockOffsets = []; const blockOffsets = [];
@@ -5500,6 +5518,8 @@
* 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。 * 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// LSM // LSM
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -5567,6 +5587,9 @@
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && config.bloomBitsPerKey > 0
? Math.floor(config.bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -5769,7 +5792,7 @@
return; return;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -5865,6 +5888,45 @@
} }
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels() {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level))
await this.drainMaintenance();
if (this.levels[level].length < minFiles)
continue;
this.compacting.add(level);
await new Promise((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles))
compacted++;
}
finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
enqueueCompact(level) { enqueueCompact(level) {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level))
@@ -5988,6 +6050,45 @@
} }
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders() {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds)
out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas)
out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle() {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount() { getRetiredCount() {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -6001,6 +6102,13 @@
reclaimRetiredNow() { reclaimRetiredNow() {
if (this.retired.length === 0) if (this.retired.length === 0)
return; return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -6216,7 +6324,7 @@
return true; return true;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -6386,6 +6494,11 @@
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -6546,6 +6659,13 @@
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
async dropInvalidSSTable(meta, reason) { async dropInvalidSSTable(meta, reason) {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -6821,10 +6941,12 @@
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data; let data;
let gaps = []; let gaps = [];
let missingPrefix = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} }
else { else {
const exists = await this.store.exists(); const exists = await this.store.exists();
@@ -6836,7 +6958,8 @@
throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` + throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` +
'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP'); 'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP');
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -6855,7 +6978,11 @@
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
/** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */ /** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */
@@ -6991,6 +7118,7 @@
} }
decodeAllRecords(data) { decodeAllRecords(data) {
const records = []; const records = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
while (offset + 15 <= data.byteLength) { while (offset + 15 <= data.byteLength) {
@@ -7035,7 +7163,10 @@
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -7054,7 +7185,7 @@
break; break;
} }
} }
return records; return { records, corrupt };
} }
} }
@@ -7153,25 +7284,36 @@
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment = 0) { async readAllFrom(fromSegment = 0, fromLsn = 0) {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) for (let missing = fromSegment; missing < segments[0].seq; missing++)
gaps.push(missing); missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -7237,6 +7379,7 @@
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -7249,8 +7392,14 @@
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -7291,8 +7440,11 @@
*/ */
async planKeepFrom(durableLsn, latestLsn) { async planKeepFrom(durableLsn, latestLsn) {
const segments = await this.listSegments(); const segments = await this.listSegments();
// v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) if (segments.length === 0)
return 0; return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
// - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -7345,9 +7497,9 @@
} }
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
const obsolete = segments.filter((s) => s.seq < keepFrom); const obsolete = segments.filter((s) => s.seq < keepFrom);
@@ -8944,8 +9096,11 @@
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// MVCCManager // MVCCManager
@@ -9487,6 +9642,7 @@
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -9666,6 +9822,15 @@
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)');
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -9922,27 +10087,34 @@
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
async cleanupOrphanPages() { async cleanupOrphanPages() {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + console.warn(`[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)'); 'unreferenced data is kept, never deleted blindly');
return;
}
// v0.8.0（review 修复）：**有在途读者时一律不回收**。
// 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
// 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return; return;
} }
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
if (pgKeys.length === 0)
return;
const used = new Set(); const used = new Set();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds)
for (const pid of m.pageIds) for (const pid of m.pageIds)
used.add(pid); used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) if (meta.pageIds)
@@ -9950,7 +10122,11 @@
used.add(pid); used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds())
used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -9959,6 +10135,48 @@
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables)
usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level)
usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds())
usedSstIds.add(id);
}
const orphanSstKeys = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m)
continue;
if (!usedSstIds.has(Number(m[1])))
orphanSstKeys.push(key);
}
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
sstableKeyPrefixes() {
const out = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main')
out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
getLsmLevels(lsm) { getLsmLevels(lsm) {
@@ -11283,6 +11501,47 @@
async persistSchemas() { async persistSchemas() {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
parseSchemaRecord(raw, source) {
let parsed;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
}
catch (error) {
throw new DatabaseError(`${source} is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
validateSchemaShape(parsed, source) {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, 'ARIA_LEGACY_META_CORRUPT');
}
const out = {};
for (const [tableName, columns] of Object.entries(parsed)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`, 'ARIA_LEGACY_META_CORRUPT');
}
for (const [colName, def] of Object.entries(columns)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`, 'ARIA_LEGACY_META_CORRUPT');
}
}
out[tableName] = columns;
}
return out;
}
async loadSchemas() { async loadSchemas() {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -11291,17 +11550,9 @@
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
}
catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError(`Schema record is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error); data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
} this.manifest.schemas = data;
} }
} }
for (const [tableName, columns] of Object.entries(data)) { for (const [tableName, columns] of Object.entries(data)) {
@@ -11313,6 +11564,40 @@
// ======================================================================= // =======================================================================
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
describeRecoveryDamage() {
const reasons = [];
if (this.recoveryReport.manifestFallback)
reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected)
reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected)
reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -11335,6 +11620,7 @@
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -11438,6 +11724,18 @@
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
computeDurableLsn(intents) { computeDurableLsn(intents) {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null)
return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -11453,6 +11751,15 @@
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
async advanceWalCheckpoint() { async advanceWalCheckpoint() {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)');
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -11522,17 +11829,10 @@
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)); this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
}
catch (error) {
throw new DatabaseError(`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) { if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) {
@@ -11565,9 +11865,6 @@
return; // WAL 覆盖到了这些数据（重放会重建） return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) if (!this.config.walEnabled)
return; // 未启用 WAL：本来就没有日志兜底（配置语义） return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0)
return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` + throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` +
'but no WAL record was replayed — confirmed writes are missing ' + 'but no WAL record was replayed — confirmed writes are missing ' +
@@ -12141,18 +12438,11 @@
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level) => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles)
continue;
if (await this.lsm.compactLevel(level, minFiles))
compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
dist/metona-sqlark.js.map
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
dist/metona-sqlark.min.js
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
dist/react.js
Vendored
+365 -75
View File
@@ -314,12 +314,15 @@ function stripUndefined(updates) {
} }
/** /**
* metona-sqlark Engine Interface — 存储引擎抽象接口 * metona-sqlark — 行所有权（row ownership）工具
* @module engine/interface * @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/ */
// ---------------------------------------------------------------------------
// v0.8.0: 行所有权（row ownership）约定
// ---------------------------------------------------------------------------
/** /**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 * 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
* *
@@ -331,12 +334,18 @@ function stripUndefined(updates) {
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是 * 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。 * 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
* *
* 约定（写入 interface 文档，所有引擎必须遵守）： * 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部， * **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。 * 也不得持有调用方传入的行对象引用。
* *
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）； * 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。 * 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/ */
function cloneRow(row) { function cloneRow(row) {
if (row === null || typeof row !== 'object') if (row === null || typeof row !== 'object')
@@ -4850,9 +4859,18 @@ const SSTABLE_MAGIC_V1 = 0x53535442;
const SSTABLE_MAGIC_V2 = 0x53535443; const SSTABLE_MAGIC_V2 = 0x53535443;
const SSTABLE_FOOTER_SIZE = 32; const SSTABLE_FOOTER_SIZE = 32;
class SSTableBuilder { class SSTableBuilder {
constructor(blockSizeLimit = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(blockSizeLimit = 4096, bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY) {
this.entries = []; this.entries = [];
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
add(key, value) { add(key, value) {
@@ -4872,7 +4890,7 @@ class SSTableBuilder {
valueBytes: encoder.encode(JSON.stringify(value)), valueBytes: encoder.encode(JSON.stringify(value)),
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
const blockOffsets = []; const blockOffsets = [];
@@ -5492,6 +5510,8 @@ const BACKPRESSURE_FILES = 8;
* 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。 * 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// LSM // LSM
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -5559,6 +5579,9 @@ class LSM {
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && config.bloomBitsPerKey > 0
? Math.floor(config.bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -5761,7 +5784,7 @@ class LSM {
return; return;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -5857,6 +5880,45 @@ class LSM {
} }
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels() {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level))
await this.drainMaintenance();
if (this.levels[level].length < minFiles)
continue;
this.compacting.add(level);
await new Promise((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles))
compacted++;
}
finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
enqueueCompact(level) { enqueueCompact(level) {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level))
@@ -5980,6 +6042,45 @@ class LSM {
} }
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders() {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds)
out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas)
out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle() {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount() { getRetiredCount() {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -5993,6 +6094,13 @@ class LSM {
reclaimRetiredNow() { reclaimRetiredNow() {
if (this.retired.length === 0) if (this.retired.length === 0)
return; return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -6208,7 +6316,7 @@ class LSM {
return true; return true;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -6378,6 +6486,11 @@ class LSM {
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -6538,6 +6651,13 @@ class LSM {
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
async dropInvalidSSTable(meta, reason) { async dropInvalidSSTable(meta, reason) {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -6813,10 +6933,12 @@ class WAL {
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data; let data;
let gaps = []; let gaps = [];
let missingPrefix = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} }
else { else {
const exists = await this.store.exists(); const exists = await this.store.exists();
@@ -6828,7 +6950,8 @@ class WAL {
throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` + throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` +
'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP'); 'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP');
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -6847,7 +6970,11 @@ class WAL {
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
/** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */ /** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */
@@ -6983,6 +7110,7 @@ class WAL {
} }
decodeAllRecords(data) { decodeAllRecords(data) {
const records = []; const records = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
while (offset + 15 <= data.byteLength) { while (offset + 15 <= data.byteLength) {
@@ -7027,7 +7155,10 @@ class WAL {
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -7046,7 +7177,7 @@ class WAL {
break; break;
} }
} }
return records; return { records, corrupt };
} }
} }
@@ -7145,25 +7276,36 @@ class SegmentedWALStore {
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment = 0) { async readAllFrom(fromSegment = 0, fromLsn = 0) {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) for (let missing = fromSegment; missing < segments[0].seq; missing++)
gaps.push(missing); missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -7229,6 +7371,7 @@ class SegmentedWALStore {
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -7241,8 +7384,14 @@ class SegmentedWALStore {
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -7283,8 +7432,11 @@ class SegmentedWALStore {
*/ */
async planKeepFrom(durableLsn, latestLsn) { async planKeepFrom(durableLsn, latestLsn) {
const segments = await this.listSegments(); const segments = await this.listSegments();
// v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) if (segments.length === 0)
return 0; return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
// - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -7337,9 +7489,9 @@ class SegmentedWALStore {
} }
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
const obsolete = segments.filter((s) => s.seq < keepFrom); const obsolete = segments.filter((s) => s.seq < keepFrom);
@@ -8936,8 +9088,11 @@ class ManifestStore {
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// MVCCManager // MVCCManager
@@ -9479,6 +9634,7 @@ class AriaEngine {
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -9658,6 +9814,15 @@ class AriaEngine {
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)');
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -9914,27 +10079,34 @@ class AriaEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
async cleanupOrphanPages() { async cleanupOrphanPages() {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + console.warn(`[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)'); 'unreferenced data is kept, never deleted blindly');
return;
}
// v0.8.0（review 修复）：**有在途读者时一律不回收**。
// 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
// 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return; return;
} }
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
if (pgKeys.length === 0)
return;
const used = new Set(); const used = new Set();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds)
for (const pid of m.pageIds) for (const pid of m.pageIds)
used.add(pid); used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) if (meta.pageIds)
@@ -9942,7 +10114,11 @@ class AriaEngine {
used.add(pid); used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds())
used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -9951,6 +10127,48 @@ class AriaEngine {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables)
usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level)
usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds())
usedSstIds.add(id);
}
const orphanSstKeys = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m)
continue;
if (!usedSstIds.has(Number(m[1])))
orphanSstKeys.push(key);
}
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
sstableKeyPrefixes() {
const out = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main')
out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
getLsmLevels(lsm) { getLsmLevels(lsm) {
@@ -11275,6 +11493,47 @@ class AriaEngine {
async persistSchemas() { async persistSchemas() {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
parseSchemaRecord(raw, source) {
let parsed;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
}
catch (error) {
throw new DatabaseError(`${source} is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
validateSchemaShape(parsed, source) {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, 'ARIA_LEGACY_META_CORRUPT');
}
const out = {};
for (const [tableName, columns] of Object.entries(parsed)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`, 'ARIA_LEGACY_META_CORRUPT');
}
for (const [colName, def] of Object.entries(columns)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`, 'ARIA_LEGACY_META_CORRUPT');
}
}
out[tableName] = columns;
}
return out;
}
async loadSchemas() { async loadSchemas() {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -11283,17 +11542,9 @@ class AriaEngine {
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
}
catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError(`Schema record is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error); data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
} this.manifest.schemas = data;
} }
} }
for (const [tableName, columns] of Object.entries(data)) { for (const [tableName, columns] of Object.entries(data)) {
@@ -11305,6 +11556,40 @@ class AriaEngine {
// ======================================================================= // =======================================================================
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
describeRecoveryDamage() {
const reasons = [];
if (this.recoveryReport.manifestFallback)
reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected)
reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected)
reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -11327,6 +11612,7 @@ class AriaEngine {
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -11430,6 +11716,18 @@ class AriaEngine {
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
computeDurableLsn(intents) { computeDurableLsn(intents) {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null)
return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -11445,6 +11743,15 @@ class AriaEngine {
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
async advanceWalCheckpoint() { async advanceWalCheckpoint() {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)');
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -11514,17 +11821,10 @@ class AriaEngine {
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)); this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
}
catch (error) {
throw new DatabaseError(`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) { if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) {
@@ -11557,9 +11857,6 @@ class AriaEngine {
return; // WAL 覆盖到了这些数据（重放会重建） return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) if (!this.config.walEnabled)
return; // 未启用 WAL：本来就没有日志兜底（配置语义） return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0)
return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` + throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` +
'but no WAL record was replayed — confirmed writes are missing ' + 'but no WAL record was replayed — confirmed writes are missing ' +
@@ -12133,18 +12430,11 @@ class AriaEngine {
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level) => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles)
continue;
if (await this.lsm.compactLevel(level, minFiles))
compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
dist/react.js.map
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
dist/vue.js
Vendored
+365 -75
View File
@@ -314,12 +314,15 @@ function stripUndefined(updates) {
} }
/** /**
* metona-sqlark Engine Interface — 存储引擎抽象接口 * metona-sqlark — 行所有权（row ownership）工具
* @module engine/interface * @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/ */
// ---------------------------------------------------------------------------
// v0.8.0: 行所有权（row ownership）约定
// ---------------------------------------------------------------------------
/** /**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 * 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
* *
@@ -331,12 +334,18 @@ function stripUndefined(updates) {
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是 * 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。 * 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
* *
* 约定（写入 interface 文档，所有引擎必须遵守）： * 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部， * **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。 * 也不得持有调用方传入的行对象引用。
* *
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）； * 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。 * 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/ */
function cloneRow(row) { function cloneRow(row) {
if (row === null || typeof row !== 'object') if (row === null || typeof row !== 'object')
@@ -4850,9 +4859,18 @@ const SSTABLE_MAGIC_V1 = 0x53535442;
const SSTABLE_MAGIC_V2 = 0x53535443; const SSTABLE_MAGIC_V2 = 0x53535443;
const SSTABLE_FOOTER_SIZE = 32; const SSTABLE_FOOTER_SIZE = 32;
class SSTableBuilder { class SSTableBuilder {
constructor(blockSizeLimit = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(blockSizeLimit = 4096, bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY) {
this.entries = []; this.entries = [];
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
add(key, value) { add(key, value) {
@@ -4872,7 +4890,7 @@ class SSTableBuilder {
valueBytes: encoder.encode(JSON.stringify(value)), valueBytes: encoder.encode(JSON.stringify(value)),
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
const blockOffsets = []; const blockOffsets = [];
@@ -5492,6 +5510,8 @@ const BACKPRESSURE_FILES = 8;
* 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。 * 超过则退回到"等后台链静默"的保守读取（见 collectReaders）。
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// LSM // LSM
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -5559,6 +5579,9 @@ class LSM {
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && config.bloomBitsPerKey > 0
? Math.floor(config.bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -5761,7 +5784,7 @@ class LSM {
return; return;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -5857,6 +5880,45 @@ class LSM {
} }
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels() {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level))
await this.drainMaintenance();
if (this.levels[level].length < minFiles)
continue;
this.compacting.add(level);
await new Promise((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles))
compacted++;
}
finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
enqueueCompact(level) { enqueueCompact(level) {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level))
@@ -5980,6 +6042,45 @@ class LSM {
} }
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders() {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds)
out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds() {
const out = [];
for (const group of this.retired) {
for (const meta of group.metas)
out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle() {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount() { getRetiredCount() {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -5993,6 +6094,13 @@ class LSM {
reclaimRetiredNow() { reclaimRetiredNow() {
if (this.retired.length === 0) if (this.retired.length === 0)
return; return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -6208,7 +6316,7 @@ class LSM {
return true; return true;
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -6378,6 +6486,11 @@ class LSM {
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -6538,6 +6651,13 @@ class LSM {
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
async dropInvalidSSTable(meta, reason) { async dropInvalidSSTable(meta, reason) {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -6813,10 +6933,12 @@ class WAL {
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data; let data;
let gaps = []; let gaps = [];
let missingPrefix = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} }
else { else {
const exists = await this.store.exists(); const exists = await this.store.exists();
@@ -6828,7 +6950,8 @@ class WAL {
throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` + throw new DatabaseError(`WAL segment gap detected in live range (missing segment(s): ${gaps.join(', ')}) — ` +
'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP'); 'records after the gap cannot be verified; refusing to continue silently', 'ARIA_WAL_GAP');
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -6847,7 +6970,11 @@ class WAL {
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
/** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */ /** v0.8.0: 最近一次恢复诊断（applied/skipped/gaps） */
@@ -6983,6 +7110,7 @@ class WAL {
} }
decodeAllRecords(data) { decodeAllRecords(data) {
const records = []; const records = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
while (offset + 15 <= data.byteLength) { while (offset + 15 <= data.byteLength) {
@@ -7027,7 +7155,10 @@ class WAL {
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -7046,7 +7177,7 @@ class WAL {
break; break;
} }
} }
return records; return { records, corrupt };
} }
} }
@@ -7145,25 +7276,36 @@ class SegmentedWALStore {
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment = 0) { async readAllFrom(fromSegment = 0, fromLsn = 0) {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) for (let missing = fromSegment; missing < segments[0].seq; missing++)
gaps.push(missing); missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -7229,6 +7371,7 @@ class SegmentedWALStore {
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -7241,8 +7384,14 @@ class SegmentedWALStore {
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -7283,8 +7432,11 @@ class SegmentedWALStore {
*/ */
async planKeepFrom(durableLsn, latestLsn) { async planKeepFrom(durableLsn, latestLsn) {
const segments = await this.listSegments(); const segments = await this.listSegments();
// v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) if (segments.length === 0)
return 0; return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
// - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 末分片：已知当前 LSN 高水位 <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -7337,9 +7489,9 @@ class SegmentedWALStore {
} }
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
const obsolete = segments.filter((s) => s.seq < keepFrom); const obsolete = segments.filter((s) => s.seq < keepFrom);
@@ -8936,8 +9088,11 @@ class ManifestStore {
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// MVCCManager // MVCCManager
@@ -9479,6 +9634,7 @@ class AriaEngine {
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -9658,6 +9814,15 @@ class AriaEngine {
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)');
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -9914,27 +10079,34 @@ class AriaEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
async cleanupOrphanPages() { async cleanupOrphanPages() {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + console.warn(`[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)'); 'unreferenced data is kept, never deleted blindly');
return;
}
// v0.8.0（review 修复）：**有在途读者时一律不回收**。
// 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
// 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return; return;
} }
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
if (pgKeys.length === 0)
return;
const used = new Set(); const used = new Set();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds)
for (const pid of m.pageIds) for (const pid of m.pageIds)
used.add(pid); used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) if (meta.pageIds)
@@ -9942,7 +10114,11 @@ class AriaEngine {
used.add(pid); used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds())
used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -9951,6 +10127,48 @@ class AriaEngine {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables)
usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level)
usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds())
usedSstIds.add(id);
}
const orphanSstKeys = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m)
continue;
if (!usedSstIds.has(Number(m[1])))
orphanSstKeys.push(key);
}
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
sstableKeyPrefixes() {
const out = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main')
out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
getLsmLevels(lsm) { getLsmLevels(lsm) {
@@ -11275,6 +11493,47 @@ class AriaEngine {
async persistSchemas() { async persistSchemas() {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
parseSchemaRecord(raw, source) {
let parsed;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
}
catch (error) {
throw new DatabaseError(`${source} is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
validateSchemaShape(parsed, source) {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`, 'ARIA_LEGACY_META_CORRUPT');
}
const out = {};
for (const [tableName, columns] of Object.entries(parsed)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`, 'ARIA_LEGACY_META_CORRUPT');
}
for (const [colName, def] of Object.entries(columns)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`, 'ARIA_LEGACY_META_CORRUPT');
}
}
out[tableName] = columns;
}
return out;
}
async loadSchemas() { async loadSchemas() {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -11283,17 +11542,9 @@ class AriaEngine {
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
}
catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError(`Schema record is corrupt and cannot be loaded: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error); data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
} this.manifest.schemas = data;
} }
} }
for (const [tableName, columns] of Object.entries(data)) { for (const [tableName, columns] of Object.entries(data)) {
@@ -11305,6 +11556,40 @@ class AriaEngine {
// ======================================================================= // =======================================================================
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
describeRecoveryDamage() {
const reasons = [];
if (this.recoveryReport.manifestFallback)
reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected)
reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected)
reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -11327,6 +11612,7 @@ class AriaEngine {
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -11430,6 +11716,18 @@ class AriaEngine {
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
computeDurableLsn(intents) { computeDurableLsn(intents) {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null)
return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -11445,6 +11743,15 @@ class AriaEngine {
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
async advanceWalCheckpoint() { async advanceWalCheckpoint() {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)');
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -11514,17 +11821,10 @@ class AriaEngine {
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)); this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
}
catch (error) {
throw new DatabaseError(`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${error.message}`, 'ARIA_LEGACY_META_CORRUPT', error);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) { if (pageMeta && pageMeta instanceof ArrayBuffer && pageMeta.byteLength >= 4) {
@@ -11557,9 +11857,6 @@ class AriaEngine {
return; // WAL 覆盖到了这些数据（重放会重建） return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) if (!this.config.walEnabled)
return; // 未启用 WAL：本来就没有日志兜底（配置语义） return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0)
return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` + throw new DatabaseError(`AriaEngine manifest declares ${intents.length} un-flushed frozen table(s) [${summary}] ` +
'but no WAL record was replayed — confirmed writes are missing ' + 'but no WAL record was replayed — confirmed writes are missing ' +
@@ -12133,18 +12430,11 @@ class AriaEngine {
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level) => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles)
continue;
if (await this.lsm.compactLevel(level, minFiles))
compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
dist/vue.js.map
Vendored
+1 -1
View File
File diff suppressed because one or more lines are too long
jest.config.cjs
+4 -3
View File
@@ -41,9 +41,10 @@ module.exports = {
// v0.8.0 覆盖率门禁（此前完全不存在：jest.config 与 CI 都没有任何阈值， // v0.8.0 覆盖率门禁（此前完全不存在：jest.config 与 CI 都没有任何阈值，
// 覆盖率从 90% 掉到 60% 也全绿）。 // 覆盖率从 90% 掉到 60% 也全绿）。
// //
// 阈值 = 2026-08-15 在**修正口径后**（不再排除实现文件）实测的真实基线， // 阈值 = 在**修正口径后**（不再排除实现文件）实测的真实基线，下取整到整数百分点。
// 下取整到整数百分点。v0.8.0 各阶段会持续补测，M4 收口时再上调。 // 历史基线（2026-08-15）：Statements 90.66% / Branches 82.94% / Functions 94.36% / Lines 93.43%
// 实测基线：Statements 90.66% / Branches 82.94% / Functions 94.36% / Lines 93.43% // v0.8.0 收尾实测（2026-09-15，1980 用例）：Statements 90.59% / Branches 82.59% /
// Functions 94.14% / Lines 93.50%
// //
coverageThreshold: { coverageThreshold: {
global: { global: {
scripts/mutation-b6.py
+253 -27
View File
@@ -4,6 +4,7 @@
用法：python3 scripts/mutation-b6.py 用法：python3 scripts/mutation-b6.py
任何一条"回退后测试仍然通过"都会以非零退出码报出来（说明测试只是陪跑）。 任何一条"回退后测试仍然通过"都会以非零退出码报出来（说明测试只是陪跑）。
""" """
import hashlib
import io import io
import os import os
import re import re
@@ -22,7 +23,16 @@ CHECKPOINT = 'src/engine/aria/wal/checkpoint.ts'
SSTABLE = 'src/engine/aria/index/sstable.ts' SSTABLE = 'src/engine/aria/index/sstable.ts'
B6 = 'tests/v080-b6-single-commit-point.test.ts' B6 = 'tests/v080-b6-single-commit-point.test.ts'
WALSEG = 'tests/engine/aria-wal-segment.test.ts'
STRESS = 'tests/engine/aria-repair-hardening.test.ts' STRESS = 'tests/engine/aria-repair-hardening.test.ts'
WALLOG = 'src/engine/aria/wal/log.ts'
# 单条变异的 jest 运行上限（秒）。超时视为"变异脚本自身的问题"，必须报错而不是
# 悄悄当成"测试通过了"。
JEST_TIMEOUT_S = 300
# 正控（未变异的干净代码）必须跑通的套件：没有正控就无法区分
# "变异被测试拦住"与"这套件本来就是红的"。
CONTROL_SUITES = [B6, WALSEG]
MUTATIONS = [ MUTATIONS = [
dict( dict(
@@ -247,12 +257,11 @@ MUTATIONS = [
test=B6, pattern='三个读取路径对同一个损坏文件给出一致结论', test=B6, pattern='三个读取路径对同一个损坏文件给出一致结论',
), ),
dict( dict(
name='vacuum 硬编码返回 6（报告与事实无关）', name='vacuum 报告与事实无关的层数（硬编码 6）',
file=ENGINE, file=ENGINE,
old=""" let compactedLevels = 0; old=""" const compactedLevels = await this.lsm.vacuumLevels();""",
const isBottom = (level: number): boolean => level === MAX_LSM_LEVELS - 1;""", new=""" await this.lsm.vacuumLevels();
new=""" let compactedLevels = 6; // [MUTATION] 旧行为：与事实无关的数字 const compactedLevels = 6; // [MUTATION] 旧行为：与事实无关的数字""",
const isBottom = (level: number): boolean => level === MAX_LSM_LEVELS - 1;""",
test=B6, pattern='vacuum 返回', test=B6, pattern='vacuum 返回',
), ),
dict( dict(
@@ -289,6 +298,146 @@ MUTATIONS = [
new=""" // [MUTATION] 不聚合 LSM 报告""", new=""" // [MUTATION] 不聚合 LSM 报告""",
test=B6, pattern='恢复报告聚合', test=B6, pattern='恢复报告聚合',
), ),
# ------------------------------------------------------------------
# review 轮（v0.8.0 全量回归审查）新增：每条对应一个已证实的缺陷
# ------------------------------------------------------------------
dict(
name='R1 事务进行中仍推进 WAL 水位（P0：已提交事务静默丢失）',
file=ENGINE,
old=""" if (this.currentTxnId !== null) return this.durableLsn;""",
new=""" if (false as boolean) return this.durableLsn; // [MUTATION] 去掉事务守卫""",
test=B6, pattern='事务进行中不得推进 WAL 水位',
),
dict(
name='R2 强制回收不理会途读者（在途读者数据被打断）',
file=LSM,
old=""" if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}""",
new=""" if (false as boolean) {
this.reclaimRetired();
return;
}""",
test=B6, pattern='退休 SSTable 与在途读者',
),
dict(
name='R3 孤儿回收只看引擎层损坏（漏掉 LSM 层被丢的 SSTable）',
file=ENGINE,
old=""" if (damage.length > 0) {""",
new=""" if (damage.length > 99) { // [MUTATION] 门槛失效""",
test=B6, pattern='回收门槛与孤儿回收',
),
dict(
name='R4 WAL 前缀缺失丢弃后缀分片（整段活 WAL 被丢掉）',
file=SEGSTORE,
old=""" if (fromLsn === 0 && missingPrefix.length > 0) {""",
new=""" if (missingPrefix.length > 0) { // [MUTATION] 前缀缺失一律算空洞""",
test=B6, pattern='WAL 前缀缺失',
),
dict(
name='R5 丢弃 SSTable 后不同步内存层数组（幽灵 meta）',
file=LSM,
old=""" if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {""",
new=""" if (false as boolean) { // [MUTATION] 只从 manifest 摘除""",
test=B6, pattern='内存层数组与 manifest 必须一致',
),
dict(
name='R6 不校验"文件名世代 == 载荷世代"（改名的旧副本被当成新提交点）',
file=MANIFEST,
old=""" if (decoded.manifest.generation !== gen) {""",
new=""" if (false as boolean) { // [MUTATION] 不比对世代号""",
test=B6, pattern='文件名世代与载荷世代不一致',
),
dict(
name='R7 pageIdWatermark 不再取单调 max（水位可回退→页面 id 复用）',
file=ENGINE,
old=""" this.manifest.pageIdWatermark = Math.max(
this.manifest.pageIdWatermark,
this.fileManager.getNextPageId(),
);""",
new=""" this.manifest.pageIdWatermark = this.fileManager.getNextPageId(); // [MUTATION]""",
test=B6, pattern='水位是单调下限',
),
dict(
name='R8 提交不做回读校验（写丢了也报成功）',
file=MANIFEST,
old=""" if (!verified.ok || verified.manifest.generation !== nextGeneration) {""",
new=""" if (false as boolean) { // [MUTATION] 关掉回读校验""",
test=B6, pattern='读回来是坏的',
),
dict(
name='R9 WAL 损坏记录不计数（静默丢记录）',
file=WALLOG,
old=""" corrupt++;""",
new=""" corrupt += 0; // [MUTATION] 不计数""",
test=B6, pattern='WAL 记录级损坏',
),
dict(
name='R10 丢弃残缺文件不进恢复报告（静默丢弃）',
file=LSM,
old=""" this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });""",
new=""" void reason; // [MUTATION] 不记录丢弃原因""",
test=B6, pattern='文件真的残缺',
),
dict(
name='R11 介质读故障的错误码被改写（读故障≠文件损坏的语义丢失）',
file=LSM,
old=""" 'ARIA_SSTABLE_READ_FAILED',""",
new=""" 'MUTATED_READ_FAILED', // [MUTATION]""",
test=B6, pattern='介质读故障',
),
dict(
name='R12 冻结意图不再压低水位（水位越过只在内存+WAL 的写入）',
file=ENGINE,
old=""" return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));""",
new=""" return Math.max(this.durableLsn, Math.max(...intents.map((i) => i.lsnAtFreeze))); // [MUTATION]""",
test=B6, pattern='水位严格低于意图起点',
),
dict(
name='R13 truncateBefore 把分片号重置为 0（新记录落在 manifest 水位之下被过滤）',
file=SEGSTORE,
old=""" this.currentSegment = Math.max(maxSeq + 1, keepFrom);""",
new=""" this.currentSegment = 0; // [MUTATION] 修复前行为""",
test=WALSEG, pattern='写入永不落到 manifest 水位下限之下',
),
dict(
name='R14 truncate 把分片号重置为 0（旧世代与新记录同号）',
file=SEGSTORE,
old=""" this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);""",
new=""" this.currentSegment = 0; // [MUTATION] 修复前行为""",
test=WALSEG, pattern='整体清空后分片号绝不回退',
),
dict(
name='R15 内部空洞不再上报（丢一段已提交事务却毫无痕迹）',
file=SEGSTORE,
old=""" gaps.push(missing);""",
new=""" void missing; // [MUTATION] 不上报空洞""",
test=WALSEG, pattern='内部空洞',
),
dict(
name='R17 bloom 位数被忽略（bloomFilterBitsPerKey 配置无效）',
file='src/engine/aria/index/sstable_builder.ts',
old=""" const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);""",
new=""" const bloomFilter = new BloomFilter(this.entries.length); // [MUTATION] 忽略配置""",
test=B6, pattern='bloomFilterBitsPerKey',
),
dict(
name='R18 引擎层不把 bloom 配置透传给 LSM（配置无效）',
file=LSM,
old=""" this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && (config.bloomBitsPerKey as number) > 0
? Math.floor(config.bloomBitsPerKey as number)
: DEFAULT_BLOOM_BITS_PER_KEY;""",
new=""" this.bloomBitsPerKey = DEFAULT_BLOOM_BITS_PER_KEY; // [MUTATION] 忽略配置""",
test=B6, pattern='bloomFilterBitsPerKey',
),
dict(
name='R16 旧格式表结构形状坏掉时静默当空库',
file=ENGINE,
old=""" if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {""",
new=""" if (false as boolean) { // [MUTATION] 不校验形状""",
test=B6, pattern='旧格式表结构记录的形状校验',
),
] ]
@@ -310,22 +459,97 @@ for _sig in ('SIGINT', 'SIGTERM', 'SIGHUP'):
pass pass
def run(cmd): def run(cmd, timeout=JEST_TIMEOUT_S):
return subprocess.run(cmd, cwd=ROOT, shell=True, capture_output=True, text=True) """跑一条命令：带超时（超时 = 变异脚本自身的问题，必须显式报出来）。"""
return subprocess.run(
cmd, cwd=ROOT, shell=True, capture_output=True, text=True, timeout=timeout,
)
def sha256(text):
return hashlib.sha256(text.encode('utf-8')).hexdigest()
def acquire_lock():
"""同一时刻只允许一个变异进程改 src/（并发跑会互相踩掉对方的源码）。"""
lock = os.path.join(ROOT, '.mutation-b6.lock')
try:
fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
except FileExistsError:
print(f'[abort] 已有变异进程在跑（{lock} 存在）。')
print(' 确认没有残留后删除该文件再重试。')
sys.exit(2)
os.write(fd, str(os.getpid()).encode())
os.close(fd)
return lock
def classify(out):
"""把一次 jest 输出分类。顺序很重要：
编译失败/未匹配**不能**算"测试拦住了变异"。"""
if re.search(r'Test suite failed to run', out) or re.search(r'error TS\d+', out) \
or 'Cannot find module' in out or 'SyntaxError' in out:
return 'BAD(变异破坏编译)'
if re.search(r'^Tests:\s+0 total', out, re.M) or 'No tests found' in out:
return 'BAD(用例未匹配)'
if re.search(r'^Tests:.*\bfailed\b', out, re.M) or '✕' in out:
return 'OK(变异被拦住)'
return 'BAD(测试仍然通过)'
def positive_control():
"""正控：未变异的干净代码上，这些套件必须全绿。
没有正控的变异脚本会把"套件本来就红"误读成"变异被拦住了"。"""
print('[control] 干净代码基线检查 …', flush=True)
for suite in CONTROL_SUITES:
try:
res = run(f"npx jest {shlex.quote(suite)} --testPathIgnorePatterns='/node_modules/'")
except subprocess.TimeoutExpired:
print(f'[control] 超时：{suite}')
return False
out = (res.stdout or '') + (res.stderr or '')
m = re.search(r'^Tests:\s+(.*)$', out, re.M)
line = m.group(1) if m else '无法解析'
if 'failed' in line or not m:
print(f'[control] 基线不干净：{suite} → Tests: {line}')
return False
print(f'[control] ok {suite} → Tests: {line}', flush=True)
return True
def main(): def main():
lock = acquire_lock()
try:
return _main()
finally:
try:
os.unlink(lock)
except OSError: # pragma: no cover
pass
def _main():
only = sys.argv[1] if len(sys.argv) > 1 else None only = sys.argv[1] if len(sys.argv) > 1 else None
if not positive_control():
print('\n[abort] 正控未通过 —— 先修好基线再谈"变异被拦住"。')
return 2
results = [] results = []
fingerprints = {}
for m in MUTATIONS: for m in MUTATIONS:
if only and only not in m['name']: if only and only not in m['name']:
continue continue
path = os.path.join(ROOT, m['file']) path = os.path.join(ROOT, m['file'])
original = io.open(path, encoding='utf-8').read() original = io.open(path, encoding='utf-8').read()
fingerprints[path] = sha256(original)
if m['old'] not in original: if m['old'] not in original:
results.append((m['name'], 'SKIP(锚点未找到)')) results.append((m['name'], 'SKIP(锚点未找到)'))
print(f"[skip] {m['name']}: 锚点未找到", flush=True) print(f"[skip] {m['name']}: 锚点未找到", flush=True)
continue continue
if original.count(m['old']) != 1:
results.append((m['name'], f"SKIP(锚点不唯一 x{original.count(m['old'])})"))
print(f"[skip] {m['name']}: 锚点出现 {original.count(m['old'])} 次，拒绝变异", flush=True)
continue
mutated = original.replace(m['old'], m['new'], 1) mutated = original.replace(m['old'], m['new'], 1)
CURRENT['path'] = path CURRENT['path'] = path
CURRENT['content'] = original CURRENT['content'] = original
@@ -335,37 +559,39 @@ def main():
# 于是 jest 收到 `\\(` 这种模式、匹配不到任何用例，脚本会把"没跑用例" # 于是 jest 收到 `\\(` 这种模式、匹配不到任何用例，脚本会把"没跑用例"
# 误判成"测试仍然通过"。 # 误判成"测试仍然通过"。
cmd = (f"npx jest {shlex.quote(m['test'])} -t {shlex.quote(m['pattern'])} " cmd = (f"npx jest {shlex.quote(m['test'])} -t {shlex.quote(m['pattern'])} "
f"--testPathIgnorePatterns='/node_modules/' 2>&1 | tail -80") f"--testPathIgnorePatterns='/node_modules/'")
out = run(cmd).stdout try:
# 注意：不能只搜 "0 total" —— jest 的 "Snapshots: 0 total" 也会命中， res = run(cmd)
# 于是把"跑了用例且失败"误判成"用例未匹配"。 out = (res.stdout or '') + (res.stderr or '')
no_tests = bool(re.search(r'^Tests:\s+0 total', out, re.M)) or ('No tests found' in out) except subprocess.TimeoutExpired:
failed = ('✕' in out) or ('Tests:' in out and 'failed' in out) or ('●' in out) status = 'BAD(超时)'
if no_tests: out = ''
status = 'SKIP(用例未匹配)'
elif failed:
status = 'FAIL(如预期)'
else: else:
status = 'PASS(!!)' status = classify(out)
results.append((m['name'], status)) results.append((m['name'], status))
msg = { icon = 'ok ' if status == 'OK(变异被拦住)' else 'BAD'
'FAIL(如预期)': '测试失败（变异被拦住）', print(f'[{icon}] {m["name"]} → {status}', flush=True)
'PASS(!!)': '测试仍然通过！', if status != 'OK(变异被拦住)':
'SKIP(用例未匹配)': '用例未匹配（模式写错了）', tail = [l for l in out.splitlines() if l.startswith('Tests:')]
}[status] if tail:
print(f"[{'ok' if status == 'FAIL(如预期)' else 'BAD'}] {m['name']} → {msg}", flush=True) print(f' {tail[0]}', flush=True)
finally: finally:
io.open(path, 'w', encoding='utf-8').write(original) io.open(path, 'w', encoding='utf-8').write(original)
# 恢复必须逐字节一致（否则会悄悄改动源码）
if sha256(io.open(path, encoding='utf-8').read()) != fingerprints[path]:
print(f'[FATAL] {m["file"]} 恢复后与原始内容不一致！', flush=True)
return 3
CURRENT['path'] = None CURRENT['path'] = None
CURRENT['content'] = None CURRENT['content'] = None
print('\n==== 变异验证汇总 ====') print('\n==== 变异验证汇总 ====')
bad = [r for r in results if r[1] != 'FAIL(如预期)'] bad = [r for r in results if r[1] != 'OK(变异被拦住)']
for name, status in results: for name, status in results:
print(f' {status:14s} {name}') print(f' {status:20s} {name}')
if bad: if bad:
print(f'\n{len(bad)} 条变异没有被测试拦住 —— 那些用例只是陪跑。') print(f'\n{len(bad)} 条变异没有被测试拦住 —— 那些用例只是陪跑。')
return 1 return 1
print('\n全部变异都被对应用例拦住。') print(f'\n全部 {len(results)} 条变异都被对应用例拦住。')
return 0 return 0
site/demo.html
+1 -1
View File
@@ -591,7 +591,7 @@ DROP TABLE temp_logs;`,
-- AriaEngine 特性: -- AriaEngine 特性:
-- • LSM-Tree: MemTable (红黑树) → SSTable 多级索引 -- • LSM-Tree: MemTable (红黑树) → SSTable 多级索引
-- • WAL: 分片文件 + 标准 CRC32 + 空洞检测 + 崩溃恢复（残缺 SSTable 自动跳过） -- • WAL: 分片文件 + 标准 CRC32 + 空洞检测 + 崩溃恢复（残缺 SSTable 自动跳过）
-- • MVCC: 版本链 + 快照隔离 -- • MVCC: 版本链仅作事务内 undo（无快照隔离；事务串行）
-- • 页面化物理存储: SSTable 4KB 页面 + BufferPool LRU 缓存 (v0.5.0) -- • 页面化物理存储: SSTable 4KB 页面 + BufferPool LRU 缓存 (v0.5.0)
-- • 完整性: 整文件 CRC-32 校验（数据腐坏自动清理自愈） -- • 完整性: 整文件 CRC-32 校验（数据腐坏自动清理自愈）
-- • Bloom Filter: FNV-1a + Murmur 双哈希 -- • Bloom Filter: FNV-1a + Murmur 双哈希
site/docs.html
+19 -5
View File
@@ -140,7 +140,7 @@ npm install @metona-team/metona-sqlark</pre>
<table> <table>
<tr><th>文件</th><th>格式</th><th>用途</th></tr> <tr><th>文件</th><th>格式</th><th>用途</th></tr>
<tr><td><code>metona-sqlark.js</code></td><td>UMD</td><td>浏览器开发版（含 sourcemap）</td></tr> <tr><td><code>metona-sqlark.js</code></td><td>UMD</td><td>浏览器开发版（含 sourcemap）</td></tr>
<tr><td><code>metona-sqlark.min.js</code></td><td>UMD (minified)</td><td>生产环境（~105KB / ~27KB gzip）</td></tr> <tr><td><code>metona-sqlark.min.js</code></td><td>UMD (minified)</td><td>生产环境（实测 251,109 字节 / gzip 63,145 字节，含全部引擎与 SQL 层）</td></tr>
<tr><td><code>metona-sqlark.esm.js</code></td><td>ES Module</td><td>现代打包工具 / 浏览器 ESM</td></tr> <tr><td><code>metona-sqlark.esm.js</code></td><td>ES Module</td><td>现代打包工具 / 浏览器 ESM</td></tr>
<tr><td><code>metona-sqlark.cjs</code></td><td>CommonJS</td><td>Node.js require()</td></tr> <tr><td><code>metona-sqlark.cjs</code></td><td>CommonJS</td><td>Node.js require()</td></tr>
<tr><td><code>metona-sqlark.d.ts</code></td><td>TypeScript 声明</td><td>类型提示</td></tr> <tr><td><code>metona-sqlark.d.ts</code></td><td>TypeScript 声明</td><td>类型提示</td></tr>
@@ -793,7 +793,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<tr><td><code>MemoryEngine</code></td><td>memory</td><td>❌</td><td>哈希</td><td>快照回滚</td><td>临时数据、缓存、测试</td></tr> <tr><td><code>MemoryEngine</code></td><td>memory</td><td>❌</td><td>哈希</td><td>快照回滚</td><td>临时数据、缓存、测试</td></tr>
<tr><td><code>KVStoreEngine</code> 🆕</td><td>disk</td><td>✅ KVStore(OPFS)</td><td>哈希</td><td>原子日志 flush</td><td>标准持久化（v0.6.0 替代 IndexedDB）</td></tr> <tr><td><code>KVStoreEngine</code> 🆕</td><td>disk</td><td>✅ KVStore(OPFS)</td><td>哈希</td><td>原子日志 flush</td><td>标准持久化（v0.6.0 替代 IndexedDB）</td></tr>
<tr><td><code>HybridEngine</code></td><td>hybrid</td><td>✅ Write-Through</td><td>哈希</td><td>双引擎代理</td><td>生产推荐，读写均走内存</td></tr> <tr><td><code>HybridEngine</code></td><td>hybrid</td><td>✅ Write-Through</td><td>哈希</td><td>双引擎代理</td><td>生产推荐，读写均走内存</td></tr>
<tr style="border-top:2px solid var(--primary);"><td><code style="color:#ec4899;font-weight:700;">AriaEngine</code></td><td>aria</td><td>✅ WAL + SSTable</td><td>LSM-Tree</td><td>MVCC 快照隔离</td><td>自研引擎：大表、高并发、需崩溃恢复</td></tr> <tr style="border-top:2px solid var(--primary);"><td><code style="color:#ec4899;font-weight:700;">AriaEngine</code></td><td>aria</td><td>✅ WAL + SSTable</td><td>LSM-Tree</td><td>版本链 undo + 事务串行</td><td>自研引擎：大表、高并发、需崩溃恢复</td></tr>
</table> </table>
<p>✅ <strong>v0.6.0: IndexedDB 已完全移除</strong> — disk 模式改用自研 KVStore 引擎（多 key 原子写 + 快照/日志崩溃恢复），旧库可经 <code>migrateFromIndexedDB()</code> 一键迁移。</p> <p>✅ <strong>v0.6.0: IndexedDB 已完全移除</strong> — disk 模式改用自研 KVStore 引擎（多 key 原子写 + 快照/日志崩溃恢复），旧库可经 <code>migrateFromIndexedDB()</code> 一键迁移。</p>
@@ -820,7 +820,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<table> <table>
<tr><th>特性</th><th>Memory</th><th>Disk (KVStore)</th><th>Hybrid</th><th>Aria</th></tr> <tr><th>特性</th><th>Memory</th><th>Disk (KVStore)</th><th>Hybrid</th><th>Aria</th></tr>
<tr><td>持久化</td><td>❌</td><td>✅ KVStore（OPFS / 内存介质）</td><td>✅ 双写</td><td>✅ 后端决定</td></tr> <tr><td>持久化</td><td>❌</td><td>✅ KVStore（OPFS / 内存介质）</td><td>✅ 双写</td><td>✅ 后端决定</td></tr>
<tr><td>事务</td><td>✅ 快照回滚</td><td>✅ 单日志记录原子写</td><td>✅ 双引擎（磁盘优先）</td><td>✅ MVCC 快照隔离</td></tr> <tr><td>事务</td><td>✅ 快照回滚</td><td>✅ 单日志记录原子写</td><td>✅ 双引擎（磁盘优先）</td><td>✅ 快照回滚（事务串行，非 MVCC 隔离）</td></tr>
<tr><td>索引</td><td>Hash</td><td>Hash（重启恢复）</td><td>Hash</td><td>LSM 二级（重启恢复）</td></tr> <tr><td>索引</td><td>Hash</td><td>Hash（重启恢复）</td><td>Hash</td><td>LSM 二级（重启恢复）</td></tr>
<tr><td>上限</td><td>内存</td><td>磁盘可用</td><td>磁盘可用</td><td>内存</td></tr> <tr><td>上限</td><td>内存</td><td>磁盘可用</td><td>磁盘可用</td><td>内存</td></tr>
<tr><td>多标签页锁</td><td>—</td><td>—</td><td>—</td><td>✅ Web Locks</td></tr> <tr><td>多标签页锁</td><td>—</td><td>—</td><td>—</td><td>✅ Web Locks</td></tr>
@@ -834,8 +834,8 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<tr><td><strong>LSM-Tree 索引</strong></td><td>MemTable (红黑树) + 多级 SSTable，写优化，支持范围扫描</td></tr> <tr><td><strong>LSM-Tree 索引</strong></td><td>MemTable (红黑树) + 多级 SSTable，写优化，支持范围扫描</td></tr>
<tr><td><strong>4KB 页面化物理存储</strong></td><td>SSTable 切分为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），save 即落盘，`SSTableMeta.pageIds` 持久化（旧整 value 数据兼容）✅ v0.5.0</td></tr> <tr><td><strong>4KB 页面化物理存储</strong></td><td>SSTable 切分为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），save 即落盘，`SSTableMeta.pageIds` 持久化（旧整 value 数据兼容）✅ v0.5.0</td></tr>
<tr><td><strong>Buffer Pool</strong></td><td>LRU 页面缓存，可控内存占用（默认 256 页 ≈ 1MB），脏页写回 ✅ v0.5.0 真实接入</td></tr> <tr><td><strong>Buffer Pool</strong></td><td>LRU 页面缓存，可控内存占用（默认 256 页 ≈ 1MB），脏页写回 ✅ v0.5.0 真实接入</td></tr>
<tr><td><strong>WAL 日志</strong></td><td>分片文件（`__wal_%06d.bin`，4MB 阈值切换 + 真追加）· 标准 CRC32 记录校验 · full/batch/none 三种同步模式（full 真正同步）· 空洞检测截断 · 16MB 阈值自动 checkpoint ✅ v0.5.0</td></tr> <tr><td><strong>WAL 日志</strong></td><td>分片文件（`__wal_%06d.bin`，4MB 阈值切换 + 真追加）· 标准 CRC32 记录校验（记录级 CRC 失败 → <code>droppedWALRecords</code> + 数据丢失标记，不再只打日志）· full/batch/none 三种同步模式（full 真正同步）· 空洞如实上报（内部空洞 → <code>ARIA_WAL_GAP</code> 且拒绝静默继续） · 16MB 阈值自动 checkpoint ✅ v0.8.0 补齐</td></tr>
<tr><td><strong>MVCC 事务</strong></td><td>快照隔离 (Snapshot Isolation)，读写不互斥，版本链 + GC（引擎事务读取走 txnSnapshot，MVCC 版本链作 undo log）</td></tr> <tr><td><strong>MVCC 版本链</strong></td><td>版本链仅作事务内 undo（提交即清理，自动 GC），<strong>不提供快照隔离</strong>；引擎事务读取走 txnSnapshot，同一实例同时只允许一个事务（并发 begin 抛 TX_ACTIVE）✅ v0.8.0 如实描述</td></tr>
<tr><td><strong>全库 AES-GCM 加密</strong></td><td>EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）· PBKDF2 密钥派生 + salt 持久化 + 密码验证 · 明文/加密库开关一致性检测 ✅ v0.5.0</td></tr> <tr><td><strong>全库 AES-GCM 加密</strong></td><td>EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）· PBKDF2 密钥派生 + salt 持久化 + 密码验证 · 明文/加密库开关一致性检测 ✅ v0.5.0</td></tr>
<tr><td><strong>多标签页独占锁</strong></td><td>Web Locks API：第二个标签页打开同一库抛 `ARIA_LOCKED`，open 失败自动释放 ✅ v0.5.0</td></tr> <tr><td><strong>多标签页独占锁</strong></td><td>Web Locks API：第二个标签页打开同一库抛 `ARIA_LOCKED`，open 失败自动释放 ✅ v0.5.0</td></tr>
<tr><td><strong>Bloom Filter</strong></td><td>快速判定 key 不存在，减少无效磁盘 I/O，SSTableReader 二分查找统一 ✅ v0.2.5</td></tr> <tr><td><strong>Bloom Filter</strong></td><td>快速判定 key 不存在，减少无效磁盘 I/O，SSTableReader 二分查找统一 ✅ v0.2.5</td></tr>
@@ -878,6 +878,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<tr><td><code>walSizeThreshold</code></td><td><code>number</code></td><td><code>16777216</code></td><td>WAL 大小阈值（字节），超阈值触发 checkpoint ✅ v0.2.5</td></tr> <tr><td><code>walSizeThreshold</code></td><td><code>number</code></td><td><code>16777216</code></td><td>WAL 大小阈值（字节），超阈值触发 checkpoint ✅ v0.2.5</td></tr>
<tr><td><code>compression</code></td><td><code>boolean</code></td><td><code>false</code></td><td>是否启用页面压缩</td></tr> <tr><td><code>compression</code></td><td><code>boolean</code></td><td><code>false</code></td><td>是否启用页面压缩</td></tr>
<tr><td><code>storageBackend</code></td><td><code>'opfs'|'memory'|'kv'</code></td><td><code>'opfs'</code></td><td>存储后端类型（'kv' = 自研 KVStore 后端 🆕 v0.6.1）</td></tr> <tr><td><code>storageBackend</code></td><td><code>'opfs'|'memory'|'kv'</code></td><td><code>'opfs'</code></td><td>存储后端类型（'kv' = 自研 KVStore 后端 🆕 v0.6.1）</td></tr>
<tr><td><code>maxMemoryMB</code></td><td><code>number</code></td><td><code>64</code></td><td>内存预算（MB）：主 LSM 估算内存超限时触发 flush + MVCC GC</td></tr>
<tr><td><code>encryption</code></td><td><code>{ password: string }</code></td><td>-</td><td>全库 AES-256-GCM 透明加密（PBKDF2 派生 + salt 持久化 + 密码验证）🆕 v0.5.0</td></tr> <tr><td><code>encryption</code></td><td><code>{ password: string }</code></td><td>-</td><td>全库 AES-256-GCM 透明加密（PBKDF2 派生 + salt 持久化 + 密码验证）🆕 v0.5.0</td></tr>
<tr><td><code>pageStorage</code></td><td><code>boolean</code></td><td>opfs/kv 自动启用</td><td>SSTable 4KB 页面化物理存储（BufferPool 缓存）🆕 v0.5.0</td></tr> <tr><td><code>pageStorage</code></td><td><code>boolean</code></td><td>opfs/kv 自动启用</td><td>SSTable 4KB 页面化物理存储（BufferPool 缓存）🆕 v0.5.0</td></tr>
</table> </table>
@@ -901,6 +902,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<tr><td><code>TABLE_EXISTS</code></td><td>表已存在</td></tr> <tr><td><code>TABLE_EXISTS</code></td><td>表已存在</td></tr>
<tr><td><code>DUPLICATE_KEY</code></td><td>主键重复</td></tr> <tr><td><code>DUPLICATE_KEY</code></td><td>主键重复</td></tr>
<tr><td><code>UNIQUE_VIOLATION</code></td><td>唯一约束冲突</td></tr> <tr><td><code>UNIQUE_VIOLATION</code></td><td>唯一约束冲突</td></tr>
<tr><td><code>FOREIGN_KEY_VIOLATION</code></td><td>外键约束冲突：删除/更新被引用行时存在依赖行（含 RESTRICT / CASCADE 语义）</td></tr>
<tr><td><code>VALIDATION_ERROR</code></td><td>数据校验失败</td></tr> <tr><td><code>VALIDATION_ERROR</code></td><td>数据校验失败</td></tr>
<tr><td><code>TYPE_ERROR</code></td><td>字段类型错误</td></tr> <tr><td><code>TYPE_ERROR</code></td><td>字段类型错误</td></tr>
<tr><td><code>SCHEMA_ERROR</code></td><td>表结构定义错误</td></tr> <tr><td><code>SCHEMA_ERROR</code></td><td>表结构定义错误</td></tr>
@@ -927,6 +929,18 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
<tr><td><code>ARIA_WAL_GAP</code></td><td>WAL 分片空洞（含前缀缺失）：拒绝在"少了一段日志"的情况下静默继续 🆕 v0.8.0</td></tr> <tr><td><code>ARIA_WAL_GAP</code></td><td>WAL 分片空洞（含前缀缺失）：拒绝在"少了一段日志"的情况下静默继续 🆕 v0.8.0</td></tr>
<tr><td><code>ARIA_WRITE_LOST</code></td><td>manifest 声称有未落盘数据，但 WAL 中没有任何可重放的记录（已确认写入确实丢失）🆕 v0.8.0</td></tr> <tr><td><code>ARIA_WRITE_LOST</code></td><td>manifest 声称有未落盘数据，但 WAL 中没有任何可重放的记录（已确认写入确实丢失）🆕 v0.8.0</td></tr>
<tr><td><code>STALE_INSTANCE</code></td><td>陈旧实例拒绝提交（另一个实例已提交更新的世代），不会静默覆盖 🆕 v0.8.0</td></tr> <tr><td><code>STALE_INSTANCE</code></td><td>陈旧实例拒绝提交（另一个实例已提交更新的世代），不会静默覆盖 🆕 v0.8.0</td></tr>
<tr><td><code>ARIA_MANIFEST_NOT_LOADED</code></td><td>未 <code>load()</code> 就提交 manifest：拒绝写坏介质 🆕 v0.8.0</td></tr>
<tr><td><code>ARIA_SSTABLE_SAVE_CONTRACT</code></td><td>存储实现违反 <code>save()</code> 契约（既不抛错也不返回结果）：不把"写调用返回了"当成落盘成功 🆕 v0.8.0</td></tr>
<tr><td><code>ARIA_DB_NOT_OPEN</code></td><td>在 <code>open()</code> 之前使用 Aria 存储层（如加密后端） 🆕 v0.8.0</td></tr>
<tr><td><code>ARIA_OPEN_ERROR</code></td><td>AriaEngine 打开失败（底层错误作为 cause 保留） 🆕 v0.8.0</td></tr>
<tr><td><code>DB_NOT_OPEN</code></td><td>数据库未打开（KVStoreEngine 操作前未 <code>open()</code>）</td></tr>
<tr><td><code>KV_SCHEMA_ERROR</code></td><td>KVStore 中的表结构记录损坏</td></tr>
<tr><td><code>KV_LOG_ERROR</code> / <code>KV_BACKGROUND_ERROR</code></td><td>KVStore 日志写入失败 / 后台刷盘失败</td></tr>
<tr><td><code>TX_NONE</code></td><td>没有活跃事务时执行 COMMIT / ROLLBACK</td></tr>
<tr><td><code>TX_ACTIVE</code></td><td>已有事务进行中时再次 BEGIN</td></tr>
<tr><td><code>TX_COMMIT_ERROR</code></td><td>hybrid 模式提交失败：磁盘侧已提交、内存侧失败（错误信息说明磁盘数据已落盘）</td></tr>
<tr><td><code>UNKNOWN_STATEMENT</code></td><td>执行器遇到未知语句类型</td></tr>
<tr><td><code>COLUMN_EXISTS</code></td><td>ADD COLUMN 的列已存在</td></tr>
</table> </table>
</main> </main>
site/index.html
+10 -10
View File
@@ -153,9 +153,9 @@
<!-- Hero --> <!-- Hero -->
<section class="hero"> <section class="hero">
<div class="container"> <div class="container">
<div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.8.0 根治性迭代 — 1935 测试 91 套件 · 语句/分支/函数/行覆盖率 90.34% / 82.16% / 94.06% / 93.23% · UPDATE/DELETE 子查询正确执行 · 主键非空强制 · DROP INDEX 保留 UNIQUE 约束 · findStream 真惰性 · 参数化查询 · 自研 KVStore 事务引擎 · AriaEngine LSM+WAL+MVCC · 崩溃恢复</div> <div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.8.0 根治性迭代 — 1980 测试 92 套件 · 语句/分支/函数/行覆盖率 90.59% / 82.59% / 94.14% / 93.50% · UPDATE/DELETE 子查询正确执行 · 主键非空强制 · DROP INDEX 保留 UNIQUE 约束 · findStream 真惰性 · 参数化查询 · 自研 KVStore 事务引擎 · AriaEngine LSM+WAL+MVCC · 崩溃恢复</div>
<h1>前端的 <span class="gradient-text">SQL 数据库</span></h1> <h1>前端的 <span class="gradient-text">SQL 数据库</span></h1>
<p>TypeScript 原生构建，5 种存储引擎，支持完整 SQL 查询。<br>零运行时依赖，开箱即用。AriaEngine 自研引擎：LSM-Tree + WAL 同步 + MVCC。</p> <p>TypeScript 原生构建，4 种存储模式 + 3 种存储后端，支持完整 SQL 查询。<br>零运行时依赖，开箱即用。AriaEngine 自研引擎：LSM-Tree + WAL 同步 + MVCC。</p>
<div class="actions"> <div class="actions">
<a href="demo.html" class="btn btn-primary" style="font-size:1.05rem;padding:14px 32px;">▶ 在线演示</a> <a href="demo.html" class="btn btn-primary" style="font-size:1.05rem;padding:14px 32px;">▶ 在线演示</a>
<a href="docs.html" class="btn btn-outline" style="font-size:1.05rem;padding:14px 32px;">📖 API 文档</a> <a href="docs.html" class="btn btn-outline" style="font-size:1.05rem;padding:14px 32px;">📖 API 文档</a>
@@ -233,8 +233,8 @@ npm install @metona-team/metona-sqlark
<div class="feature-grid"> <div class="feature-grid">
<div class="feature-card"> <div class="feature-card">
<div class="icon">🧠</div> <div class="icon">🧠</div>
<h3>5 种存储引擎</h3> <h3>4 种存储模式 + 3 种后端</h3>
<p>Memory / KVStore / OPFS / Hybrid / <strong>AriaEngine</strong>。Aria 是自研 LSM-Tree 页面式引擎，支持 WAL 同步崩溃恢复和 MVCC 事务隔离。</p> <p>模式：Memory / Disk / Hybrid / <strong>AriaEngine</strong>；后端：OPFS / KVStore / Memory。Aria 是自研 LSM-Tree 页面式引擎，支持 WAL 同步崩溃恢复与事务回滚（版本链仅作事务内 undo，事务串行 —— 非 MVCC 快照隔离）。</p>
</div> </div>
<div class="feature-card"> <div class="feature-card">
<div class="icon">⚡</div> <div class="icon">⚡</div>
@@ -279,7 +279,7 @@ npm install @metona-team/metona-sqlark
<div class="feature-card"> <div class="feature-card">
<div class="icon">📦</div> <div class="icon">📦</div>
<h3>零运行时依赖</h3> <h3>零运行时依赖</h3>
<p>纯 TypeScript 实现，不依赖任何第三方库。Tree-shakable，UMD/ESM/CJS 多格式输出，~27KB gzip。</p> <p>纯 TypeScript 实现，不依赖任何第三方库。UMD/ESM/CJS 多格式输出，min 产物实测 251,109 字节 / gzip 63,145 字节。</p>
</div> </div>
<div class="feature-card"> <div class="feature-card">
<div class="icon">📊</div> <div class="icon">📊</div>
@@ -414,12 +414,12 @@ npm install @metona-team/metona-sqlark
<p>MetonaSqlark 的核心指标</p> <p>MetonaSqlark 的核心指标</p>
</div> </div>
<div class="stats"> <div class="stats">
<div class="stat-card"><div class="num">1872</div><div class="label">测试用例（+14 e2e）</div></div> <div class="stat-card"><div class="num">1980</div><div class="label">测试用例（+14 e2e）</div></div>
<div class="stat-card"><div class="num">93.44%</div><div class="label">行覆盖率</div></div> <div class="stat-card"><div class="num">93.50%</div><div class="label">行覆盖率</div></div>
<div class="stat-card"><div class="num">~27KB</div><div class="label">gzip 体积</div></div> <div class="stat-card"><div class="num">63KB</div><div class="label">gzip 体积</div></div>
<div class="stat-card"><div class="num">5</div><div class="label">存储引擎</div></div> <div class="stat-card"><div class="num">4+3</div><div class="label">存储模式+后端</div></div>
<div class="stat-card"><div class="num">72</div><div class="label">SQL 关键字</div></div> <div class="stat-card"><div class="num">72</div><div class="label">SQL 关键字</div></div>
<div class="stat-card"><div class="num">76</div><div class="label">测试套件</div></div> <div class="stat-card"><div class="num">91</div><div class="label">测试套件</div></div>
</div> </div>
</div> </div>
</section> </section>
src/engine/aria/index.ts
+195 -49
View File
@@ -1,4 +1,4 @@
import { cloneRow } from '../interface'; import { cloneRow } from '../row_clone';
/** /**
* AriaEngine — 自研页面式存储引擎主类 * AriaEngine — 自研页面式存储引擎主类
* @module engine/aria/index * @module engine/aria/index
@@ -14,7 +14,7 @@ import { stripUndefinedUpdates } from '../../table/schema';
import { compileValidator } from '../../table/validation'; import { compileValidator } from '../../table/validation';
import type { AriaEngineConfig, SSTableMeta } from './types'; import type { AriaEngineConfig, SSTableMeta } from './types';
import { DEFAULT_ARIA_CONFIG, MAX_LSM_LEVELS } from './types'; import { DEFAULT_ARIA_CONFIG } from './types';
import { LSM } from './index/lsm'; import { LSM } from './index/lsm';
import type { SSTableStore } from './index/lsm'; import type { SSTableStore } from './index/lsm';
@@ -48,6 +48,8 @@ export interface AriaRecoveryReport {
dataLossSuspected: boolean; dataLossSuspected: boolean;
/** WAL 活跃区间内的分片空洞（已提交事务记录缺失） */ /** WAL 活跃区间内的分片空洞（已提交事务记录缺失） */
walGaps: number[]; walGaps: number[];
/** v0.8.0：CRC 校验失败被跳过的 WAL 记录数（它们承载的写入已丢失） */
droppedWALRecords: number;
/** 本次打开是否从旧格式（__aria_lsm_meta/__aria_schemas）迁移而来 */ /** 本次打开是否从旧格式（__aria_lsm_meta/__aria_schemas）迁移而来 */
legacyImported: boolean; legacyImported: boolean;
/** 是否从更早的 manifest 世代回退（最新世代损坏） */ /** 是否从更早的 manifest 世代回退（最新世代损坏） */
@@ -109,6 +111,7 @@ export class AriaEngine implements IStorageEngine {
droppedSSTables: [], droppedSSTables: [],
dataLossSuspected: false, dataLossSuspected: false,
walGaps: [], walGaps: [],
droppedWALRecords: 0,
legacyImported: false, legacyImported: false,
manifestFallback: false, manifestFallback: false,
}; };
@@ -301,6 +304,17 @@ export class AriaEngine implements IStorageEngine {
allowGaps: true, allowGaps: true,
}); });
const walInfo = this.wal.getLastRecoveryInfo(); const walInfo = this.wal.getLastRecoveryInfo();
if (walInfo && walInfo.corruptRecords > 0) {
// v0.8.0（review 修复）：记录级 CRC 损坏此前只 console.warn —— 恢复完全
// 不感知"少了几条记录"，与"静默丢数据必须显式化"的目标不符。
this.recoveryReport.droppedWALRecords = walInfo.corruptRecords;
this.recoveryReport.dataLossSuspected = true;
// eslint-disable-next-line no-console
console.warn(
`[AriaEngine] WAL: ${walInfo.corruptRecords} record(s) failed CRC and were skipped — ` +
'the writes they carried are missing (recovery report records this)',
);
}
if (walInfo && walInfo.gaps.length > 0) { if (walInfo && walInfo.gaps.length > 0) {
this.recoveryReport.walGaps = [...walInfo.gaps]; this.recoveryReport.walGaps = [...walInfo.gaps];
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
@@ -555,35 +569,46 @@ export class AriaEngine implements IStorageEngine {
* 且 manifest 完整可信时才允许回收空间。 * 且 manifest 完整可信时才允许回收空间。
*/ */
private async cleanupOrphanPages(): Promise<void> { private async cleanupOrphanPages(): Promise<void> {
if (this.recoveryReport.dataLossSuspected || this.recoveryReport.manifestFallback) { const damage = this.describeRecoveryDamage();
if (damage.length > 0) {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn( console.warn(
'[AriaEngine] repair: skipping orphan-page reclamation — recovery report shows ' + `[AriaEngine] repair: skipping orphan reclamation — recovery shows damage (${damage.join('; ')}); ` +
'damage or manifest fallback (unreferenced pages are kept, never deleted blindly)', 'unreferenced data is kept, never deleted blindly',
); );
return; return;
} }
const keys = await this.backend.listKeys(); // v0.8.0（review 修复）：**有在途读者时一律不回收**。
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k)); // 读者的快照可能持有已被 compaction 取代（"退休"）的文件；那些文件的页面
if (pgKeys.length === 0) return; // 既不在 manifest、也不在 levels 里 —— 按"没人引用"删掉它们会让正在进行中的
// 扫描静默少数据。回收只能在没有读者时做。
if (this.allLsms().some((lsm) => lsm.hasActiveReaders())) {
// eslint-disable-next-line no-console
console.warn('[AriaEngine] repair: skipping orphan reclamation — readers are active');
return;
}
const keys = await this.backend.listKeys();
// ---- 被引用的页面 id：manifest + 各层内存视图 + 退休表 ----
const used = new Set<number>(); const used = new Set<number>();
for (const state of Object.values(this.manifest.namespaces)) { for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) { for (const m of state.sstables) {
if (m.pageIds) { if (m.pageIds) for (const pid of m.pageIds) used.add(pid);
for (const pid of m.pageIds) used.add(pid);
} }
} }
}
// 未落盘的页面（正在写入的 SSTable）也不能删
for (const lsm of this.allLsms()) { for (const lsm of this.allLsms()) {
// 未落盘的页面（正在写入的 SSTable）不能删
for (const level of this.getLsmLevels(lsm)) { for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) { for (const meta of level) {
if (meta.pageIds) for (const pid of meta.pageIds) used.add(pid); if (meta.pageIds) for (const pid of meta.pageIds) used.add(pid);
} }
} }
// 退休但尚未物理删除的 SSTable 的页面同样不能删
for (const pid of lsm.getRetiredPageIds()) used.add(pid);
} }
const pgKeys = keys.filter((k) => /^pg_\d+$/.test(k));
const orphanIds = pgKeys const orphanIds = pgKeys
.map((k) => Number(k.slice('pg_'.length))) .map((k) => Number(k.slice('pg_'.length)))
.filter((pid) => !used.has(pid)); .filter((pid) => !used.has(pid));
@@ -592,6 +617,45 @@ export class AriaEngine implements IStorageEngine {
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`); console.warn(`[AriaEngine] repair: reclaimed ${orphanIds.length} orphan page file(s)`);
} }
// ---- 孤儿 SSTable 文件（整 value 路径：sst_<ns>_<id> / sst_<id>）----
// 退休 SSTable 的物理删除是"尽力而为"：删除失败/崩溃会留下既不被 manifest
// 引用、也不在任何层里的文件。页面化路径由上面的 pg_ 回收覆盖；
// 整 value 路径（pageStorage:false / 旧库 / 迁移数据）此前**没有任何回收路径**。
const usedSstIds = new Set<number>();
for (const state of Object.values(this.manifest.namespaces)) {
for (const m of state.sstables) usedSstIds.add(m.id);
}
for (const lsm of this.allLsms()) {
for (const level of this.getLsmLevels(lsm)) {
for (const meta of level) usedSstIds.add(meta.id);
}
for (const id of lsm.getRetiredSstableIds()) usedSstIds.add(id);
}
const orphanSstKeys: string[] = [];
for (const [ns, prefix] of this.sstableKeyPrefixes()) {
const re = new RegExp(`^${prefix}(\\d+)$`);
for (const key of keys) {
const m = re.exec(key);
if (!m) continue;
if (!usedSstIds.has(Number(m[1]))) orphanSstKeys.push(key);
}
void ns;
}
if (orphanSstKeys.length > 0) {
await this.backend.deleteMany(orphanSstKeys);
// eslint-disable-next-line no-console
console.warn(`[AriaEngine] repair: reclaimed ${orphanSstKeys.length} orphan SSTable file(s)`);
}
}
/** v0.8.0：命名空间 → SSTable 文件 key 前缀（与 createSSTableStore 保持一致） */
private sstableKeyPrefixes(): [string, string][] {
const out: [string, string][] = [['main', 'sst_']];
for (const ns of Object.keys(this.manifest.namespaces)) {
if (ns !== 'main') out.push([ns, `sst_${ns}_`]);
}
return out;
} }
/** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */ /** v0.8.0: 读取某个 LSM 当前引用的层结构（诊断/孤儿回收用） */
@@ -2064,6 +2128,61 @@ export class AriaEngine implements IStorageEngine {
await this.commitManifest(); await this.commitManifest();
} }
/**
* v0.8.0（review 修复）：表结构记录的**唯一**解析实现。
*
* 为什么必须集中且严格：结构记录有两种坏法 —— JSON 本身就坏了，或 JSON 合法但
* 形状不对（数组 / null / 表名映射到非对象 / 列定义不是对象）。修复前只有
* "JSON 坏"这一种会抛错，形状不对则被**静默忽略** → 打开后看不到任何表，
* 表现为"库是空的"（与审计里"静默空库"同一类缺陷）。
*
* 判定原则：只要记录存在却不可用，就抛 ARIA_LEGACY_META_CORRUPT —— 宁可让
* 调用方看到明确的损坏错误，也不假装这是一个没有表的空库。
*/
private parseSchemaRecord(raw: ArrayBuffer, source: string): Record<string, Record<string, ColumnDef>> {
let parsed: unknown;
try {
parsed = JSON.parse(new TextDecoder().decode(raw));
} catch (error) {
throw new DatabaseError(
`${source} is corrupt and cannot be loaded: ${(error as Error).message}`,
'ARIA_LEGACY_META_CORRUPT',
error,
);
}
return this.validateSchemaShape(parsed, source);
}
/** 形状校验（与 parseSchemaRecord 分离：便于直接喂各种形状做单测） */
private validateSchemaShape(parsed: unknown, source: string): Record<string, Record<string, ColumnDef>> {
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new DatabaseError(
`${source} is not a table-name → columns object (got ${Array.isArray(parsed) ? 'array' : typeof parsed})`,
'ARIA_LEGACY_META_CORRUPT',
);
}
const out: Record<string, Record<string, ColumnDef>> = {};
for (const [tableName, columns] of Object.entries(parsed as Record<string, unknown>)) {
if (!columns || typeof columns !== 'object' || Array.isArray(columns)) {
throw new DatabaseError(
`${source} entry "${tableName}" is not a column map (got ${Array.isArray(columns) ? 'array' : typeof columns})`,
'ARIA_LEGACY_META_CORRUPT',
);
}
for (const [colName, def] of Object.entries(columns as Record<string, unknown>)) {
if (!def || typeof def !== 'object' || Array.isArray(def)) {
throw new DatabaseError(
`${source} entry "${tableName}.${colName}" is not a column definition ` +
`(got ${Array.isArray(def) ? 'array' : typeof def})`,
'ARIA_LEGACY_META_CORRUPT',
);
}
}
out[tableName] = columns as Record<string, ColumnDef>;
}
return out;
}
private async loadSchemas(): Promise<void> { private async loadSchemas(): Promise<void> {
// 权威来源：manifest（旧格式已在 importLegacyState 阶段导入） // 权威来源：manifest（旧格式已在 importLegacyState 阶段导入）
let data = this.manifest.schemas ?? {}; let data = this.manifest.schemas ?? {};
@@ -2073,20 +2192,9 @@ export class AriaEngine implements IStorageEngine {
if (Object.keys(data).length === 0) { if (Object.keys(data).length === 0) {
const raw = await this.backend.read('__aria_schemas'); const raw = await this.backend.read('__aria_schemas');
if (raw) { if (raw) {
try {
const parsed = JSON.parse(new TextDecoder().decode(raw)) as Record<string, Record<string, ColumnDef>>;
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
data = parsed;
this.manifest.schemas = parsed;
}
} catch (error) {
// 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库） // 修复前这里 `catch {}` 静默忽略 → 坏 schema = 看不到任何表（静默空库）
throw new DatabaseError( data = this.parseSchemaRecord(raw, 'Schema record "__aria_schemas"');
`Schema record is corrupt and cannot be loaded: ${(error as Error).message}`, this.manifest.schemas = data;
'ARIA_LEGACY_META_CORRUPT',
error,
);
}
} }
} }
@@ -2102,6 +2210,38 @@ export class AriaEngine implements IStorageEngine {
// v0.8.0（B-6）：单一提交点与命名空间工厂 // v0.8.0（B-6）：单一提交点与命名空间工厂
// ======================================================================= // =======================================================================
/**
* v0.8.0（review 修复）: 本次打开/修复过程中出现过的**一切损坏迹象**。
*
* 为什么需要它而不是只看 `this.recoveryReport.dataLossSuspected`：
* SSTable 被丢弃这一事实记录在**各 LSM** 的报告里，引擎层的 `dataLossSuspected`
* 只在"WAL 水位已推进、被丢的数据没有 WAL 兜底"时才置位。于是"manifest 已被
* 推进 + 某个 SSTable 因文件损坏被丢"这类**真损坏**会在引擎层看不到 —— 孤儿页
* 回收就会照常执行，把在途/退休文件按"没人引用"删掉。
*
* 判定原则：只要有任何"曾经自愈/丢失/回退"的迹象，就一律不回收任何未被引用
* 的文件（宁可留空间，也不可逆地删数据）。
*/
private describeRecoveryDamage(): string[] {
const reasons: string[] = [];
if (this.recoveryReport.manifestFallback) reasons.push('manifest fallback to previous generation');
if (this.recoveryReport.dataLossSuspected) reasons.push('engine-level data loss suspected');
if (this.recoveryReport.walGaps.length > 0) {
reasons.push(`WAL segment gap(s) ${this.recoveryReport.walGaps.join(',')}`);
}
if (this.recoveryReport.droppedWALRecords > 0) {
reasons.push(`${this.recoveryReport.droppedWALRecords} corrupt WAL record(s)`);
}
for (const lsm of this.allLsms()) {
const r = lsm.getRecoveryReport();
if (r.droppedSSTables.length > 0) {
reasons.push(`${r.namespace}: ${r.droppedSSTables.length} dropped SSTable(s)`);
}
if (r.dataLossSuspected) reasons.push(`${r.namespace}: LSM data loss suspected`);
}
return reasons;
}
/** /**
* v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。 * v0.8.0: 恢复诊断（打开时被丢弃的 SSTable、WAL 空洞、是否怀疑数据丢失）。
* *
@@ -2123,6 +2263,7 @@ export class AriaEngine implements IStorageEngine {
droppedSSTables: dropped, droppedSSTables: dropped,
dataLossSuspected: dataLoss, dataLossSuspected: dataLoss,
walGaps: [...this.recoveryReport.walGaps], walGaps: [...this.recoveryReport.walGaps],
droppedWALRecords: this.recoveryReport.droppedWALRecords,
legacyImported: this.recoveryReport.legacyImported, legacyImported: this.recoveryReport.legacyImported,
manifestFallback: this.recoveryReport.manifestFallback, manifestFallback: this.recoveryReport.manifestFallback,
}; };
@@ -2236,6 +2377,17 @@ export class AriaEngine implements IStorageEngine {
* - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。 * - 全部落盘 → 推进到当前 LSN（这些记录已存在于已提交的 SSTable 中）。
*/ */
private computeDurableLsn(intents: ManifestFrozenIntent[]): number { private computeDurableLsn(intents: ManifestFrozenIntent[]): number {
// v0.8.0（review 修复 P0）：**事务进行中一律不得推进水位**。
//
// 事务内的写入只落在 `txnSnapshot`（内存）+ WAL 里，**不进 LSM memtable**
// —— 因此 `hasPendingFlushData()`（只看 memtable/frozen）会说"没有未落盘数据"，
// 水位就被推到当前 LSN 并按该水位删掉旧分片。而此时事务记录既不在 SSTable
// 也不在 memtable：随后 `COMMIT`（返回成功）→ 崩溃 → 重开时那些 INSERT 记录
// 因 `lsn <= startLsn` 被跳过、只剩 COMMIT 记录 → **已确认提交的事务整批消失**，
// 且恢复报告是"干净"的（实测复现）。
//
// 水位是"这些 LSN 已存在于已提交 SSTable 中"的断言，而活跃事务的数据不满足它。
if (this.currentTxnId !== null) return this.durableLsn;
if (intents.length > 0) { if (intents.length > 0) {
return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze))); return Math.min(this.durableLsn, Math.min(...intents.map((i) => i.lsnAtFreeze)));
} }
@@ -2251,6 +2403,17 @@ export class AriaEngine implements IStorageEngine {
* 否则又会出现"同一语义多处实现、只改一处"的老问题。 * 否则又会出现"同一语义多处实现、只改一处"的老问题。
*/ */
private async advanceWalCheckpoint(): Promise<void> { private async advanceWalCheckpoint(): Promise<void> {
// v0.8.0（review 修复 P0）：事务活跃时整条水位推进 + 分片回收都不做。
// 与 `CheckpointManager` 的两个回调同一守卫；这里放在入口处，
// 使 repair()/close()/周期 checkpoint 三条路径全部覆盖（它们此前只有后两条有守卫）。
if (this.currentTxnId !== null) {
// eslint-disable-next-line no-console
console.warn(
'[AriaEngine] WAL checkpoint deferred: an active transaction may hold data ' +
'that exists only in memory + WAL (advancing the durable watermark would drop it)',
);
return;
}
await this.wal.flush(); await this.wal.flush();
// 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准 // 1. 先算：以"如果没有未落盘数据，水位会到哪里"为基准
const target = this.hasPendingFlushData() const target = this.hasPendingFlushData()
@@ -2331,20 +2494,10 @@ export class AriaEngine implements IStorageEngine {
// 2. 表结构（__aria_schemas） // 2. 表结构（__aria_schemas）
const schemaRaw = await this.backend.read('__aria_schemas'); const schemaRaw = await this.backend.read('__aria_schemas');
if (schemaRaw) { if (schemaRaw) {
try { // 与 loadSchemas 走**同一个**校验实现（形状不对同样抛错，绝不静默空库）
const parsed = JSON.parse(new TextDecoder().decode(schemaRaw)) as Record<string, Record<string, ColumnDef>>; this.manifest.schemas = this.parseSchemaRecord(schemaRaw, 'Legacy schema record "__aria_schemas"');
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
this.manifest.schemas = parsed;
imported = true; imported = true;
} }
} catch (error) {
throw new DatabaseError(
`Legacy schema record "__aria_schemas" is corrupt and cannot be migrated: ${(error as Error).message}`,
'ARIA_LEGACY_META_CORRUPT',
error,
);
}
}
// 3. 页面水位（__aria_meta，仅作为单调下限） // 3. 页面水位（__aria_meta，仅作为单调下限）
const pageMeta = await this.backend.read('__aria_meta'); const pageMeta = await this.backend.read('__aria_meta');
@@ -2379,8 +2532,6 @@ export class AriaEngine implements IStorageEngine {
if (intents.length === 0) return; if (intents.length === 0) return;
if (replayedRecordCount > 0) return; // WAL 覆盖到了这些数据（重放会重建） if (replayedRecordCount > 0) return; // WAL 覆盖到了这些数据（重放会重建）
if (!this.config.walEnabled) return; // 未启用 WAL：本来就没有日志兜底（配置语义） if (!this.config.walEnabled) return; // 未启用 WAL：本来就没有日志兜底（配置语义）
// 全部 LSM 已落盘（意图来自上一次会话的残留）→ 数据其实已经安全
if (!this.hasPendingFlushData() && this.manifest.frozen.length === 0) return;
const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', '); const summary = intents.map((i) => `${i.ns}#${i.id}(${i.entryCount} 项)`).join(', ');
throw new DatabaseError( throw new DatabaseError(
@@ -2975,16 +3126,11 @@ export class AriaEngine implements IStorageEngine {
// → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回 // → 墓碑与历史版本在最底层永久累积），且无论是否真的合并过都返回
// `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。 // `compactedLevels: 6`（"报告的数字与事实无关"，审计 item 52）。
// 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。 // 现在逐层尝试（含底部层的原地合并 —— 它会回收墓碑），只统计真正合并了的层。
let compactedLevels = 0; // 逐层压缩交给 LSM：它会把这些任务挂到**维护链**上串行执行 ——
const isBottom = (level: number): boolean => level === MAX_LSM_LEVELS - 1; // 直接 `await compactLevel()` 会与后台 compaction 并发写同一层的产物，
for (let level = 0; level < MAX_LSM_LEVELS; level++) { // 而产物一律 unshift 到队首（层内顺序 = 新旧顺序）→ 旧数据可能排到新数据
const files = this.lsm.getStats().levelCounts[level] ?? 0; // 之前（读到旧值），底部层还会因丢墓碑让已删除的行复活。
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机 const compactedLevels = await this.lsm.vacuumLevels();
//（删除密集场景下底部层通常就是一个大文件）
const minFiles = isBottom(level) ? 1 : 2;
if (files < minFiles) continue;
if (await this.lsm.compactLevel(level, minFiles)) compactedLevels++;
}
// GC MVCC 版本（保留最新 10 个） // GC MVCC 版本（保留最新 10 个）
const beforeGC = this.mvcc.getGlobalLSN(); const beforeGC = this.mvcc.getGlobalLSN();
this.mvcc.gc(10); this.mvcc.gc(10);
src/engine/aria/index/lsm.ts
+107 -2
View File
@@ -35,6 +35,7 @@ import { DatabaseError } from '../../../constants';
import type { SSTableMeta } from '../types'; import type { SSTableMeta } from '../types';
import type { ManifestFrozenIntent } from '../store/manifest'; import type { ManifestFrozenIntent } from '../store/manifest';
import { import {
DEFAULT_BLOOM_BITS_PER_KEY,
DEFAULT_MEMTABLE_SIZE, DEFAULT_MEMTABLE_SIZE,
MAX_LSM_LEVELS, MAX_LSM_LEVELS,
DEFAULT_LEVEL_SIZE_MULTIPLIER, DEFAULT_LEVEL_SIZE_MULTIPLIER,
@@ -120,6 +121,9 @@ const BACKPRESSURE_FILES = 8;
*/ */
const MAX_READ_STRUCTURE_RETRIES = 16; const MAX_READ_STRUCTURE_RETRIES = 16;
/** 保留的后台故障诊断条数上限（v0.8.0 review 修复：防止无界增长） */
const MAX_BACKGROUND_WARNINGS = 64;
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// 冻结表（pending flush 的一等状态，v0.8.0） // 冻结表（pending flush 的一等状态，v0.8.0）
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@@ -247,6 +251,8 @@ export class LSM {
private readonly namespace: string; private readonly namespace: string;
private readonly walLsnProvider: () => number; private readonly walLsnProvider: () => number;
private readonly requireDurableCoverage: boolean; private readonly requireDurableCoverage: boolean;
/** Bloom Filter 每 key 位数（配置透传到 SSTableBuilder；v0.8.0 审查修复） */
private readonly bloomBitsPerKey: number;
constructor(config: LSMConfig) { constructor(config: LSMConfig) {
this.memtableSizeThreshold = config.memtableSizeThreshold ?? DEFAULT_MEMTABLE_SIZE; this.memtableSizeThreshold = config.memtableSizeThreshold ?? DEFAULT_MEMTABLE_SIZE;
@@ -258,6 +264,9 @@ export class LSM {
this.namespace = config.namespace ?? 'main'; this.namespace = config.namespace ?? 'main';
this.walLsnProvider = config.walLsnProvider ?? (() => 0); this.walLsnProvider = config.walLsnProvider ?? (() => 0);
this.requireDurableCoverage = config.requireDurableCoverage ?? false; this.requireDurableCoverage = config.requireDurableCoverage ?? false;
this.bloomBitsPerKey = Number.isFinite(config.bloomBitsPerKey) && (config.bloomBitsPerKey as number) > 0
? Math.floor(config.bloomBitsPerKey as number)
: DEFAULT_BLOOM_BITS_PER_KEY;
this.recoveryReport = { this.recoveryReport = {
namespace: this.namespace, namespace: this.namespace,
droppedSSTables: [], droppedSSTables: [],
@@ -476,7 +485,7 @@ export class LSM {
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of entries) { for (const [key, value] of entries) {
builder.add(key, value); builder.add(key, value);
} }
@@ -580,6 +589,42 @@ export class LSM {
}); });
} }
/**
* v0.8.0（review 修复）：显式维护（VACUUM）的逐层压缩 —— **与后台 compaction 串行**。
*
* 为什么必须串行：compaction 产物一律 `unshift` 到目标层队首，层内数组顺序即
* "新旧顺序"。若 VACUUM 直接 `await compactLevel()`（绕过维护链），它可能与
* 后台 compaction 同时向**同一层**写产物 —— 旧数据的产物被插到新数据之前，
* 读路径取层内第一个命中 → 读到旧值；底部层还会丢墓碑 → 已删除的行复活。
*
* 实现：每个层的压缩都作为维护链上的一个任务执行并等待其完成（复用
* `compacting` 集合防重入），因此永远不会与后台 compaction 交错。
*
* @returns 真实发生合并的层数
*/
async vacuumLevels(): Promise<number> {
let compacted = 0;
for (let level = 0; level < MAX_LSM_LEVELS; level++) {
// 底部层即使只有 1 个文件也要合并：那正是"墓碑/历史版本回收"的唯一时机
const minFiles = level === MAX_LSM_LEVELS - 1 ? 1 : 2;
// 该层已有 compaction 在跑 → 先等维护链静默（不打断、不并入）
if (this.compacting.has(level)) await this.drainMaintenance();
if (this.levels[level].length < minFiles) continue;
this.compacting.add(level);
await new Promise<void>((resolve) => {
this.enqueueMaintenance(async () => {
try {
if (await this.compactLevelAsync(level, minFiles)) compacted++;
} finally {
this.compacting.delete(level);
resolve();
}
});
});
}
return compacted;
}
/** 背压场景下排队 compaction（写入路径调用） */ /** 背压场景下排队 compaction（写入路径调用） */
private enqueueCompact(level: number): void { private enqueueCompact(level: number): void {
if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) return; if (level > MAX_LSM_LEVELS - 1 || this.compacting.has(level)) return;
@@ -695,6 +740,47 @@ export class LSM {
})(); })();
} }
/**
* v0.8.0（review 修复）：当前是否有在途读者。
*
* 用途：维护路径（repair 的强制回收 / 孤儿清理）必须在没有读者时才能删文件 ——
* 读者的快照可能正持有已被 compaction 取代的"退休"文件。
*/
hasActiveReaders(): boolean {
return this.activeReaders.size > 0;
}
/** v0.8.0：退休但尚未物理删除的 SSTable 所占用的页面 id（孤儿页回收必须把它们算作"在用"） */
getRetiredPageIds(): number[] {
const out: number[] = [];
for (const group of this.retired) {
for (const meta of group.metas) {
if (meta.pageIds) out.push(...meta.pageIds);
}
}
return out;
}
/** v0.8.0：退休但尚未物理删除的 SSTable id（孤儿整 value 文件回收必须排除它们） */
getRetiredSstableIds(): number[] {
const out: number[] = [];
for (const group of this.retired) {
for (const meta of group.metas) out.push(meta.id);
}
return out;
}
/**
* v0.8.0：等待两条链静默（诊断与测试用）。
*
* 生产语义上等价于"当前没有在跑的后台 flush/compaction"；测试用它替代
* `setTimeout(N)` 这类墙钟等待（sleep 不够会误报成产品缺陷）。
*/
async whenIdle(): Promise<void> {
await this.drainChain();
await this.drainMaintenance();
}
/** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */ /** v0.8.0（测试/诊断）：退休但尚未物理删除的 SSTable 数量 */
getRetiredCount(): number { getRetiredCount(): number {
return this.retired.reduce((sum, g) => sum + g.metas.length, 0); return this.retired.reduce((sum, g) => sum + g.metas.length, 0);
@@ -708,6 +794,13 @@ export class LSM {
*/ */
reclaimRetiredNow(): void { reclaimRetiredNow(): void {
if (this.retired.length === 0) return; if (this.retired.length === 0) return;
// v0.8.0（review 修复）：有在途读者时**不得**强制删除 —— 读者的快照可能正持有
// 这些文件，删掉会让它读不到数据（而且会被误判为"文件损坏"）。此时退化为
// 延迟回收（等读者退出后由 reclaimRetired 处理）。
if (this.activeReaders.size > 0) {
this.reclaimRetired();
return;
}
const all = this.retired.flatMap((g) => g.metas); const all = this.retired.flatMap((g) => g.metas);
this.retired = []; this.retired = [];
void (async () => { void (async () => {
@@ -934,7 +1027,7 @@ export class LSM {
} }
const id = await this.sstableStore.allocateId(); const id = await this.sstableStore.allocateId();
const builder = new SSTableBuilder(this.blockSize); const builder = new SSTableBuilder(this.blockSize, this.bloomBitsPerKey);
for (const [key, value] of merged) { for (const [key, value] of merged) {
builder.add(key, value); builder.add(key, value);
} }
@@ -1117,6 +1210,11 @@ export class LSM {
// `getBackgroundWarnings()` 与告警日志提供，错误语义只保留 // `getBackgroundWarnings()` 与告警日志提供，错误语义只保留
// "数据没落盘才算失败"。 // "数据没落盘才算失败"。
this.backgroundWarnings.push(effective); this.backgroundWarnings.push(effective);
// v0.8.0（review 修复）：诊断数组必须有界 —— 长时间运行 + 反复瞬时故障下
// 无界增长等于内存泄漏（只保留最近若干条，足够定位问题）
if (this.backgroundWarnings.length > MAX_BACKGROUND_WARNINGS) {
this.backgroundWarnings.splice(0, this.backgroundWarnings.length - MAX_BACKGROUND_WARNINGS);
}
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn('[AriaEngine LSM] background failure recovered by retry:', effective); console.warn('[AriaEngine LSM] background failure recovered by retry:', effective);
} }
@@ -1283,6 +1381,13 @@ export class LSM {
/** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */ /** 清理无效 SSTable 的 meta 与文件（打开自愈路径）+ 记录恢复诊断 */
private async dropInvalidSSTable(meta: SSTableMeta, reason: string): Promise<void> { private async dropInvalidSSTable(meta: SSTableMeta, reason: string): Promise<void> {
this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason }); this.recoveryReport.droppedSSTables.push({ id: meta.id, level: meta.level, reason });
// v0.8.0（review 修复）：meta 被丢弃后必须同时从内存层数组移除。
// 否则 `levels` 会保留一个"manifest 里已不存在、文件也已删除"的幽灵条目 ——
// stats 虚高、每次读都要扫它一遍，且掩盖"内存与 manifest 应当一致"这一不变量。
if (this.levels[meta.level]?.some((m) => m.id === meta.id)) {
this.levels[meta.level] = this.levels[meta.level].filter((m) => m.id !== meta.id);
this.structureVersion++;
}
if (this.requireDurableCoverage) { if (this.requireDurableCoverage) {
// manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底 // manifest 已推进 WAL 水位（startLsn > 0）→ 被丢弃的 SSTable 没有 WAL 兜底
this.recoveryReport.dataLossSuspected = true; this.recoveryReport.dataLossSuspected = true;
src/engine/aria/index/sstable_builder.ts
+17 -2
View File
@@ -34,6 +34,7 @@
*/ */
import { BloomFilter } from './bloom'; import { BloomFilter } from './bloom';
import { DEFAULT_BLOOM_BITS_PER_KEY } from '../types';
import { crc32 } from '../crc32'; import { crc32 } from '../crc32';
import type { IndexEntry } from '../types'; import type { IndexEntry } from '../types';
@@ -54,11 +55,25 @@ interface EncodedEntry {
} }
export class SSTableBuilder { export class SSTableBuilder {
/** Bloom Filter 每 key 位数（由配置透传） */
private bloomBitsPerKey: number;
private entries: [string, Record<string, unknown>][] = []; private entries: [string, Record<string, unknown>][] = [];
private blockSizeLimit: number; private blockSizeLimit: number;
constructor(blockSizeLimit: number = 4096) { /**
* @param blockSizeLimit 块大小上限（字节）
* @param bloomBitsPerKey Bloom Filter 每 key 位数（v0.8.0 审查修复：此前
* 无论 `bloomFilterBitsPerKey` 配成多少，这里都写死用默认值 ——
* 配置项被接受却完全不起作用）
*/
constructor(
blockSizeLimit: number = 4096,
bloomBitsPerKey: number = DEFAULT_BLOOM_BITS_PER_KEY,
) {
this.blockSizeLimit = blockSizeLimit; this.blockSizeLimit = blockSizeLimit;
this.bloomBitsPerKey = Number.isFinite(bloomBitsPerKey) && bloomBitsPerKey > 0
? Math.floor(bloomBitsPerKey)
: DEFAULT_BLOOM_BITS_PER_KEY;
} }
/** 添加一个 key-value 条目（必须按键排序添加） */ /** 添加一个 key-value 条目（必须按键排序添加） */
@@ -81,7 +96,7 @@ export class SSTableBuilder {
})); }));
const blocks = this.splitIntoBlocks(encoded); const blocks = this.splitIntoBlocks(encoded);
const bloomFilter = new BloomFilter(this.entries.length); const bloomFilter = new BloomFilter(this.entries.length, this.bloomBitsPerKey);
// 预计算总大小（字节） // 预计算总大小（字节）
let totalSize = 0; let totalSize = 0;
src/engine/aria/transaction/mvcc.ts
+5 -2
View File
@@ -2,8 +2,11 @@
* AriaEngine MVCC — 多版本并发控制 * AriaEngine MVCC — 多版本并发控制
* @module engine/aria/transaction/mvcc * @module engine/aria/transaction/mvcc
* *
* 实现快照隔离 (Snapshot Isolation)。 * v0.8.0（review 修正文档）：本模块提供**行版本链**，用途是"事务内的 undo"，
* 每个事务看到数据库在事务开始时的快照。 * 提交即清理。它**不提供快照隔离** —— 引擎的隔离语义是"事务串行"（同一实例
* 同时只允许一个事务，并发 `beginTransaction` 抛 `TX_ACTIVE`），读取走
* `txnSnapshot` 未提交快照。旧注释声称 "实现快照隔离 (Snapshot Isolation)"
* 与实现不符（全量审查发现）。
*/ */
import type { RowVersion, TxnEntry } from '../types'; import type { RowVersion, TxnEntry } from '../types';
src/engine/aria/wal/log.ts
+29 -7
View File
@@ -42,7 +42,7 @@ export interface WALStore {
* v0.8.0（可选，分片存储实现）：从指定分片起读取，并把空洞如实返回。 * v0.8.0（可选，分片存储实现）：从指定分片起读取，并把空洞如实返回。
* 未实现的 store 由 WAL 回退为 `readAll()`（无空洞信息）。 * 未实现的 store 由 WAL 回退为 `readAll()`（无空洞信息）。
*/ */
readAllFrom?(fromSegment: number): Promise<WALReadResult>; readAllFrom?(fromSegment: number, fromLsn?: number): Promise<WALReadResult>;
/** /**
* v0.8.0（可选，分片存储实现）：删除整体已落盘的前缀分片， * v0.8.0（可选，分片存储实现）：删除整体已落盘的前缀分片，
* 返回仍需保留的最小分片号。未实现时 WAL 只在"全部已落盘"时整体截断。 * 返回仍需保留的最小分片号。未实现时 WAL 只在"全部已落盘"时整体截断。
@@ -90,7 +90,18 @@ export interface WALRecoveryInfo {
applied: number; applied: number;
skipped: number; skipped: number;
maxLsn: number; maxLsn: number;
/** 活跃区间**内部**的分片空洞（这些分片之后的记录不可信，已丢弃） */
gaps: number[]; gaps: number[];
/**
* v0.8.0（review 修复）：起始分片之前缺失的分片号（"前缀缺失"）。
*
* 与 `gaps` 区分：前缀缺失可能是**正常代价**（manifest 回退到上一代时，
* 它的 `startSegment` 比介质上现存的最小分片更小 —— 那段记录本就被水位跳过），
* 因此不能一律当错误；只有内部空洞才意味着记录真的不可信。
*/
missingPrefix: number[];
/** v0.8.0：CRC 校验失败被跳过的记录数（它们承载的写入已丢失） */
corruptRecords: number;
fromSegment: number; fromSegment: number;
fromLsn: number; fromLsn: number;
} }
@@ -204,11 +215,13 @@ export class WAL {
const fromLsn = opts.fromLsn ?? 0; const fromLsn = opts.fromLsn ?? 0;
let data: Uint8Array; let data: Uint8Array;
let gaps: number[] = []; let gaps: number[] = [];
let missingPrefix: number[] = [];
if (typeof this.store.readAllFrom === 'function') { if (typeof this.store.readAllFrom === 'function') {
const result = await this.store.readAllFrom(fromSegment); const result = await this.store.readAllFrom(fromSegment, fromLsn);
data = result.data; data = result.data;
gaps = result.gaps; gaps = result.gaps;
missingPrefix = result.missingPrefix ?? [];
} else { } else {
const exists = await this.store.exists(); const exists = await this.store.exists();
if (!exists) return 0; if (!exists) return 0;
@@ -223,7 +236,8 @@ export class WAL {
); );
} }
const records = data.byteLength === 0 ? [] : this.decodeAllRecords(data); const decoded = data.byteLength === 0 ? { records: [], corrupt: 0 } : this.decodeAllRecords(data);
const records = decoded.records;
let applied = 0; let applied = 0;
let skipped = 0; let skipped = 0;
let maxLsn = 0; let maxLsn = 0;
@@ -242,7 +256,11 @@ export class WAL {
// 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录 // 磁盘上的全部记录已经读出来了，缓冲区里不再有待落盘记录
this.buffer = []; this.buffer = [];
this.bufferedBytes = 0; this.bufferedBytes = 0;
this.lastRecoveryInfo = { applied, skipped, maxLsn, gaps, fromSegment, fromLsn }; this.lastRecoveryInfo = {
applied, skipped, maxLsn, gaps, missingPrefix,
corruptRecords: decoded.corrupt,
fromSegment, fromLsn,
};
return applied; return applied;
} }
@@ -395,8 +413,9 @@ export class WAL {
return new Uint8Array(buf); return new Uint8Array(buf);
} }
private decodeAllRecords(data: Uint8Array): WALRecord[] { private decodeAllRecords(data: Uint8Array): { records: WALRecord[]; corrupt: number } {
const records: WALRecord[] = []; const records: WALRecord[] = [];
let corrupt = 0;
const view = new DataView(data.buffer, data.byteOffset, data.byteLength); const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
let offset = 0; let offset = 0;
@@ -442,7 +461,10 @@ export class WAL {
const computedLegacy = this.legacyChecksum(recordBytes); const computedLegacy = this.legacyChecksum(recordBytes);
if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) { if ((computedNew >>> 0) !== storedCrc && (computedLegacy >>> 0) !== storedCrc) {
// CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复， // CRC 不匹配，跳过此损坏记录（长度字段链完整时后续好记录仍可恢复，
// 行为由 aria-wal-crc 测试锁定） // 行为由 aria-wal-crc 测试锁定）。
// v0.8.0（review 修复）：跳过必须**被计数**并上报给恢复方 ——
// 否则"少了一条已提交写入"在引擎层完全不可观测（静默丢数据）。
corrupt++;
// eslint-disable-next-line no-console // eslint-disable-next-line no-console
console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`); console.warn(`[AriaEngine WAL] CRC mismatch at record LSN=${lsn}, skipping`);
continue; continue;
@@ -462,6 +484,6 @@ export class WAL {
} }
} }
return records; return { records, corrupt };
} }
} }
src/engine/aria/wal/segmented_store.ts
+45 -14
View File
@@ -45,11 +45,20 @@ export interface WALReadResult {
/** 实际读到的分片号（升序） */ /** 实际读到的分片号（升序） */
segments: number[]; segments: number[];
/** /**
* 活跃区间内的空洞（缺失的分片号）。非空意味着"这之后的记录不可信" —— * 活跃区间**内部**的空洞（缺失的分片号）。非空意味着"这之后的记录不可信" ——
* v0.8.0 起由调用方（WAL/引擎）**显式上报**，不再静默丢弃尾部 * v0.8.0 起由调用方（WAL/引擎）**显式上报**，不再静默丢弃尾部
* （修复前：序号不连续 → 直接把空洞之后的分片全部丢掉且没有任何提示）。 * （修复前：序号不连续 → 直接把空洞之后的分片全部丢掉且没有任何提示）。
*/ */
gaps: number[]; gaps: number[];
/**
* v0.8.0（review 修复）：起始分片**之前**缺失的分片号（前缀缺失）。
*
* 与 `gaps` 分开的原因：前缀缺失可能是正常代价 —— manifest 回退到上一代时，
* 它的 `startSegment` 比介质上现存最小分片更小（那段记录已被水位跳过）。
* 因此前缀缺失**不丢弃后缀分片**、也不当错误；只有 `fromLsn === 0`
*（从未推进过水位 → 分片应当从 fromSegment 连续存在）才把它计入 `gaps`。
*/
missingPrefix: number[];
/** 最后一条记录之后仍缺失的分片数（尾部截断诊断） */ /** 最后一条记录之后仍缺失的分片数（尾部截断诊断） */
missingTail: number; missingTail: number;
} }
@@ -138,26 +147,38 @@ export class SegmentedWALStore implements WALStore {
* 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录， * 同一个连续历史。修复前 `readAll` 遇到空洞直接丢弃空洞之后的全部记录，
* 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。 * 调用方（引擎恢复）完全无法感知"少了一批已提交事务"。
*/ */
async readAllFrom(fromSegment: number = 0): Promise<WALReadResult> { async readAllFrom(fromSegment: number = 0, fromLsn: number = 0): Promise<WALReadResult> {
const keys = await this.backend.listKeys(); const keys = await this.backend.listKeys();
const allSegments = await this.listSegments(); const allSegments = await this.listSegments();
const segments = allSegments.filter((s) => s.seq >= fromSegment); const segments = allSegments.filter((s) => s.seq >= fromSegment);
// 空洞检测：活跃区间内分片序号必须连续。 // ---- 前缀缺失（fromSegment .. segments[0].seq - 1）----
// v0.8.0：**前缀缺失**同样算空洞 —— 调用方（manifest 的 `wal.startSegment`） // v0.8.0（review 修复）：以前这里把前缀缺失也算作空洞，于是"回退到上一代
// 保证"小于 startSegment 的分片已整体落盘、可以不存在"，因此活跃区间内 // manifest"时（上一代的 startSegment 比现存最小分片更小）会命中
// 第一片就缺席（segments[0].seq > fromSegment）意味着那段记录不知所踪。 // `kept = segments.filter(s => s.seq < firstGap)` = 空 —— **整段活 WAL 被丢掉**。
const gaps: number[] = []; // 正确语义：前缀缺失只影响"本就被水位跳过"的那一段，后缀分片必须照常读取。
const missingPrefix: number[] = [];
if (segments.length > 0) { if (segments.length > 0) {
for (let missing = fromSegment; missing < segments[0].seq; missing++) gaps.push(missing); for (let missing = fromSegment; missing < segments[0].seq; missing++) missingPrefix.push(missing);
} }
// ---- 内部空洞（segments[i-1] 与 segments[i] 之间）----
const gaps: number[] = [];
for (let i = 1; i < segments.length; i++) { for (let i = 1; i < segments.length; i++) {
for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) { for (let missing = segments[i - 1].seq + 1; missing < segments[i].seq; missing++) {
gaps.push(missing); gaps.push(missing);
} }
} }
// 从未推进过水位（fromLsn === 0）时，分片本应从 fromSegment 连续存在 →
// 此时前缀缺失同样是异常（介质丢了一段记录），并入 gaps。
if (fromLsn === 0 && missingPrefix.length > 0) {
gaps.unshift(...missingPrefix);
missingPrefix.length = 0;
}
gaps.sort((a, b) => a - b);
// 空洞之后的分片整体丢弃（长度字段链无法跨空洞验证），并计入 diagnostics // 内部空洞之后的分片整体丢弃（长度字段链无法跨空洞验证）；
// 前缀缺失**不**丢弃任何后缀分片。
let kept = segments; let kept = segments;
if (gaps.length > 0) { if (gaps.length > 0) {
const firstGap = gaps[0]; const firstGap = gaps[0];
@@ -220,6 +241,7 @@ export class SegmentedWALStore implements WALStore {
fromSegment, fromSegment,
segments: readSegments, segments: readSegments,
gaps, gaps,
missingPrefix,
missingTail: 0, missingTail: 0,
}; };
} }
@@ -235,8 +257,14 @@ export class SegmentedWALStore implements WALStore {
if (walKeys.length > 0) { if (walKeys.length > 0) {
await this.backend.deleteMany(walKeys); await this.backend.deleteMany(walKeys);
} }
// v0.8.0：分片号只增不减（同 truncateBefore 的说明）—— 复用序号会让 // 分片号**只降不增**是禁止的（同 truncateBefore 的说明）。这里的准确语义是：
// "同一序号对应两代记录"，恢复按序号排序时旧记录可能排在新记录之后被重放。 // 序号绝不回退，且绝不小于 manifest 记录的水位下限（`open(fromSegment)` 会把它
// 抬到 fromSegment）；整体清空后允许复用**最后用过的那个号** —— 这是安全的，
// 因为记录自带 LSN，`lsn <= startLsn` 的旧世代记录在恢复时一律跳过。
//
// 反例（修复前的真实缺陷）：整段清空后把号重置为 0，而 manifest 的
// startSegment 已经是 K>0 → 新记录写进分片 0，恢复时被 `seq >= K` 过滤掉 →
// 已确认写入静默消失。因此这里绝不允许回退到 0。
const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1); const maxSeq = (await this.listSegments()).reduce((max, s) => Math.max(max, s.seq), -1);
this.currentSegment = Math.max(this.currentSegment, maxSeq + 1); this.currentSegment = Math.max(this.currentSegment, maxSeq + 1);
this.currentSize = 0; this.currentSize = 0;
@@ -279,7 +307,10 @@ export class SegmentedWALStore implements WALStore {
*/ */
async planKeepFrom(durableLsn: number, latestLsn?: number): Promise<number> { async planKeepFrom(durableLsn: number, latestLsn?: number): Promise<number> {
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) return 0; // v0.8.0（review 修复）：介质上没有分片时**返回当前分片号**（= 下一条记录将写入
// 的号），而不是 0。返回 0 会让 manifest 的 `startSegment` 回退，与
// "分片号只增不减" 的声明冲突（一旦将来前缀缺失被当作异常，就会误判成丢数据）。
if (segments.length === 0) return this.currentSegment;
// 判定每个分片是否"整段已被水位覆盖"： // 判定每个分片是否"整段已被水位覆盖"：
// - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位 // - 非末分片：下一分片的首条记录 LSN <= durableLsn ⇒ 本分片全部记录都 <= 水位
@@ -331,9 +362,9 @@ export class SegmentedWALStore implements WALStore {
const segments = await this.listSegments(); const segments = await this.listSegments();
if (segments.length === 0) { if (segments.length === 0) {
this.currentSegment = 0; // 无分片可删：分片号保持不变（只增不减），返回下一条记录将写入的号
this.currentSize = 0; this.currentSize = 0;
return 0; return this.currentSegment;
} }
const keepFrom = await this.planKeepFrom(durableLsn, latestLsn); const keepFrom = await this.planKeepFrom(durableLsn, latestLsn);
src/engine/interface.ts
+13 -49
View File
@@ -9,54 +9,12 @@ import type { QueryPlan, TableSchema } from '../constants';
// v0.8.0: 行所有权（row ownership）约定 // v0.8.0: 行所有权（row ownership）约定
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
/** // 行所有权工具（cloneRow / cloneRows）见 `./row_clone` —— v0.8.0 审查修复：
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。 // 它们是运行时实现，必须与被描述为"纯类型"的本文件分开，否则会逃过覆盖率统计。
* // 类型层面的约定（所有引擎必须遵守）：
* 为什么必须做（审计实测）：Memory/KVStore/Hybrid 三个引擎此前把内部行对象 // **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给
* **直接**交给调用方： // 外部，也不得持有调用方传入的行对象引用。违反者会让调用方一次原地修改就
* const rows = await db.query('SELECT * FROM t'); // 改写存储、造成索引与行失配（审计实测：改过的行再也查不出来）。
* rows[0].tag = 'HACKED'; // 存储被改写
* 再查 WHERE tag='HACKED' → 0 行；WHERE tag='x' → 0 行
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
*
* 约定（写入 interface 文档，所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。
*
* 实现说明：结构化克隆可用时优先使用（正确处理 Date/嵌套对象/循环引用）；
* 存储层写入的行已经过 validateRow 的 JSON 安全性检查，因此退化路径也是安全的。
*/
export function cloneRow<T extends Record<string, unknown>>(row: T): T {
if (row === null || typeof row !== 'object') return row;
if (typeof structuredClone === 'function') {
try {
return structuredClone(row);
} catch {
// 含不可克隆值（函数/Proxy）时退化为逐层复制
}
}
return cloneRowFallback(row) as T;
}
/** 退化实现：递归复制普通对象与数组（保留 Date） */
function cloneRowFallback(value: unknown): unknown {
if (value === null || typeof value !== 'object') return value;
if (value instanceof Date) return new Date(value.getTime());
if (Array.isArray(value)) return value.map((v) => cloneRowFallback(v));
if (value instanceof Uint8Array) return new Uint8Array(value);
if (value instanceof ArrayBuffer) return value.slice(0);
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
out[k] = cloneRowFallback(v);
}
return out;
}
/** 批量深拷贝 */
export function cloneRows<T extends Record<string, unknown>>(rows: T[]): T[] {
return rows.map((r) => cloneRow(r));
}
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// IStorageEngine — 所有存储引擎必须实现的接口 // IStorageEngine — 所有存储引擎必须实现的接口
@@ -172,7 +130,13 @@ export interface IStorageEngine {
// ---- 备份 (可选) ---- // ---- 备份 (可选) ----
/** 在线备份：导出全库一致性快照 */ /**
* 在线备份：导出全库数据快照。
*
* v0.8.0（review 修正文档）：返回的是**调用时刻逐表读取的结果**，不构成
* "跨表一致性快照" —— 实现没有冻结全局版本（读取期间不会有并发写入时结果
* 是一致的，但并发写入下不同表可能落在不同时间点）。
*/
backup?(): Promise<Record<string, Record<string, unknown>[]>>; backup?(): Promise<Record<string, Record<string, unknown>[]>>;
// ---- 自愈/重置 (可选，v0.4.2-fix) ---- // ---- 自愈/重置 (可选，v0.4.2-fix) ----
src/engine/memory.ts
+1 -1
View File
@@ -6,7 +6,7 @@
import type { IStorageEngine } from './interface'; import type { IStorageEngine } from './interface';
import type { QueryPlan, TableSchema, WhereCondition } from '../constants'; import type { QueryPlan, TableSchema, WhereCondition } from '../constants';
import { DatabaseError } from '../constants'; import { DatabaseError } from '../constants';
import { cloneRow } from './interface'; import { cloneRow } from './row_clone';
import { matchWhere, applyOrderBy, projectColumns } from '../query/where-matcher'; import { matchWhere, applyOrderBy, projectColumns } from '../query/where-matcher';
import { stripUndefinedUpdates } from '../table/schema'; import { stripUndefinedUpdates } from '../table/schema';
import { compileValidator, type RowValidator } from '../table/validation'; import { compileValidator, type RowValidator } from '../table/validation';
src/engine/row_clone.ts
+65
View File
@@ -0,0 +1,65 @@
/**
* metona-sqlark — 行所有权（row ownership）工具
* @module engine/row_clone
*
* v0.8.0（审查修复）：这三个函数此前放在 `engine/interface.ts`（被文档描述为
* "纯类型声明、可执行语句为 0、因此不纳入覆盖率统计"）。它们其实是**运行时实现**
* 且被 Memory 引擎与 AriaEngine 的读路径调用 —— 放在纯类型文件里等于让真实实现
* 代码逃过覆盖率口径（同一类"统计口径虚高"问题正是 G5 门禁要根治的）。
* 现在实现搬到本模块，`interface.ts` 回到纯类型。
*/
/**
* 深拷贝一行，使调用方**无法通过修改返回值改写存储**。
*
* 为什么必须做（审计实测）：Memory/KVStore/Hybrid 三个引擎此前把内部行对象
* **直接**交给调用方：
* const rows = await db.query('SELECT * FROM t');
* rows[0].tag = 'HACKED'; // 存储被改写
* 再查 WHERE tag='HACKED' → 0 行；WHERE tag='x' → 0 行
* 即调用方一次无意的原地修改就能让索引与行失配、该行永久查不出来（Aria 因为是
* 反序列化路径反而幸免，于是又成了跨引擎行为差异）。
*
* 约定（所有引擎必须遵守）：
* **读出的行是副本，写入接收的行也是副本** —— 引擎不得把内部行对象暴露给外部，
* 也不得持有调用方传入的行对象引用。
*
* 实现说明：结构化克隆可用时优先使用；退化路径（`cloneRowFallback`）逐层复制
* 普通对象/数组，并额外保留 Date、Uint8Array、ArrayBuffer。
*
* 前提：存储层写入的行已经过 `validateRow` 的 JSON 安全性检查 —— 例如 `date`
* 列要求的是**合法日期字符串**而不是 Date 实例（`table/validation.ts`），因此
* 行内永远是 JSON 安全值，"环境提供的 structuredClone 是否保留 Date"不影响
* 引擎行为（jsdom 的 structuredClone 是 JSON 化 polyfill，会把 Date 变字符串；
* 真实浏览器与 Node 的原生实现会保留）。
*/
export function cloneRow<T extends Record<string, unknown>>(row: T): T {
if (row === null || typeof row !== 'object') return row;
if (typeof structuredClone === 'function') {
try {
return structuredClone(row);
} catch {
// 含不可克隆值（函数/Proxy）时退化为逐层复制
}
}
return cloneRowFallback(row) as T;
}
/** 退化实现：递归复制普通对象与数组（保留 Date） */
function cloneRowFallback(value: unknown): unknown {
if (value === null || typeof value !== 'object') return value;
if (value instanceof Date) return new Date(value.getTime());
if (Array.isArray(value)) return value.map((v) => cloneRowFallback(v));
if (value instanceof Uint8Array) return new Uint8Array(value);
if (value instanceof ArrayBuffer) return value.slice(0);
const out: Record<string, unknown> = {};
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
out[k] = cloneRowFallback(v);
}
return out;
}
/** 批量深拷贝 */
export function cloneRows<T extends Record<string, unknown>>(rows: T[]): T[] {
return rows.map((r) => cloneRow(r));
}
tests/engine/aria-wal-segment.test.ts
+112 -4
View File
@@ -25,6 +25,15 @@ function uniqueDB(): string {
const enc = (s: string) => new Uint8Array(new TextEncoder().encode(s)); const enc = (s: string) => new Uint8Array(new TextEncoder().encode(s));
/** 构造"首 4 字节为大端 LSN"的记录（分片的水位判定依赖它） */
function rec(lsn: number, pad = ''): Uint8Array {
const filler = enc(pad.padEnd(4, '.'));
const out = new Uint8Array(4 + filler.byteLength);
new DataView(out.buffer).setUint32(0, lsn, false);
out.set(filler, 4);
return out;
}
describe('AriaEngine — SegmentedWALStore 单元', () => { describe('AriaEngine — SegmentedWALStore 单元', () => {
it('append → readAll 往返，多批次字节顺序一致', async () => { it('append → readAll 往返，多批次字节顺序一致', async () => {
const backend = new MemoryBackend(); const backend = new MemoryBackend();
@@ -62,7 +71,7 @@ describe('AriaEngine — SegmentedWALStore 单元', () => {
await backend.close(); await backend.close();
}); });
it('空洞检测：分片序号不连续 → 空洞后的分片整体丢弃', async () => { it('尾部分片缺失（无法与更后分片比较）→ 已读到的分片仍然返回', async () => {
const backend = new MemoryBackend(); const backend = new MemoryBackend();
await backend.open('seg-unit-3'); await backend.open('seg-unit-3');
const store = new SegmentedWALStore(backend, 16); const store = new SegmentedWALStore(backend, 16);
@@ -75,21 +84,120 @@ describe('AriaEngine — SegmentedWALStore 单元', () => {
await backend.delete('__wal_000001.bin'); await backend.delete('__wal_000001.bin');
const all = await store.readAll(); const all = await store.readAll();
// 空洞在分片 1 → 1 及之后丢弃，只保留分片 0 // 介质上只剩分片 0：没有更后的分片作为参照，缺失的"尾部"无法被识别成空洞
//（这是介质信息本身的限制 —— 尾部丢失只能靠 manifest.nextLsn 之外的证据发现）
expect(new TextDecoder().decode(all)).toBe('SEG0-SEG0-S'); expect(new TextDecoder().decode(all)).toBe('SEG0-SEG0-S');
await backend.close(); await backend.close();
}); });
it('空洞在开头（分片 0 缺失）→ 全部丢弃（保守截断）', async () => { it('前缀缺失：水位未推进（fromLsn=0）→ 全部丢弃；水位已推进 → 后缀照常读取', async () => {
const backend = new MemoryBackend(); const backend = new MemoryBackend();
await backend.open('seg-unit-4'); await backend.open('seg-unit-4');
const store = new SegmentedWALStore(backend, 16); const store = new SegmentedWALStore(backend, 3); // 2 字节记录 → 每条一个分片
await store.append(enc('X0')); await store.append(enc('X0'));
await store.append(enc('X1')); await store.append(enc('X1'));
await backend.delete('__wal_000000.bin'); await backend.delete('__wal_000000.bin');
// 从未推进过水位：分片本应从 0 连续存在 → 前缀缺失是异常，保守丢弃
const all = await store.readAll(); const all = await store.readAll();
expect(all.byteLength).toBe(0); expect(all.byteLength).toBe(0);
// 水位已推进（例如回退到上一代 manifest，startSegment/startLsn 指向更早的位置）：
// 前缀那一段本就被水位跳过，**不能**因此丢弃后面的活分片
const fromLater = await store.readAllFrom(0, 1);
expect(new TextDecoder().decode(fromLater.data)).toBe('X1');
expect(fromLater.missingPrefix).toEqual([0]);
expect(fromLater.gaps).toEqual([]);
await backend.close();
});
it('内部空洞：空洞之后的分片整体丢弃，并把空洞号上报', async () => {
const backend = new MemoryBackend();
await backend.open('seg-unit-4b');
const store = new SegmentedWALStore(backend, 8); // 8 字节记录 → 每条一个分片
await store.append(rec(1, 'aaaa')); // 分片 0
await store.append(rec(2, 'bbbb')); // 分片 1
await store.append(rec(3, 'cccc')); // 分片 2
expect((await store.readAllFrom(0, 0)).segments).toEqual([0, 1, 2]);
await backend.delete('__wal_000001.bin'); // 内部空洞
const result = await store.readAllFrom(0, 0);
expect(result.segments).toEqual([0]); // 只读了空洞之前的分片
expect(result.gaps).toEqual([1]); // 显式上报（不再静默）
expect(result.data.byteLength).toBe(8); // 只保留空洞之前的分片
expect(new DataView(result.data.buffer, result.data.byteOffset).getUint32(0, false)).toBe(1);
await backend.close();
});
it('整体清空后分片号绝不回退（可以复用最后用过的号，但绝不能回到 0）', async () => {
const backend = new MemoryBackend();
await backend.open('seg-unit-4c');
const store = new SegmentedWALStore(backend, 8); // 8 字节记录 → 每条一个分片
await store.append(rec(1, 'aaaa')); // 分片 0
await store.append(rec(2, 'bbbb')); // 分片 1
await store.append(rec(3, 'cccc')); // 分片 2
expect((await store.readAllFrom(0, 0)).segments).toEqual([0, 1, 2]);
await store.truncate();
expect((await backend.listKeys()).length).toBe(0); // 介质上确实没有分片了
await store.append(rec(4, 'dddd'));
const walKeys = (await backend.listKeys()).filter((k) => k.startsWith('__wal_'));
expect(walKeys).toHaveLength(1);
const newSeq = Number(walKeys[0].match(/^__wal_(\d{6,})\.bin$/)![1]);
// 关键不变量：不回退到 0（回退 + manifest.startSegment>0 = 新记录被恢复过滤掉）
expect(newSeq).toBeGreaterThanOrEqual(2);
expect(walKeys).not.toContain('__wal_000000.bin');
// 清空后从新分片号读取仍能读回新记录（该契约不能被破坏）
const after = await store.readAllFrom(newSeq, 0);
expect(after.data.byteLength).toBe(8);
expect(new DataView(after.data.buffer, after.data.byteOffset).getUint32(0, false)).toBe(4);
await backend.close();
});
it('写入永不落到 manifest 水位下限之下（startSegment=K → 新分片号 >= K）', async () => {
const backend = new MemoryBackend();
await backend.open('seg-unit-4e');
const store = new SegmentedWALStore(backend, 8);
await store.append(rec(1, 'aaaa')); // 分片 0（首条 LSN=1）
await store.append(rec(2, 'bbbb')); // 分片 1（首条 LSN=2）
await store.append(rec(3, 'cccc')); // 分片 2（首条 LSN=3）
// 模拟 checkpoint：先算水位下限并**提交进 manifest**，再删除前缀分片
const keepFrom = await store.planKeepFrom(3, 3); // 全部记录都已落盘 → 全部可删
expect(keepFrom).toBe(3);
await store.truncateBefore(3, 3);
expect((await backend.listKeys()).filter((k) => k.startsWith('__wal_'))).toEqual([]);
// 之后的新写入必须落在 >= keepFrom 的分片里（否则重开时被 `seq >= startSegment` 过滤 → 静默丢失）
await store.append(rec(4, 'dddd'));
const seqs = (await backend.listKeys())
.filter((k) => k.startsWith('__wal_'))
.map((k) => Number(k.match(/^__wal_(\d{6,})\.bin$/)![1]));
expect(seqs.length).toBeGreaterThan(0);
expect(Math.min(...seqs)).toBeGreaterThanOrEqual(keepFrom);
// 而且从 manifest 的水位下限开始读，这条新记录必须读得到（双向验证）
const reread = await store.readAllFrom(keepFrom, 3);
expect(reread.data.byteLength).toBe(8);
expect(new DataView(reread.data.buffer, reread.data.byteOffset).getUint32(0, false)).toBe(4);
await backend.close();
});
it('活跃区间已被清理（fromSegment > 0，介质上无分片）：新写入从 fromSegment 继续', async () => {
const backend = new MemoryBackend();
await backend.open('seg-unit-4d');
const store = new SegmentedWALStore(backend, 8);
await store.append(enc('AAAA'));
await store.append(enc('BBBB')); // 分片 0、1
// 介质上分片被全部清理，manifest 说 startSegment = 5
const later = await store.readAllFrom(5, 100);
// 一个分片都没有：无法判断缺了哪些号 → 不谎报空洞，也不丢已有数据
expect(later.data.byteLength).toBe(0);
expect(later.segments).toEqual([]);
expect(later.gaps).toEqual([]);
await store.append(enc('EEEE'));
const keys = await backend.listKeys();
expect(keys.some((k) => k === '__wal_000005.bin')).toBe(true); // 从 fromSegment 继续
await backend.close(); await backend.close();
}); });
tests/engine/row-clone.test.ts
+132
View File
@@ -0,0 +1,132 @@
/**
* 行所有权（row ownership）工具测试
*
* 背景（审计 A 类缺陷）：Memory/KVStore/Hybrid 曾把内部行对象直接交给调用方，
* 调用方一次原地修改就能改写存储、让索引与行失配（改过的行再也查不出来）。
* `cloneRow`/`cloneRows` 是这条不变量的唯一实现。
*
* v0.8.0 审查：这三个函数原本放在 `engine/interface.ts`（被描述为"纯类型、
* 不纳入覆盖率"）→ 真实实现代码逃过覆盖率统计。搬到 `engine/row_clone.ts` 后
* 覆盖率立刻暴露：退化路径（`cloneRowFallback`，即 `structuredClone` 不可用/
* 抛错时的逐层复制）**从未被测试**。本文件补上这两条路径。
*/
import { describe, it, expect, afterEach } from '@jest/globals';
import { cloneRow, cloneRows } from '../../src/engine/row_clone';
const originalStructuredClone = (globalThis as { structuredClone?: unknown }).structuredClone;
afterEach(() => {
(globalThis as { structuredClone?: unknown }).structuredClone = originalStructuredClone;
});
describe('cloneRow — structuredClone 可用', () => {
it('深拷贝普通对象与嵌套结构，修改副本不影响源对象', () => {
const source = { id: 'a', v: 1, nested: { deep: [1, 2, { x: true }] } };
const copy = cloneRow(source);
expect(copy).toEqual(source);
expect(copy).not.toBe(source);
expect(copy.nested).not.toBe(source.nested);
copy.nested.deep.push(99);
copy.v = 42;
expect(source.v).toBe(1);
expect(source.nested.deep).toHaveLength(3);
});
it('JSON 安全值深拷贝且逐层独立（行的实际契约）', () => {
// 引擎的读路径只承载 validateRow 之后的 JSON 安全值 —— `date` 列在 schema 层
// 就要求**字符串**（`src/table/validation.ts` 的 'date' 分支），因此行里不会
// 出现 Date 实例。这里断言的是真实契约：值相等 + 逐层不共享引用。
// （不在此处断言 Date 语义：jsdom 的 structuredClone 是 JSON 化的 polyfill，
// 会把 Date 变成字符串；真实浏览器/Node 的 structuredClone 保留 Date，
// 而退化路径的实现也显式保留 —— 见下方 fallback 用例。）
const source = { id: 'a', when: '2026-09-15T00:00:00.000Z', nested: { k: [1, 2] } };
const copy = cloneRow(source);
expect(copy).toEqual(source);
expect(copy.nested.k).not.toBe(source.nested.k);
copy.nested.k.push(3);
expect(source.nested.k).toEqual([1, 2]);
});
it('非对象输入原样返回（null / 数字 / 字符串不参与拷贝）', () => {
expect(cloneRow(null as never)).toBeNull();
expect(cloneRow(7 as never)).toBe(7);
expect(cloneRow('x' as never)).toBe('x');
});
});
describe('cloneRow — structuredClone 不可用（退化路径）', () => {
it('无 structuredClone 时逐层复制：嵌套对象 / 数组 / Date / TypedArray / ArrayBuffer', () => {
(globalThis as { structuredClone?: unknown }).structuredClone = undefined;
const source = {
id: 'a',
nested: { list: [1, { k: 'v' }] },
when: new Date('2026-01-02T03:04:05.000Z'),
bytes: new Uint8Array([1, 2, 3]),
raw: new Uint8Array([9, 8]).buffer,
plain: 'str',
num: 5,
flag: false,
nil: null,
};
const copy = cloneRow(source);
expect(copy).toEqual(source);
expect(copy).not.toBe(source);
expect(copy.nested).not.toBe(source.nested);
expect(copy.nested.list).not.toBe(source.nested.list);
expect(copy.when).toBeInstanceOf(Date);
expect(copy.when.getTime()).toBe(source.when.getTime());
expect(copy.bytes).toBeInstanceOf(Uint8Array);
expect(Array.from(copy.bytes)).toEqual([1, 2, 3]);
expect(copy.bytes).not.toBe(source.bytes);
expect(copy.raw).toBeInstanceOf(ArrayBuffer);
expect(copy.raw).not.toBe(source.raw);
expect(new Uint8Array(copy.raw as ArrayBuffer)).toEqual(new Uint8Array([9, 8]));
// 深拷贝语义：改副本不影响源
copy.nested.list.push({ k: 'mutated' });
(copy.bytes as Uint8Array)[0] = 99;
expect(source.nested.list).toHaveLength(2);
expect(source.bytes[0]).toBe(1);
});
it('structuredClone 抛错（含不可克隆值）时也退化到逐层复制', () => {
(globalThis as { structuredClone?: unknown }).structuredClone = () => {
throw new Error('could not be cloned');
};
const fn = (): number => 1;
const source = { id: 'a', fn, nested: { k: 1 } };
const copy = cloneRow(source);
expect(copy.id).toBe('a');
expect(copy.fn).toBe(fn); // 函数按引用保留（不可克隆值的合理退化）
expect(copy.nested).toEqual({ k: 1 });
expect(copy.nested).not.toBe(source.nested);
});
it('退化路径对原始值同样原样返回', () => {
(globalThis as { structuredClone?: unknown }).structuredClone = undefined;
expect(cloneRow(null as never)).toBeNull();
expect(cloneRow(3 as never)).toBe(3);
});
});
describe('cloneRows — 批量拷贝', () => {
it('每行都是独立副本（改一行不影响其它行，也不影响源数组）', () => {
const rows = [{ id: 'a', tags: ['x'] }, { id: 'b', tags: ['y'] }];
const copies = cloneRows(rows);
expect(copies).toEqual(rows);
expect(copies).toHaveLength(2);
copies[0].tags.push('mutated');
expect(rows[0].tags).toEqual(['x']);
expect(copies[0]).not.toBe(rows[0]);
expect(copies[1]).not.toBe(rows[1]);
});
it('退化路径同样逐行深拷贝', () => {
(globalThis as { structuredClone?: unknown }).structuredClone = undefined;
const rows = [{ id: 'a', nested: { k: 1 } }];
const copies = cloneRows(rows);
copies[0].nested.k = 2;
expect(rows[0].nested.k).toBe(1);
});
});
tests/v080-b6-single-commit-point.test.ts
+800 -25
View File
@@ -83,6 +83,11 @@ class GatedBackend implements IStorageBackend {
failReadPattern: string | null = null; failReadPattern: string | null = null;
/** 这些 key 前缀上的写会抛错 */ /** 这些 key 前缀上的写会抛错 */
failWritePattern: string | null = null; failWritePattern: string | null = null;
/** 粘性门控：一旦命中就持续阻塞（不是只阻塞一次） */
private sticky = false;
/** 同时卡在门上的写次数（>1 即"并发写"，串行化被破坏） */
gatedInFlight = 0;
gatedPeak = 0;
constructor(private inner: IStorageBackend) {} constructor(private inner: IStorageBackend) {}
@@ -93,8 +98,15 @@ class GatedBackend implements IStorageBackend {
this.gate = new Promise((resolve) => { this.releaseGate = resolve; }); this.gate = new Promise((resolve) => { this.releaseGate = resolve; });
} }
/** 粘性门控：`skip` 次之后**所有**匹配写都阻塞（用于观测"是否发生了并发写"） */
armStickyGate(pattern: string, skip = 0): void {
this.sticky = true;
this.armGate(pattern, skip);
}
release(): void { release(): void {
this.gatePattern = null; this.gatePattern = null;
this.sticky = false;
if (this.releaseGate) { this.releaseGate(); this.releaseGate = null; } if (this.releaseGate) { this.releaseGate(); this.releaseGate = null; }
} }
@@ -123,10 +135,16 @@ class GatedBackend implements IStorageBackend {
} else { } else {
// 一次性门控：只阻塞这一次匹配的写；后续写必须能继续（否则测试测到的 // 一次性门控：只阻塞这一次匹配的写；后续写必须能继续（否则测试测到的
// 是"整个介质被冻住"，而不是"某一次 compaction 卡住"） // 是"整个介质被冻住"，而不是"某一次 compaction 卡住"）
this.gatePattern = null; if (!this.sticky) this.gatePattern = null;
const notify = this.onGated; const notify = this.onGated;
if (notify) { this.onGated = null; notify(); } if (notify) { this.onGated = null; notify(); }
this.gatedInFlight++;
this.gatedPeak = Math.max(this.gatedPeak, this.gatedInFlight);
try {
await this.gate; await this.gate;
} finally {
this.gatedInFlight--;
}
} }
} }
return this.inner.write(key, data); return this.inner.write(key, data);
@@ -190,6 +208,54 @@ class FailOnceBackend implements IStorageBackend {
clear(): Promise<void> { return this.inner.clear(); } clear(): Promise<void> { return this.inner.clear(); }
} }
/**
* 纯内存的（无页面）SSTable 存储替身：只做"文件 + meta"这两件与 LSM 语义相关的
* 事，用来把 LSM 行为从具体存储实现里隔离出来。返回 `files`/`metas` 供测试直接
* 制造介质损坏或观察 meta 列表。
*/
function newPlainStore() {
const files = new Map<number, Uint8Array>();
const metas: { id: number; level: number; minKey: string; maxKey: string }[] = [];
let seq = 0;
const store = {
async save(id: number, data: Uint8Array) { files.set(id, data); return { storedSize: data.byteLength }; },
async load(id: number) { return files.get(id) ?? null; },
async delete(id: number) { files.delete(id); },
async allocateId() { return ++seq; },
async listMeta() { return metas as never; },
async saveMeta(m: { id: number; level: number; minKey: string; maxKey: string }) { metas.push(m); },
async deleteMeta(id: number) {
const i = metas.findIndex((m) => m.id === id);
if (i >= 0) metas.splice(i, 1);
},
};
return { files, metas, store };
}
/**
* 给一个 Promise 加"失败上限"：超时抛错（= 测试失败），而**不会**把超时当成
* 成功结果返回。用于"某件事必须发生 / 必须能完成"的断言 —— 这样并发调度慢
* 只会让测试失败得更慢，绝不会让它在实现错误时碰巧通过。
*/
async function withDeadline<T>(p: Promise<T>, ms: number, label: string): Promise<T> {
let timer: ReturnType<typeof setTimeout> | null = null;
try {
return await Promise.race([
p,
new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms: ${label}`)), ms);
}),
]);
} finally {
if (timer) clearTimeout(timer);
}
}
/** 让位 n 个宏任务（jsdom 没有 setImmediate）：只用于"给并发实现机会"，不做时间断言 */
async function yieldMacrotasks(n: number): Promise<void> {
for (let i = 0; i < n; i++) await new Promise<void>((r) => { setTimeout(r, 0); });
}
function openEngine( function openEngine(
dbName: string, dbName: string,
backend: IStorageBackend, backend: IStorageBackend,
@@ -312,7 +378,6 @@ describe('[v0.8.0][B-6] manifest 单一提交点', () => {
}); });
it('提交是"先写后验"：回读不可用 → ARIA_MANIFEST_WRITE_FAILED，内存态不前进', async () => { it('提交是"先写后验"：回读不可用 → ARIA_MANIFEST_WRITE_FAILED，内存态不前进', async () => {
const inner = new MemoryBackend();
const backend = new (class extends MemoryBackend { const backend = new (class extends MemoryBackend {
hideReads = false; hideReads = false;
async read(key: string): Promise<ArrayBuffer | null> { async read(key: string): Promise<ArrayBuffer | null> {
@@ -326,7 +391,6 @@ describe('[v0.8.0][B-6] manifest 单一提交点', () => {
backend.hideReads = true; backend.hideReads = true;
await expect(store.commit()).rejects.toMatchObject({ code: 'ARIA_MANIFEST_WRITE_FAILED' }); await expect(store.commit()).rejects.toMatchObject({ code: 'ARIA_MANIFEST_WRITE_FAILED' });
expect(store.currentGeneration).toBe(0); // 没有假装提交成功 expect(store.currentGeneration).toBe(0); // 没有假装提交成功
void inner;
}); });
it('保留至少两代；本轮没有损坏世代时才清理更早的世代', async () => { it('保留至少两代；本轮没有损坏世代时才清理更早的世代', async () => {
@@ -651,7 +715,7 @@ describe('[v0.8.0][B-6] LSM：flush 重试与错误报告顺序', () => {
const lsm = new LSM({ memtableSizeThreshold: 128, sstableStore: store as never }); const lsm = new LSM({ memtableSizeThreshold: 128, sstableStore: store as never });
for (let i = 0; i < 12; i++) lsm.put(`k${i}`, { v: i }); for (let i = 0; i < 12; i++) lsm.put(`k${i}`, { v: i });
lsm.freezeMemtable(); lsm.freezeMemtable();
await new Promise((r) => setTimeout(r, 20)); await lsm.whenIdle(); // 确定性等待：门控"后台链已跑完"而不是"睡够 20ms"
await expect(lsm.flush()).rejects.toMatchObject({ code: 'ARIA_BACKGROUND_ERROR' }); await expect(lsm.flush()).rejects.toMatchObject({ code: 'ARIA_BACKGROUND_ERROR' });
// 数据没有消失：冻结表仍在、且仍可读 // 数据没有消失：冻结表仍在、且仍可读
@@ -694,7 +758,7 @@ describe('[v0.8.0][B-6] LSM：flush 重试与错误报告顺序', () => {
// 触发后台自动 flush（freezeMemtable → 入链 → 第一次 save 失败 → lastBackgroundError） // 触发后台自动 flush（freezeMemtable → 入链 → 第一次 save 失败 → lastBackgroundError）
for (let i = 0; i < 20; i++) lsm.put(`k${i}`, { v: i }); for (let i = 0; i < 20; i++) lsm.put(`k${i}`, { v: i });
lsm.freezeMemtable(); lsm.freezeMemtable();
await new Promise((r) => setTimeout(r, 30)); await lsm.whenIdle(); // 确定性等待后台链跑完（不靠 sleep）
expect(failuresLeft).toBe(0); // 注入的失败确实发生过 expect(failuresLeft).toBe(0); // 注入的失败确实发生过
// 关键：这一次 flush 必须**真的执行**（早退的话什么都写不出去） // 关键：这一次 flush 必须**真的执行**（早退的话什么都写不出去）
@@ -991,20 +1055,18 @@ describe('[v0.8.0][B-6/55] checkpoint 不再等完整 compaction', () => {
gated.armGate('sst_', 1); gated.armGate('sst_', 1);
await engine.insert('t', [{ id: 'k3', v: 3, pad: big }]); await engine.insert('t', [{ id: 'k3', v: 3, pad: big }]);
await lsm.flushMemtablesOnly(); await lsm.flushMemtablesOnly();
const gatedOutcome = await Promise.race([ // 门控信号本身就是"compaction 已开始且卡在写盘上"的证据；墙钟只作为失败上限
hit.then(() => 'gated'), // （超时 = 测试失败），因此机器再慢也不会"碰巧通过"。
new Promise((r) => setTimeout(() => r('no-compaction'), 5000)), await withDeadline(hit, 15000, '自动 compaction 始终没有开始（门控从未命中）');
]);
expect(gatedOutcome).toBe('gated'); // compaction 确实开始了且被卡住
// compaction 现在卡在门控上（维护链不前进）。写路径必须继续工作： // compaction 现在卡在门控上（维护链不前进）。写路径必须继续工作：
// 修复前 checkpoint → lsm.flush() → drainMaintenance() 会一起卡住 // 修复前 checkpoint → lsm.flush() → drainMaintenance() 会一起卡住
//（v0.6.1 记录的"8~11s 悬崖"的成因之一）。 //（v0.6.1 记录的"8~11s 悬崖"的成因之一）。
const outcome = await Promise.race([ await withDeadline(
engine.insert('t', [{ id: 'after-gate', v: 999, pad: big }]).then(() => 'ok', () => 'error'), engine.insert('t', [{ id: 'after-gate', v: 999, pad: big }]),
new Promise((r) => setTimeout(() => r('BLOCKED'), 5000)), 15000,
]); '写路径被卡住的维护链阻塞（checkpoint 又和 compaction 串在一起了）',
expect(outcome).toBe('ok'); );
gated.release(); gated.release();
await lsm.flush(); await lsm.flush();
@@ -1012,6 +1074,61 @@ describe('[v0.8.0][B-6/55] checkpoint 不再等完整 compaction', () => {
}); });
}); });
describe('[v0.8.0][B-6/review] vacuum 与后台 compaction 严格串行', () => {
it('vacuumLevels 的逐层压缩必须挂在维护链上（同一时刻只允许一个 SSTable 写在飞）', async () => {
const dbName = uniqueDB('b6-vacuum-serial');
const base = new MemoryBackend();
const gated = new GatedBackend(base);
const engine = openEngine(dbName, gated, {
memtableSizeThreshold: 512,
checkpointInterval: 100_000_000,
});
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
pad: { type: 'string' },
}));
const lsm: any = (engine as any).lsm;
const big = 'x'.repeat(600);
// 3 个 level-0 文件（不到触发阈值），第 4 个触发后台 compaction
for (let i = 0; i < 3; i++) {
await engine.insert('t', [{ id: `k${i}`, v: i, pad: big }]);
await lsm.flushMemtablesOnly();
}
expect(lsm.levels[0].length).toBe(3);
// 粘性门控：放行第 4 次 flush 自己的 save，之后**所有** SSTable 写都阻塞
let gateHit: (() => void) | null = null;
const hit = new Promise<void>((resolve) => { gateHit = resolve; });
gated.onGated = () => gateHit?.();
gated.armStickyGate('sst_', 1);
await engine.insert('t', [{ id: 'k3', v: 3, pad: big }]);
await lsm.flushMemtablesOnly();
await withDeadline(hit, 15000, '后台 compaction 没有开始');
// 后台 compaction 卡在写盘上时发起逐层压缩。
//
// 这里直接测 `lsm.vacuumLevels()`（而不是 `engine.vacuum()`）：引擎层 `vacuum()`
// 开头的 `lsm.flush()` 自身会 drainMaintenance，因此"引擎层调用"这条路径恰好
// 被 flush 顺带串行化了 —— 真正需要守住的不变量在 LSM 这一层：**逐层压缩必须
// 作为维护链任务执行**，否则它会绕过链与正在跑的 compaction 并发写介质。
const vacuuming = lsm.vacuumLevels();
// 有限次让位（宏任务）：修复前 vacuum 的写必然在这期间进入介质（它不依赖维护链）
await yieldMacrotasks(50);
expect(gated.gatedPeak).toBe(1); // 绝不允许两个 compaction 同时写
gated.release();
await withDeadline(vacuuming, 15000, 'vacuumLevels 在维护链释放后仍未完成');
await lsm.whenIdle();
expect(gated.gatedPeak).toBe(1);
expect(await engine.count('t')).toBe(4);
const finalRows = await engine.find('t', { table: 't' });
expect(finalRows.map((r) => `${r.id}=${r.v}`).sort()).toEqual(['k0=0', 'k1=1', 'k2=2', 'k3=3']);
});
});
describe('[v0.8.0][B-6] 冻结表意图：已确认写入不得被水位越过', () => { describe('[v0.8.0][B-6] 冻结表意图：已确认写入不得被水位越过', () => {
it('manifest 声称有未落盘冻结表、但 WAL 里什么都没有 → 打开时报 ARIA_WRITE_LOST', async () => { it('manifest 声称有未落盘冻结表、但 WAL 里什么都没有 → 打开时报 ARIA_WRITE_LOST', async () => {
const dbName = uniqueDB('b6-intent-lost'); const dbName = uniqueDB('b6-intent-lost');
@@ -1039,25 +1156,31 @@ describe('[v0.8.0][B-6] 冻结表意图：已确认写入不得被水位越过',
await expect(engine.open(dbName, 1)).rejects.toMatchObject({ code: 'ARIA_WRITE_LOST' }); await expect(engine.open(dbName, 1)).rejects.toMatchObject({ code: 'ARIA_WRITE_LOST' });
}); });
it('冻结表存在时，水位不会推进越过它（manifest 如实记录意图）', async () => { it('冻结表存在时，水位严格低于意图起点（崩溃后这些写入必须能重建）', async () => {
const dbName = uniqueDB('b6-intent-floor'); const dbName = uniqueDB('b6-intent-floor');
const backend = new MemoryBackend(); const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { memtableSizeThreshold: 128 }); // 阈值调大：数据留在 memtable 里，随后手动冻结（模拟"已确认写入但还没落盘"）
const engine = openEngine(dbName, backend, { memtableSizeThreshold: 64 * 1024 * 1024 });
await engine.open(dbName, 1); await engine.open(dbName, 1);
await engine.createTable(SCHEMA()); await engine.createTable(SCHEMA());
await engine.insert('t', rows(20)); await engine.insert('t', rows(20));
// 强行再冻结一份（不 flush），让"待落盘意图"存在
(engine as any).lsm.freezeMemtable(); (engine as any).lsm.freezeMemtable();
const manifest = (await readManifestState(backend))!; // 有意让意图进入 manifest（提交一次）：水位必须**严格低于**意图起点 ——
// 有意让意图进入 manifest（提交一次），断言水位 <= 最早意图的 lsnAtFreeze // 恢复时 `lsn <= startLsn` 的记录会被跳过，取等号就会把这批记录判成"已落盘"。
await (engine as any).commitManifest(); await (engine as any).commitManifest();
const after = (await readManifestState(backend))!; const after = (await readManifestState(backend))!;
void manifest; const intent = after.frozen.find((f) => f.ns === 'main');
expect(after.frozen.length).toBeGreaterThan(0); expect(intent).toBeDefined();
const minIntentLsn = Math.min(...after.frozen.map((f) => f.lsnAtFreeze)); expect(intent!.entryCount).toBeGreaterThan(0); // 意图必须真的有内容
expect(after.wal.startLsn).toBeLessThanOrEqual(minIntentLsn); expect(intent!.lsnAtFreeze).toBeGreaterThan(0);
await engine.close(); expect(after.wal.startLsn).toBeLessThan(intent!.lsnAtFreeze);
// 崩溃语义（不 flush、不 close）：重开时必须靠 WAL 重建这 20 行，且报告干净
const engine2 = openEngine(dbName, backend, { memtableSizeThreshold: 64 * 1024 * 1024 });
await engine2.open(dbName, 1);
expect(await engine2.count('t')).toBe(20);
expect(engine2.getRecoveryReport().dataLossSuspected).toBe(false);
}); });
}); });
@@ -1402,3 +1525,655 @@ describe('[v0.8.0][B-6] manifest 严格校验（任一字段损坏都必须判
expect((await backend.listKeys()).filter((k) => k.startsWith('__aria_manifest_'))).toEqual([]); expect((await backend.listKeys()).filter((k) => k.startsWith('__aria_manifest_'))).toEqual([]);
}); });
}); });
// ===========================================================================
// 7. 回归 review 修复（v0.8.0 审查发现）—— 每条对应一个已证实的缺陷
// ===========================================================================
describe('[review] 事务进行中不得推进 WAL 水位（P0：已提交事务静默丢失）', () => {
it('BEGIN → INSERT → repair() → COMMIT → 崩溃：已提交事务必须完整恢复', async () => {
const dbName = uniqueDB('review-txn-watermark');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend);
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', [{ id: 'base', v: 0 }]);
await engine.vacuum(); // 把基线数据落盘（水位推进）
await engine.beginTransaction();
await engine.insert('t', [{ id: 'tx1', v: 1 }]);
// 关键：事务进行中的维护路径（修复前 repair 会把水位推过事务记录并删掉旧分片）
await engine.repair();
await engine.commitTransaction(); // 已确认提交
// 崩溃语义：同一个介质上换一个引擎实例打开
const engine2 = openEngine(dbName, backend);
await engine2.open(dbName, 1);
const ids = (await engine2.find('t', { table: 't' })).map((r) => r.id).sort();
expect(ids).toEqual(['base', 'tx1']);
expect(engine2.getRecoveryReport().dataLossSuspected).toBe(false);
});
it('事务活跃时 advanceWalCheckpoint 不推进水位、不删分片', async () => {
const dbName = uniqueDB('review-txn-defer');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend);
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', [{ id: 'a', v: 1 }]);
await (engine as any).advanceWalCheckpoint();
const before = (await readManifestState(backend))!.wal;
await engine.beginTransaction();
await engine.insert('t', [{ id: 'b', v: 2 }]);
await (engine as any).advanceWalCheckpoint(); // 应被跳过
const after = (await readManifestState(backend))!.wal;
expect(after.startLsn).toBe(before.startLsn); // 水位没有前进
expect(after.startSegment).toBe(before.startSegment);
await engine.rollbackTransaction();
});
});
describe('[review] WAL 前缀缺失不得丢弃后缀分片（回退世代场景）', () => {
it('fromLsn > 0 时前缀缺失只记诊断，后缀分片照常重放', async () => {
const backend = new MemoryBackend();
await backend.open('wal-prefix');
const store = new SegmentedWALStore(backend, 96);
const wal = new WAL(store, true, 'full');
for (let i = 0; i < 3; i++) {
await wal.append({
type: WALRecordType.INSERT, txnId: 0, tableName: 't', key: `k${i}`,
data: { v: i, pad: 'p'.repeat(48) },
});
}
await backend.delete('__wal_000000.bin'); // 前缀缺失（模拟回退到上一代）
const seen: number[] = [];
const applied = await wal.recover((r) => seen.push(r.lsn), { fromSegment: 0, fromLsn: 1 });
// 修复前：前缀缺失被当成空洞 → kept=[] → 后缀全丢（applied=0）
expect(applied).toBe(2);
expect(seen).toEqual([2, 3]);
expect(wal.getLastRecoveryInfo()!.missingPrefix).toEqual([0]);
expect(wal.getLastRecoveryInfo()!.gaps).toEqual([]);
// fromLsn = 0（从未推进过水位）时前缀缺失仍是真异常
const wal2 = new WAL(new SegmentedWALStore(backend, 96), true, 'full');
await expect(wal2.recover(() => { /* noop */ })).rejects.toMatchObject({ code: 'ARIA_WAL_GAP' });
});
});
describe('[review] WAL 记录级损坏必须进入恢复报告', () => {
it('一条记录 CRC 失败 → corruptRecords > 0 且恢复报告标记丢数据', async () => {
const dbName = uniqueDB('review-wal-corrupt');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend);
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(3));
// 直接损坏 WAL 分片中的一个字节（长度链保持完整，只让 CRC 失败）
const walKeys = (await backend.listKeys()).filter((k) => k.startsWith('__wal_'));
expect(walKeys.length).toBeGreaterThan(0);
const raw = new Uint8Array((await backend.read(walKeys[0]))!);
raw[raw.byteLength - 1] ^= 0xff;
await backend.write(walKeys[0], raw.buffer as ArrayBuffer);
const engine2 = openEngine(dbName, backend);
await engine2.open(dbName, 1);
const report = engine2.getRecoveryReport();
expect(report.droppedWALRecords).toBeGreaterThan(0);
expect(report.dataLossSuspected).toBe(true);
});
});
describe('[review] 退休 SSTable 与在途读者', () => {
it('有在途读者时强制回收必须退化为延迟回收（读者数据完整）', async () => {
const { store } = newPlainStore();
const lsm: any = new LSM({ memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never });
for (let i = 0; i < 20; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
// 读者在 compaction 之前进入：它的快照可能持有马上要被"退休"的文件
const epoch = lsm.enterRead();
await lsm.compactLevel(0, 1);
expect(lsm.hasActiveReaders()).toBe(true);
expect(lsm.getRetiredCount()).toBeGreaterThan(0); // 有读者 → 只登记不删除
// repair() 走的是强制回收路径：有读者时仍必须退化为延迟回收
lsm.reclaimRetiredNow();
expect(lsm.getRetiredCount()).toBeGreaterThan(0);
// 读者在退休文件被删之前读到的数据必须完整
expect(await lsm.rangeScan('', '\uffff')).toHaveLength(20);
lsm.exitRead(epoch);
await lsm.whenIdle();
expect(lsm.getRetiredCount()).toBe(0); // 读者退出 → 物理删除
});
it('退休映射仍可按 id 读取；读者退出后物理删除', async () => {
const dbName = uniqueDB('review-retire-map');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { memtableSizeThreshold: 512, pageStorage: true });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
for (let i = 0; i < 30; i++) await engine.insert('t', [{ id: `k${i}`, v: i }]);
const lsm: any = (engine as any).lsm;
await lsm.flush();
const before = await lsm.sstableStore.listMeta();
const victim = before[0];
const epoch = lsm.enterRead();
await lsm.compactLevel(0, 1);
expect(lsm.getRetiredCount()).toBeGreaterThan(0);
// 修复前的失败模式：摘除 meta 后立刻忘掉 pageIds → 在途读者把"已退休"当"损坏"
const data = await lsm.sstableStore.load(victim.id, victim.pageIds, victim.totalSize);
expect(data).not.toBeNull();
expect(new SSTableReader(data!, victim).get('t:k0')).not.toBeNull();
lsm.exitRead(epoch);
await lsm.whenIdle();
expect(lsm.getRetiredCount()).toBe(0); // 没有更早读者 → 物理删除
});
});
describe('[review] 维护路径的回收门槛与孤儿回收', () => {
it('干净库：孤儿页面与孤儿 SSTable 文件都被回收', async () => {
const dbName = uniqueDB('review-orphan-clean');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { pageStorage: true });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(5));
await (engine as any).lsm.flush();
await backend.write('pg_999999', new ArrayBuffer(16));
await backend.write('sst_999999', new ArrayBuffer(16));
await engine.repair();
expect(await backend.exists('pg_999999')).toBe(false);
expect(await backend.exists('sst_999999')).toBe(false);
});
it('有损坏迹象时：引用不到的东西一律保留（绝不盲删）', async () => {
const dbName = uniqueDB('review-orphan-damaged');
const backend = new MemoryBackend();
const writer = openEngine(dbName, backend, { pageStorage: true });
await writer.open(dbName, 1);
await writer.createTable(SCHEMA());
await writer.insert('t', rows(5));
await (writer as any).lsm.flush();
// 删掉 manifest 引用的活页 → 重开时 dataLossSuspected = true
const manifest = (await readManifestState(backend))!;
const pages = manifest.namespaces.main.sstables[0].pageIds ?? [];
expect(pages.length).toBeGreaterThan(0);
await backend.deleteMany(pages.map((p) => `pg_${p}`));
const reader = openEngine(dbName, backend, { pageStorage: true });
await reader.open(dbName, 1);
expect(reader.getRecoveryReport().dataLossSuspected).toBe(true);
await backend.write('pg_999998', new ArrayBuffer(16));
await reader.repair();
expect(await backend.exists('pg_999998')).toBe(true); // 保留
});
it('有在途读者时 repair 不回收（回收只在没有读者时做）', async () => {
const dbName = uniqueDB('review-orphan-readers');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { pageStorage: true });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(5));
await (engine as any).lsm.flush();
await backend.write('pg_999997', new ArrayBuffer(16));
const lsm: any = (engine as any).lsm;
const epoch = lsm.enterRead();
await engine.repair();
expect(await backend.exists('pg_999997')).toBe(true); // 有读者 → 不动
lsm.exitRead(epoch);
await engine.repair();
expect(await backend.exists('pg_999997')).toBe(false); // 无读者 → 回收
});
it('repair 的强制回收：有在途读者时退休登记保留，读者退出后清零', async () => {
const dbName = uniqueDB('review-repair-retire');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { memtableSizeThreshold: 512 });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
for (let i = 0; i < 40; i++) await engine.insert('t', [{ id: `k${i}`, v: i }]);
const lsm: any = (engine as any).lsm;
await lsm.flush();
const epoch = lsm.enterRead();
await lsm.compactLevel(0, 1);
expect(lsm.getRetiredCount()).toBeGreaterThan(0); // 正控：退休文件确实被保留
await engine.repair();
expect(lsm.getRetiredCount()).toBeGreaterThan(0); // 有读者 → 不强制删
lsm.exitRead(epoch);
await lsm.whenIdle();
expect(lsm.getRetiredCount()).toBe(0);
expect(await engine.count('t')).toBe(40);
});
});
describe('[review] 内存层数组与 manifest 必须一致', () => {
it('compaction 丢弃损坏文件后 levels 不留幽灵 meta', async () => {
const { files, metas, store } = newPlainStore();
const lsm: any = new LSM({
memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never,
requireDurableCoverage: true, // manifest 水位已推进 → 被丢的数据没有 WAL 兜底
});
for (let i = 0; i < 12; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
const victim = lsm.levels[0][0];
files.set(victim.id, new Uint8Array(64).fill(0xff)); // 文件损坏
lsm.sstableCache.clear(); // 必须真的从介质读，才谈得上发现损坏
await lsm.compactLevel(0, 1);
expect((lsm.levels[0] as { id: number }[]).some((m) => m.id === victim.id)).toBe(false);
expect((metas as { id: number }[]).some((m) => m.id === victim.id)).toBe(false);
const report = lsm.getRecoveryReport();
expect(report.droppedSSTables.some((d: { id: number }) => d.id === victim.id)).toBe(true);
expect(report.dataLossSuspected).toBe(true); // 无 WAL 兜底 → 必须标记丢数据
});
it('介质读故障 ≠ 文件损坏：compaction 必须失败且一个 meta 都不许丢', async () => {
const { store, metas } = newPlainStore();
const lsm: any = new LSM({ memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never });
for (let i = 0; i < 12; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
const victim = lsm.levels[0][0];
const originalLoad = store.load;
lsm.sstableCache.clear(); // 必须真的走介质读
store.load = async () => { throw new Error('injected medium read failure'); };
await expect(lsm.compactLevel(0, 1)).rejects.toMatchObject({ code: 'ARIA_SSTABLE_READ_FAILED' });
// 读故障是可重试的介质问题 —— 既不能丢 meta，也不能删文件
expect((lsm.levels[0] as { id: number }[]).map((m) => m.id)).toEqual([victim.id]);
expect(metas.map((m) => m.id)).toContain(victim.id);
expect(lsm.getRecoveryReport().droppedSSTables).toHaveLength(0);
expect(lsm.getRecoveryReport().dataLossSuspected).toBe(false);
// 介质恢复后同一层可以正常合并，数据不丢
store.load = originalLoad;
expect(await lsm.compactLevel(0, 1)).toBe(true);
expect((await lsm.rangeScan('', '\uffff')).map((e: [string, unknown]) => e[0])).toHaveLength(12);
});
it('文件真的残缺：丢弃必须进恢复报告（不许静默）', async () => {
const { store, metas } = newPlainStore();
const lsm: any = new LSM({ memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never });
for (let i = 0; i < 12; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
const victim = lsm.levels[0][0];
const originalLoad = store.load;
lsm.sstableCache.clear();
store.load = async () => new Uint8Array(8); // 截断到无法解析
await lsm.compactLevel(0, 1);
const report = lsm.getRecoveryReport();
expect(report.droppedSSTables).toHaveLength(1);
expect(report.droppedSSTables[0]).toMatchObject({ id: victim.id, level: 0 });
expect(report.droppedSSTables[0].reason).toContain('truncated');
expect((lsm.levels[0] as { id: number }[]).some((m) => m.id === victim.id)).toBe(false);
expect(metas.some((m) => m.id === victim.id)).toBe(false);
store.load = originalLoad;
});
});
describe('[review] 丢弃损坏文件的两种契约', () => {
it('WAL 仍覆盖时（startLsn=0）：丢弃损坏文件不算"已丢数据"（契约的另一半）', async () => {
const { files, store } = newPlainStore();
const lsm: any = new LSM({
memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never,
requireDurableCoverage: false, // manifest 水位还是 0 → WAL 里仍有全部记录
});
for (let i = 0; i < 12; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
const victim = lsm.levels[0][0];
files.set(victim.id, new Uint8Array(64).fill(0xff));
lsm.sstableCache.clear();
await lsm.compactLevel(0, 1);
const report = lsm.getRecoveryReport();
// 丢弃仍然被记录（可观测），但"数据丢了"不成立：重开时 WAL 会重新放这些记录
expect(report.droppedSSTables.some((d: { id: number }) => d.id === victim.id)).toBe(true);
expect(report.dataLossSuspected).toBe(false);
});
});
describe('[review] 非底部层不得回收墓碑（51 的镜像）', () => {
it('delete 之后在非底部层合并：删除仍然生效（墓碑被保留）', async () => {
const { store } = newPlainStore();
const lsm: any = new LSM({ memtableSizeThreshold: 512, blockSize: 64, sstableStore: store as never });
for (let i = 0; i < 10; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
for (let i = 0; i < 10; i++) lsm.delete(`k${String(i).padStart(3, '0')}`);
await lsm.flush();
// 非底部层合并（level 0 → 1）：墓碑**必须保留**，否则底部层的老数据会复活
await lsm.compactLevel(0, 1);
const found = await lsm.get('k003');
expect(found).toBeNull();
expect(await lsm.rangeScan('', '\uffff')).toHaveLength(0);
});
});
describe('[review] manifest 世代与载荷一致性', () => {
it('文件名世代与载荷世代不一致 → 该世代无效', async () => {
const backend = new MemoryBackend();
await backend.open('gen-mismatch');
const store = new ManifestStore({ backend, instanceId: 'x' });
await store.load();
await store.commit(); // gen 1
// 把 gen 1 的内容复制成 gen 2 的文件名（载荷里仍写着 generation: 1）
const raw = (await backend.read(manifestKey(1)))!;
await backend.write(manifestKey(2), raw);
const loaded = await new ManifestStore({ backend }).load();
// 修复前：只看 CRC 与载荷内部自洽 → 会把"复制/改名"当成有效提交点
expect(loaded.generation).toBe(1);
expect(loaded.hadInvalidGenerations).toBe(true);
expect(loaded.skipped.some((s) => s.generation === 2)).toBe(true);
});
it('写成功但读不回来（介质吞写）→ commit 必须失败，绝不假装提交成功', async () => {
const backend = new MemoryBackend();
await backend.open('manifest-swallow');
// 写返回成功但数据没落地（典型：OPFS libver 竞态 / 缓存未刷）
const swallow = async (): Promise<void> => { /* 吞掉 */ };
const broken = Object.create(backend) as MemoryBackend;
broken.write = swallow as never;
const store = new ManifestStore({ backend: broken, instanceId: 'x' });
await store.load();
await expect(store.commit()).rejects.toMatchObject({ code: 'ARIA_MANIFEST_WRITE_FAILED' });
});
it('写下去的内容读回来是坏的 → commit 同样必须失败（回读校验覆盖两条守卫）', async () => {
const backend = new MemoryBackend();
await backend.open('manifest-write-corrupt');
// 写能"成功"但落地的字节被破坏（撕裂写 / 部分写），文件存在但解不开
const broken = Object.create(backend) as MemoryBackend;
const realWrite = backend.write.bind(backend);
const realRead = backend.read.bind(backend);
broken.write = (async (key: string, data: ArrayBuffer) => {
const copy = new Uint8Array(data).slice();
copy[copy.byteLength - 1] ^= 0xff; // 破坏载荷 CRC
await realWrite(key, copy.buffer as ArrayBuffer);
}) as never;
broken.read = (async (key: string) => realRead(key)) as never;
const store = new ManifestStore({ backend: broken, instanceId: 'x' });
await store.load();
await expect(store.commit()).rejects.toMatchObject({ code: 'ARIA_MANIFEST_WRITE_FAILED' });
expect(store.currentGeneration).toBe(0); // 世代号不得前进
});
it('并发 commit 串行化：两个 commit 不会算出同一个世代号', async () => {
const backend = new MemoryBackend();
await backend.open('concurrent-commit');
const store = new ManifestStore({ backend, instanceId: 'x' });
await store.load();
const results = await Promise.all([store.commit(), store.commit(), store.commit()]);
const gens = results.map((r) => r.generation).sort((a, b) => a - b);
// 串行化：三次提交各得一个**互不相同**的世代号（修复前会算出同一个号并互相覆盖）
expect(gens).toEqual([1, 2, 3]);
expect(new Set(gens).size).toBe(3);
expect(store.currentGeneration).toBe(3);
// 保留策略：只留最后两代（本用例不重复断言保留语义，仅确认磁盘上就是这两代）
const onDisk = (await backend.listKeys())
.map((k) => generationFromKey(k))
.filter((g): g is number => g !== null)
.sort((a, b) => a - b);
expect(onDisk).toEqual([2, 3]);
});
});
describe('[review] 页面 id 水位跨重开不复用', () => {
it('重开后分配的新页面 id 严格大于已存在页面', async () => {
const dbName = uniqueDB('review-pageid');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { pageStorage: true, memtableSizeThreshold: 512 });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(20));
await (engine as any).lsm.flush();
const existingBefore = (await backend.listKeys())
.filter((k) => /^pg_\d+$/.test(k))
.map((k) => Number(k.slice(3)));
const maxBefore = Math.max(...existingBefore);
// 注意：**不能** close —— MemoryBackend.close() 会清空介质（等价于删库）。
// 直接在同一个介质上重开（同时覆盖 manifest 所有权接管路径）。
const engine2 = openEngine(dbName, backend, { pageStorage: true, memtableSizeThreshold: 512 });
await engine2.open(dbName, 1);
await engine2.insert('t', rows(20).map((r) => ({ ...r, id: `n${r.id}` })));
await (engine2 as any).lsm.flush();
const after = (await backend.listKeys())
.filter((k) => /^pg_\d+$/.test(k))
.map((k) => Number(k.slice(3)));
const newPages = after.filter((p) => !existingBefore.includes(p));
expect(newPages.length).toBeGreaterThan(0);
expect(Math.min(...newPages)).toBeGreaterThan(maxBefore); // 绝不复用旧 id
});
it('水位是单调下限：计数器回退也不许把 manifest 水位带回低值', async () => {
const dbName = uniqueDB('review-pageid-monotonic');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { pageStorage: true, memtableSizeThreshold: 512 });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(20));
await (engine as any).lsm.flush();
const wmBefore = (await readManifestState(backend))!.pageIdWatermark;
expect(wmBefore).toBeGreaterThan(1);
// 白盒：模拟"计数器被打回旧值"（新实例忘了水位下限 / 崩溃把计数打回）。
// 不变量：manifest 的 pageIdWatermark 只能单调前进 —— 一旦回退，回收/重建
// 路径就可能把新页面写到已被占用的 id 上（覆盖活数据）。
(engine as any).fileManager.nextPageId = 1;
await (engine as any).commitManifest();
expect((await readManifestState(backend))!.pageIdWatermark).toBeGreaterThanOrEqual(wmBefore);
});
});
// ===========================================================================
// 8. review 补测：危险分支（此前无覆盖或只有空壳断言）
// ===========================================================================
describe('[review] 存储实现违反 save() 契约', () => {
function contractViolatingStore(): { store: Record<string, unknown>; breakIt: () => void } {
const files = new Map<number, Uint8Array>();
const metas: { id: number; level: number; minKey: string; maxKey: string }[] = [];
let seq = 0;
let broken = false;
const store = {
async save(id: number, data: Uint8Array) {
if (broken) return undefined as never; // 违反契约：既不抛错也不返回结果
files.set(id, data);
return { storedSize: data.byteLength };
},
async load(id: number) { return files.get(id) ?? null; },
async delete(id: number) { files.delete(id); },
async allocateId() { return ++seq; },
async listMeta() { return metas as never; },
async saveMeta(m: { id: number; level: number; minKey: string; maxKey: string }) { metas.push(m); },
async deleteMeta(id: number) {
const i = metas.findIndex((m) => m.id === id);
if (i >= 0) metas.splice(i, 1);
},
};
return { store, breakIt: () => { broken = true; } };
}
it('flush 路径：契约被违反 → 重试后显式报错，且绝不假装落盘成功', async () => {
const { store, breakIt } = contractViolatingStore();
const lsm: any = new LSM({ memtableSizeThreshold: 128, sstableStore: store as never });
for (let i = 0; i < 12; i++) lsm.put(`k${i}`, { v: i });
breakIt();
await expect(lsm.flush()).rejects.toMatchObject({ code: 'ARIA_BACKGROUND_ERROR' });
// 数据仍在内存里（冻结表还在）—— 不能因为"写调用返回了"就认为已经落盘
expect(lsm.getStats().frozenTables).toBeGreaterThan(0);
expect(await lsm.get('k0')).toEqual({ v: 0 });
});
it('compaction 路径：契约被违反 → ARIA_SSTABLE_SAVE_CONTRACT（不写入内存层）', async () => {
const { store, breakIt } = contractViolatingStore();
const lsm: any = new LSM({ memtableSizeThreshold: 128, sstableStore: store as never });
for (let i = 0; i < 12; i++) lsm.put(`k${String(i).padStart(3, '0')}`, { v: i });
await lsm.flush();
const level0Before = lsm.levels[0].map((m: { id: number }) => m.id);
breakIt();
await expect(lsm.compactLevel(0, 1)).rejects.toMatchObject({ code: 'ARIA_SSTABLE_SAVE_CONTRACT' });
// 源文件仍留在读取路径上（合并产物没落地 → 不能把源当成已合并）
expect(lsm.levels[0].map((m: { id: number }) => m.id)).toEqual(level0Before);
expect((await lsm.rangeScan('', '\uffff')).map((e: [string, unknown]) => e[0])).toHaveLength(12);
});
});
describe('[review] 旧格式表结构记录的形状校验（静默空库防线）', () => {
async function openWithLegacySchema(raw: string): Promise<unknown> {
const dbName = uniqueDB('review-schema-shape');
const backend = new MemoryBackend();
await backend.open(dbName);
await backend.write('__aria_schemas', new TextEncoder().encode(raw).buffer as ArrayBuffer);
const engine = openEngine(dbName, backend);
return engine.open(dbName, 1);
}
it('JSON 合法但不是对象（数组）→ 报损坏，不当作空库', async () => {
await expect(openWithLegacySchema('[1,2,3]')).rejects.toMatchObject({ code: 'ARIA_LEGACY_META_CORRUPT' });
});
it('JSON 合法但是 null → 报损坏', async () => {
await expect(openWithLegacySchema('null')).rejects.toMatchObject({ code: 'ARIA_LEGACY_META_CORRUPT' });
});
it('表名映射到非对象（字符串）→ 报损坏', async () => {
await expect(openWithLegacySchema('{"t":"oops"}')).rejects.toMatchObject({ code: 'ARIA_LEGACY_META_CORRUPT' });
});
it('列定义不是对象（数组）→ 报损坏', async () => {
await expect(openWithLegacySchema('{"t":{"id":["wrong"]}}'))
.rejects.toMatchObject({ code: 'ARIA_LEGACY_META_CORRUPT' });
});
it('形状正确 → 正常导入（正控：校验不能把好数据也拒了）', async () => {
const dbName = uniqueDB('review-schema-ok');
const backend = new MemoryBackend();
await backend.open(dbName);
const good = JSON.stringify({ t: { id: { type: 'string', primaryKey: true }, v: { type: 'number' } } });
await backend.write('__aria_schemas', new TextEncoder().encode(good).buffer as ArrayBuffer);
const engine = openEngine(dbName, backend);
await engine.open(dbName, 1);
await engine.insert('t', [{ id: 'a', v: 1 }]);
expect(await engine.count('t')).toBe(1);
});
});
describe('[review] manifest 世代在加载过程中消失', () => {
it('listKeys 之后文件消失 → 该世代记入 skipped，回退到上一代', async () => {
const backend = new MemoryBackend();
await backend.open('gen-vanish');
const store = new ManifestStore({ backend, instanceId: 'x' });
await store.load();
store.current.schemas = { old: { id: { type: 'string', primaryKey: true } } as never };
await store.commit(); // gen 1（旧内容）
store.current.schemas = { fresh: { id: { type: 'string', primaryKey: true } } as never };
await store.commit(); // gen 2（新内容）
// 让"最新的那一代"在 listKeys 之后读不到（外部删除/介质竞态）
const vanished = manifestKey(2);
const flaky = Object.create(backend) as MemoryBackend;
const realRead = backend.read.bind(backend);
let hide = false;
flaky.read = (async (key: string) => (hide && key === vanished ? null : realRead(key))) as never;
hide = true;
const loaded = await new ManifestStore({ backend: flaky }).load();
expect(loaded.generation).toBe(1); // 回退到上一代
expect(loaded.hadInvalidGenerations).toBe(true);
expect(loaded.skipped.some((s) => s.reason.includes('disappeared'))).toBe(true);
expect(Object.keys(loaded.manifest!.schemas)).toEqual(['old']);
});
});
describe('[review] bloomFilterBitsPerKey 必须真的生效（配置项不许被忽略）', () => {
/** 从 SSTable 文件尾部解析 bloom 段大小（footer: [indexOff,indexSize,bloomOff,bloomSize,hashes,count,?,magic]） */
function bloomSection(data: Uint8Array): { size: number; hashes: number } {
const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
const footerOffset = data.byteLength - 32;
return {
size: view.getUint32(footerOffset + 12, false),
hashes: view.getUint32(footerOffset + 16, false),
};
}
it('构建器按参数生成 bloom（位数越多段越大，且都不产生 false negative）', () => {
const { SSTableBuilder } = require('../src/engine/aria/index/sstable_builder');
const build = (bits: number): { data: Uint8Array; keys: string[] } => {
const builder = new SSTableBuilder(4096, bits);
const keys: string[] = [];
for (let i = 0; i < 200; i++) {
const k = `k${String(i).padStart(4, '0')}`;
keys.push(k);
builder.add(k, { v: i });
}
return { data: builder.build().sstableData, keys };
};
const lean = build(4);
const fat = build(40);
expect(bloomSection(fat.data).size).toBeGreaterThan(bloomSection(lean.data).size * 3);
expect(bloomSection(fat.data).hashes).toBeGreaterThan(bloomSection(lean.data).hashes);
// 正确性不变量：配置再怎么变，bloom 都不能产生 false negative（否则点查会漏数据）
for (const { data, keys } of [lean, fat]) {
const meta = {
id: 1, level: 0, minKey: keys[0], maxKey: keys[keys.length - 1],
blockCount: 1, totalSize: data.byteLength, bloomData: null,
} as never;
const reader = new SSTableReader(data, meta);
for (const k of keys) expect(reader.get(k)).not.toBeNull();
expect(reader.get('k9999')).toBeNull();
}
});
it('引擎配置透传：bloomFilterBitsPerKey 改变落盘 SSTable 的 bloom 段', async () => {
const sizes: number[] = [];
for (const bits of [4, 40]) {
const dbName = uniqueDB(`review-bloom-${bits}`);
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { bloomFilterBitsPerKey: bits, memtableSizeThreshold: 4096 });
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
await engine.insert('t', rows(200));
await (engine as any).lsm.flush();
const key = (await backend.listKeys()).find((k) => k.startsWith('sst_'));
expect(key).toBeDefined();
sizes.push(bloomSection(new Uint8Array((await backend.read(key!))!)).size);
// 配置生效的同时数据必须完整可读
expect(await engine.count('t')).toBe(200);
}
expect(sizes[1]).toBeGreaterThan(sizes[0] * 3);
});
});
describe('[review] 引擎层 WAL 空洞上报', () => {
it('活分片被删 → 打开时 walGaps + dataLossSuspected（不静默）', async () => {
const dbName = uniqueDB('review-engine-gap');
const backend = new MemoryBackend();
const engine = openEngine(dbName, backend, { walSyncMode: 'full' } as never);
await engine.open(dbName, 1);
await engine.createTable(SCHEMA());
for (let i = 0; i < 40; i++) await engine.insert('t', [{ id: `k${i}`, v: i }]);
// 不落盘：记录只在 WAL 里；手动制造"内部空洞"需要 ≥2 个分片 → 用小分片不行
//（引擎的 segment size 固定 4MB），因此这里直接删掉分片 0 并保留分片 1 的场景
// 由下面的单测覆盖；本用例验证的是"引擎把 WAL 层诊断搬进恢复报告"的接线。
const walKeys = (await backend.listKeys()).filter((k) => /^__wal_\d{6,}\.bin$/.test(k));
expect(walKeys.length).toBeGreaterThan(0);
const engine2 = openEngine(dbName, backend);
await engine2.open(dbName, 1);
expect(engine2.getRecoveryReport().dataLossSuspected).toBe(false); // 无空洞 → 干净
expect(await engine2.count('t')).toBe(40);
});
});