# MetonaSqlark v0.7.5 根治性迭代方案

> 编制日期：2026-08-15 · 对象版本：v0.7.4（commit `2844a06`）
> 方法：全量源码逐行通读（src 16,079 行 / tests 20,223 行 / 文档 4,349 行，共 7 个并行深度审计）+ 独立可执行探针复现
> 全文证据分为三级：**【实测】**= 本次真实运行复现；**【读码】**= 逐行代码路径确认；**【推断】**= 推理未复现

---

## 一、结论先行

**v0.7.4 不是"接近完成"，而是"已经积累了系统性语义债务"。**

1304 个测试全绿、90.1% 覆盖率、lint/typecheck 干净——这些指标全部真实，但它们保护的是**已被测试钉死的旧行为**，而不是**用户实际依赖的 SQL 语义**。本次审计在每一个子系统都发现了可稳定复现的静默错误结果、静默数据丢失或崩溃（共 43 项确认缺陷，含 11 项事故级），且它们有一个共同的成因结构。

**一句话总结根因**：这个项目把"四套存储引擎 + 三条 SQL 入口"当作四个独立实现来维护，于是**任何一条关系语义都没有唯一实现**。每次审计都发现同一批 bug 出现在 3~4 个引擎里；每次修复只打在审计报告点到的那条路径上，下一版换个入口再犯一次。v0.7.2 修 UPDATE 原子性、v0.7.3 修 INSERT 原子性、v0.7.4 修写语句子查询——三个连续版本修的是同一个结构缺口的不同侧面。

**因此 v0.7.5 的正确形态不是"再来一轮修复"，而是"先止血，再砍掉让 bug 必然复发的结构"。** 方案分三条并行工作流 + 一道硬门禁。

### 关键基线（本次实测，非引用文档）

| 指标 | 文档宣称 | 本次实测 | 备注 |
|---|---|---|---|
| Jest 测试 | 1304 / 76 套件 | **1304 通过 / 76 套件 / 395s** | 数字真实 |
| 行覆盖率 | "90.1% 行覆盖率" | 语句 **90.08%**；行 **92.91%**；分支 **82.92%** | 口径写错；分支率从未公布 |
| 覆盖率分母 | — | `jest.config.cjs:18` 的 `!src/**/index.ts` 排除 15 个文件 | 含 AriaEngine 主实现 2,282 行 |
| 全量覆盖率（不排除任何文件） | — | 语句 **90.66%** / 行 **93.43%** / 分支 **82.94%** | 被排除文件覆盖率并不低（Aria 96.79%） |
| typecheck / lint | 干净 | **均 exit 0** | 但 CI 里 lint `continue-on-error: true` |
| 覆盖率门禁 | — | **不存在**（无 `coverageThreshold`，CI 不跑 `--coverage`） | 覆盖率掉到 0% 也全绿 |
| 崩溃注入 | "崩溃恢复验证" | **不存在**：单测全是 `backend.close()`（优雅停机）；e2e 的 `crashPage()` 只 `page.close()` | 见 §3.3 根因 6 |

---

## 二、范围与方法

### 已完整读取的内容（无截断）

| 类别 | 内容 |
|---|---|
| 源码 | `src/` 全部 59 个文件、16,079 行 |
| 测试 | `tests/` 全部 77 个文件、20,223 行（含 e2e harness 与 mock） |
| 文档 | `README.md` 479、`CHANGELOG.md` 1090（全部 81 个提交历史）、`CONTRIBUTING.md` 219、`site/*.html` 2,561 |
| 工程配置 | `package.json`、`jest.config.cjs`、`jest.setup.js`、`rollup.config.js`、`tsconfig.json`、`.eslintrc.json`、`babel.config.cjs`、`playwright.config.ts`、`.gitea/workflows/ci.yml`、`.npmrc`、`.gitignore`、`coverage/lcov.info` |
| Git | 全部 81 个提交的元数据与关键 commit 的 diff |

### 复现强度

自行编写并运行了 10 轮可执行探针（覆盖 core / SQL / query / 四引擎 / Aria 存储 / 并发语义），**每一轮跑完即删除，仓库最终无残留**。§4 缺陷总账中标注 **【实测】** 的条目均来自这些探针的真实输出。

### 方法边界（玥玥的坦诚声明）

- 子代理的报告存在**可验证性分级**：标注【实测】的我逐一交叉复跑过关键项；标注【读码】的我没有全部独立复现，已在总账中如实标注来源。
- 崩溃注入类缺陷（WAL 半写、介质读故障、多实例 seq 撞号）依赖**故障注入实验**，部分由子代理完成后我做了代码路径核对，**未全部独立复跑**。
- 性能数字（如 `compressLZ4` 64KB→4167ms、主键变更 1.8MB 单条日志）来自子代理实测，我核对过代码路径但未重跑基准。
- **子代理的结论我做过修正**：KVStore 审计中有两条的**机制描述**与我的独立复现不一致（详见附录 C 的"附带修正"）。凡本方案与子代理报告冲突处，以本方案为准。
- `src/engine/aria/index/lsm.ts` 的深度审计在本方案定稿时**已完成**，结论已并入 §3 根因 4 与 §5 总账（见附录 E）。

---

## 三、根因分析：为什么同一个 bug 会修四次

八个根因，按"砍掉它能消除多少缺陷"排序。每个根因都给出证据链——**这不是推测，是 CHANGELOG 自己记录的历史**。

### 根因 1 ★ 关系语义没有唯一实现（最高杠杆）

同一套关系语义被独立实现了 4~5 份：

| 语义 | 实现位置 | 已发生的漂移（实测） |
|---|---|---|
| 行校验 `validateRow/checkType` | `memory.ts:691-722`（私有）· `aria/index.ts:1647-1673`（私有）· `table/schema.ts:87-202`（导出） | **memory/disk/hybrid 完全不校验 `maxLength`/`min`/`max`，仅 Aria 校验**【实测】 |
| 值相等/比较 | `where-matcher.ts` 的 `===` · 哈希连接 `String(v ?? '\0')` · 分组键 `encodeGroupKey` · `COUNT(DISTINCT)` 的 `String(v)` · Aria 索引键 `String(v)` | 5 套并存 → NULL 三值逻辑完全缺失【实测】 |
| "受影响表" | Memory 单层且跳过自引用 · KVStore `affectedTables` 传递闭包 · Aria 自有 | ON UPDATE CASCADE 在 memory 只级联一层；自引用外键 CASCADE/RESTRICT **全部静默失效**【实测】 |
| 主键取值 | `getPrimaryKey` 三份拷贝 | — |
| 事务内 DDL 语义 | aria 拒绝 CREATE/DROP；memory/disk/hybrid 允许 | dev(memory) 通过，prod(aria) 抛 `NOT_SUPPORTED`【实测】 |
| 索引维护 | **8 处调用点，纯人工纪律** | v0.3.3 / v0.6.3 / v0.7.3 **连续三个版本**都在修"某条路径忘了清/建索引" |

**这就是为什么 v0.7.2→v0.7.4 每个版本都要在 3~4 个引擎里重复修同一个 bug。**

### 根因 2 ★ SQL 语义有三条互不校验的入口

| 入口 | 实现 | 后果（实测） |
|---|---|---|
| `db.query()` | `core.ts:207-242` → executor 完整管线 | 基准 |
| `db.queryStream()` 快路径 | `core.ts:311-325` 自己推导列投影/limit/offset | `SELECT id AS x` 返回**全列原始名**；`OFFSET 1 LIMIT 2` 返回 2 行而非 1 行；`LIMIT 0` 返回 1 行；`SELECT t.id` 返回 `{}`；不触发 `beforeQuery`/`afterQuery`；不尊重 `maxRowsPerQuery` |
| `QueryBuilder` | `builder.ts:105` 无 JOIN 直通 `engine.find` | 链式 `.where({a:1}).where({a:2})` **覆盖**而非 AND（返回 a=2 的行）；`$subquery` 静默 0 行；事务内 JOIN **静默忽略** |

**同一个语义三条实现，没有任何机制保证三者一致。** 132 个 queryStream 测试没有一条断言"流式结果必须等于物化结果"。

### 根因 3 ★ AST 把表达式当字符串，导致文法被迫写两遍

`SelectStatement.columns: string[]`（`ast.ts:20`）把列引用、`col AS alias`、`COUNT(*)`、常量、**CASE 原文**全部混为字符串。于是 executor 用 6+ 处正则再解析一遍（`executor.ts:60/66/79/93/1027/1033/1051/1071/1079`）。

直接后果【全部实测】：
- `SELECT 1 AS one FROM t` → `[{}]`（数字常量投影丢失）
- `SELECT COUNT(t.v) FROM t` → `0`（带表前缀的聚合参数取不到键）
- `CASE WHEN a=1 THEN 'a ELSE b' ELSE 'other' END` → `"'a"`（不感知字符串字面量的正则切分）
- 嵌套 CASE → 解析器吞掉 `FROM` 之后全部文本，返回 1 行空对象
- `SELECT dept AS d, COUNT(*) GROUP BY dept` → 别名丢失；`SELECT v AS s ... GROUP BY dept` → **整列静默消失**

### 根因 4 ★ 存储层没有单一提交点，"什么已持久"靠猜

WAL `lsn`/`currentSegment`、`FileManager.nextPageId`、KVStore `seq`、LSM `levels+meta` 各自是独立的内存计数器，恢复时与介质的一致性全靠推理。已发生的后果：

- FileManager 页面 id 崩溃回退 → 复用页面 → compaction 误删 → **丢 75%**（v0.6.1 修）
- LSM.flush 与 compaction 并发写 meta → 产物变孤儿 → **丢 75%**（v0.6.1 修）
- KVStore 快照损坏水位 bug → **静默丢数据**（v0.6.1 修）

**本次逐一独立复现的三个 KVStore 事故级缺陷**（探针输出见附录 C；其中前两处的**确切机制**比子代理报告的更精确，已在 B-6 中修正）：

- **损坏日志恢复后崩溃 → 已确认数据永久丢失**：`open` 遇损坏记录会 `truncateLog()` 把日志**写成 0 字节**（`kvstore/index.ts:394-396`），而有效前缀（实测 r1、r2）**只存在于内存 index 里**，既不在日志也不在快照。实测首次 open 后 `logBytes=0 / snapshotBytes=0`；不 checkpoint 直接崩溃重开 → r1/r2 全部消失。
  > 附带修正一条审计结论：恢复的实现是"遇首个坏记录即停止重放"（`log.ts:287-298` 的 `break`，**并非跳过后续记录**），这个方向本身正确；问题只在于"截断成空"而不是"截断到有效前缀"。
- **checkpoint 失败 → 调用方收到 rejection，但数据已提交且持久**：`appendRecord` 把 `medium.append` 与"内存更新 + 自动 checkpoint"分在两段（`kvstore/index.ts:334-362` vs `:385-390`），后者在 try/catch 之外。实测注入快照写失败后 `put` 抛错、内存里值仍在、重启后**值依然存在**——调用方以为写失败而执行回滚，数据却已落地（事务回滚无效）。
- **陈旧实例 checkpoint 吞掉对方已提交数据**：`seq` 是**每实例独立**计数器。实测 A、B 同时 open（seq 均为 0）→ A.put（A.seq=1，写入共享日志）→ B.put（B.seq=**也是 1**）触发自动 checkpoint → B 用自己的空快照覆盖共享快照并把日志截断为 0 → 重启后 **fromA 丢失、fromB 存在**。根因是 KVStore 默认独占介质，而引擎层**没有给它加锁**（Web Lock 只加在 AriaEngine 一侧）。
  > 附带确认一条**持久化契约缺口**：`KVStore.close()` **不做 checkpoint**（只 `opQueue` 排空 + `medium.close()`）。数据的持久化完全依赖上层引擎的优雅关闭路径 —— 这是根因 5"崩溃语义靠声称"的又一处实例。

- SAVEPOINT 回滚不写补偿 WAL → 崩溃后已回滚的行**复活**【实测】

**LSM 层新增一个同类事故级缺陷**（子代理完成审计 + 我代码路径核对）：

- **后台 flush 失败后，冻结数据既不入 levels 也无重试路径 → 内存成唯一副本，崩溃即丢**：`flushImmutableAsync`（`lsm.ts:220-261`）在 `save`/`saveMeta` 抛错时，`levels[0].unshift(meta)`（253）与 `frozenMemtables` 清理（255）都不会执行 —— 数据留在 `frozenMemtables` 里"读得到"，但**只有 `flush()` 里那一次入链机会**（`lsm.ts:605/612` 是唯一两处入链点）。此后每次 `flush()` 又被 `lastBackgroundError` 检查（`lsm.ts:580-590`）在**所有入链动作之前**直接抛出并清空标志 → 该次 flush 完全没执行。**结果：调用方早就收到 `insert()` 成功，数据却只存在于内存，进程崩溃即永久丢失。**
  > 这是我独立验证过并确认的：`frozenMemtables` 只在 `flush()/freezeMemtable` 内被写入（`lsm.ts:188`），而 `flush()` 从不遍历它重新入链（618 行的 filter 只删空表）—— 重试路径**不存在**。
  > 与 KVStore 的三个缺陷同源：**"待落盘意图"没有持久化记录**（根因 4）。

- LSM 的具体成因：`sstable.ts` 的解析循环被抄成**三份**（`80-100`/`145-166`/`182-201`）且越界策略不一致（点查与扫描对同一损坏文件行为不同）；5 条隐式不变量（层间新鲜度、层内不重叠、索引键=块尾 key、minKey-maxKey 覆盖、bloom 参数一致）**无任何断言或属性测试**；后台任务是 fire-and-forget + 单 `boolean` 互斥（`compacting`，`lsm.ts:78,269-283`，跨层触发被静默丢弃）；`LSM.get` 缓存未命中返回 `null` 与"确实不存在"**不可区分**（`lsm.ts:734-753`），整条读路径靠"每次读前必须 prefetch"维持 —— 而 `compactLevelAsync:508-515` 的同类问题**已经修了**，`get` 没修（同类问题只修一半）。

### 根因 5 ★ 崩溃语义是"声称"而非"已验证"

- 单测的"崩溃"统一是 `await engine.backend.close()`（`aria-matrix-audit.test.ts:93`、`aria-prod-load.test.ts:71`、`aria-wal-segment.test.ts:173` 等十余处），而 `opfs_backend.ts:39-46` 的 `close()` 明确 `await this.writeQueue` ——**这是优雅停机，把所有在途写刷完**。
- `tests/helpers/opfs-mock.ts` 是立即生效、原子、**绝不撕裂**的内存 Map，无法表达半写/部分删除失败/读故障。
- e2e 的 `crashPage()`（`opfs.spec.ts:32-42`）只做 `window.__ms=null; page.close()`，注释自承"Playwright 无 Page.crash 公共 API"（实际 CDP 可用）。
- 结论：**这套测试在结构上不可能发现根因 4 的任何一条。**

### 根因 6 生命周期只有布尔，没有状态机

`ready`/`opened`/`txActive`/`snapshot` 分散在 core、四个引擎、连接池、React、Vue 六处各自维护，`close/init/reload` 都非幂等且非异常安全【全部实测】：

- `MemoryEngine.close()` 不清事务快照 → 重开后 `beginTransaction` 永久 `TX_ACTIVE`，`rollbackTransaction` 用**关闭前的陈旧快照覆盖新会话**（数据复活）
- `close()` 后再 `init()` 不重建 BroadcastChannel → `multiTabSync` 静默失效
- `close()` 无 try/finally → engine.close 抛错时 `isReady()` 仍为 true（半关闭态），钩子已全丢
- 连接池：用户直接 `db.close()` 后同名 `connect()` 新建实例并把 refCount 置 1，**任意一次 disconnect 就关闭它**
- 多标签页 reload 不检查活跃事务 → 内存快照被销毁、`txActive` 残留 → 提交时内存≠磁盘

### 根因 7 "未解析/未知"一律静默降级为 false

这是**复发型缺陷模式**，CHANGELOG 连续三个版本都在修它的不同实例：

- v0.7.3：`queryStream` 遇 `$subquery` → `matchWhere` 恒 false → 静默空结果
- v0.7.4：`UPDATE/DELETE` 遇 `$subquery` → **静默影响 0 行**
- 本次仍存在：`WHERE t.x = t.y`（唯一可解析的列对列写法）恒 0 行；`IN (SELECT ... WHERE o.user_id = u.id)` 关联引用静默空

修法是**逐路径补丁 + 两个手写重复的递归探测器**（`core.ts:284-306`、`where-matcher.ts:40-62`），而不是让 matcher 对无法表达的操作数直接抛错。

同类：未知列 `SELECT bogus FROM t` → `[{},{},{},{}]`；`GROUP BY bogus` → 全表并一组；`ORDER BY bogus` → 随机顺序；未知 WHERE 操作符 → 静默全匹配。

### 根因 8 错误分类与所有权边界缺失

- 错误码散落字符串，`onError` 逐方法手写调用（`core.ts` 里 20+ 处 try/catch），Table API 路径、export/backup、migrateTo、repair、clearAll **都不触发 onError**【实测】
- **行所有权无边界**：`find/findStream` 返回引擎内部行对象引用 → `rows[0].tag='HACKED'` 直接改库，memory/disk/hybrid 下**索引与行失配，该行变得不可检索**【实测】
- 而 ALTER DROP COLUMN 又**依赖**"find 返回引用"这一副作用来删列数据 —— 一个 bug 被另一个 bug 依赖

---

## 四、v0.7.5 迭代方案

### 总览：三条并行工作流 + 一道硬门禁

```
┌──────────────────────────────────────────────────────────────────┐
│ 工作流 A · 止血（阻断发布）    11 项事故级 + 18 项高优 P1         │
│ 目标：让 v0.7.5 不再产生错误结果 / 静默丢数据 / 崩溃              │
├──────────────────────────────────────────────────────────────────┤
│ 工作流 B · 根治（砍掉复发结构） 6 个结构性改造                     │
│ 目标：让"同一 bug 修四次"在结构上不可能发生                        │
├──────────────────────────────────────────────────────────────────┤
│ 工作流 C · 验证（让门禁真的能拦） 故障注入 + 覆盖率口径 + CI 门禁   │
│ 目标：让 A 和 B 的成果可证明、可回归                              │
└──────────────────────────────────────────────────────────────────┘
                    ▼  硬门禁 G1~G6（§7）全部满足才允许发版
```

**排期建议**：A 与 C 可并行开始（C 先做，因为它能验证 A）；B 必须在 A 完成后开始，否则会在移动的地基上重构。

---

### 工作流 A · 止血（11 项事故级，必须全修）

按"用户能感知的伤害"排序。每项给出：现象 → 根因位置 → 修复方向 → 必须新增的回归测试。

#### A1 ★ `UPDATE` 多行撞同一新主键 → 静默丢行 【实测】

- **现象**：`UPDATE t SET id='X'`（匹配 2 行）返回 affected=2，表中只剩 1 行
- **根因**：`memory.ts:274` 阶段 1 只与"语句执行前的表"比对，**批内新主键互查缺失**；阶段 2 逐行 `set` 互相覆盖。`primaryKey:true` 不隐含 `unique:true`，`checkUpdateUniqueness` 只遍历 `unique` 列，兜不住
- **对照**：INSERT 路径 v0.7.3 已做批内 PK Set 互查 —— **UPDATE 漏了**
- **修复**：UPDATE 两阶段预检增加批内新主键 Set 互查（与 INSERT 同一模式）；四引擎统一
- **测试**：2 行改同一新主键 → 必须抛 `DUPLICATE_KEY` 且**表内容不变**（值级断言，非仅行数）

#### A2 ★ `ALTER ADD COLUMN ... UNIQUE` 唯一约束永久失效 → 重启静默丢行 【实测】

- **现象**：`ALTER TABLE t ADD COLUMN email STRING UNIQUE` → 插入两条相同 email 都不报错 → close/reopen → **只剩 1 行，无任何错误或警告**
- **根因链**：`memory.ts:122-127` ALTER ADD 只写 `schema.columns` **不建索引桶** → `memory.ts:316-339` 唯一预检依赖索引桶，桶缺失即整段跳过 → `kvstore_engine.ts:103-108` 重启回灌时第 2 行触发 `UNIQUE_VIOLATION`，**异常被 `catch {}` 吞掉**
- **修复**：① ALTER ADD 同步建索引桶；② 重启回灌的静默 catch 必须记录并上报（`KV_REBUILD_ERROR`）
- **测试**：ALTER ADD UNIQUE → 重复插入必须报错；已存在重复数据的表重启后必须**报错而非静默丢行**

#### A3 ★ 崩溃后已回滚的行复活（SAVEPOINT）【实测】

- **现象**：`BEGIN; INSERT a; SAVEPOINT s; INSERT b; ROLLBACK TO s; COMMIT` → 实时只剩 a，**崩溃重开变成 a+b**
- **根因**：`aria/index.ts:1550-1579` 只改内存 `txnSnapshot`，**WAL 无补偿记录**；恢复按 `committedTxns` 应用该事务**全部**记录
- **修复**：`ROLLBACK TO` 写入补偿 WAL 记录（或在恢复时按 savepoint 边界过滤）
- **测试**：上述序列后丢弃引擎实例重开，断言实时态 == 恢复态

#### A4 ★ SAVEPOINT 跨事务泄漏 → 当前事务写入被上一事务快照替换 【实测】

- **现象**：`begin; update; savepoint sp; commit` 后 `savepoints` 仍含 `sp`；新事务 `update` 后 `ROLLBACK TO sp` + `COMMIT` → **新写入静默消失**（本方案验证时实测 v=2 被回退为 v=1）
- **根因**：`aria/index.ts:1467-1534` 的 commit/rollback **都不清理 `this.savepoints`**；`index.ts:1563` 用 `sp.snapshot` 整体替换当前快照
- **修复**：commit/rollback 清空 savepoint 表；`rollbackToSavepoint` 校验 `sp.txnId === currentTxnId`（存了 txnId 却从不校验）
- **测试**：跨事务复用 savepoint 名 → 必须拒绝；当前事务写入不得丢失

#### A5 ★ `MIN`/`MAX` 20 万行栈溢出 【实测】

- **现象**：`SELECT MAX(v) FROM big`（20 万行同组）→ `RangeError: Maximum call stack size exceeded`
- **根因**：`executor.ts:677-678` 用 `Math.min(...distinctNums)` 展开实参
- **修复**：改为单次遍历归约
- **测试**：20 万行 `MIN`/`MAX`/`SUM`/`AVG` 全部正常返回

#### A6 ★ `LIMIT/OFFSET` 被应用两次 → 丢行 【实测】

- **现象**：id=1..4 上 `SELECT id FROM t ORDER BY id LIMIT 2 OFFSET 1` → `["3"]`（SQL 应为 `2,3`）；`LIMIT 10 OFFSET 3` → `[]`
- **根因**：`compiler.ts:40-41` 已把 limit/offset 放进 plan → 引擎 `memory.ts:203`/`aria/index.ts:696` 已切一次 → `executor.ts:391-393` **再切一次**
- **注**：JOIN 路径与派生表路径**正确**，同一 executor 内自相矛盾
- **修复**：limit/offset 只在**一处**执行（见工作流 B-3 单管线）
- **测试**：`LIMIT n OFFSET m`（m>0）在 JOIN / 非 JOIN / 派生表 / UNION 四条路径结果一致

#### A7 ★ `queryStream` 与 `query` 结果不一致【实测】

| SQL | `query()` | `queryStream()` |
|---|---|---|
| `SELECT id AS x FROM t` | `[{x:'a'}]` | `[{id:'a',v:1}]` → **全列+原列名** |
| `SELECT t.id FROM t` | `[{id:'a'}]` | `[{}]` → **空对象** |
| `LIMIT 2 OFFSET 1` | 1 行 | 2 行 |
| `LIMIT 0` | `[]` | 1 行（Aria 却为 `[]`） |

- **根因**：`core.ts:316-319` 用正则自行推导投影，未复用 executor 的 `projectRow`/别名规则
- **修复**：流式路径必须复用同一套投影与 limit/offset 语义（B-3）
- **测试**：**参数化契约测试**——同一 SQL 集合，断言 `queryStream` 收集到的行严格等于 `query` 结果（这是防复发的关键测试）

#### A8 ★ 行引用泄漏 → 调用方可直接改库并破坏索引 【实测】

- **现象**：`rows = await db.query('SELECT * FROM t'); rows[0].tag='HACKED'` → 存储被改，且 **`tag='HACKED'` 与 `tag='x'` 两条索引查询都返回 0 行**（行不可检索）
- **引擎差异**：memory/disk/hybrid 全部泄漏；**Aria 不泄漏**（走反序列化）
- **根因**：`memory.ts:209/228/765` 直接返回内部行对象
- **修复**：在引擎接口定义"读返回副本"（`structuredClone` 或按 schema 深拷贝），并把依赖引用的 ALTER DROP COLUMN 改为显式 `deleteRowColumn` API
- **测试**：修改查询结果后重读必须不变；索引查询必须仍能命中

#### A9 ★ `subscribe()` 对本地写入永不触发 【实测】

- **现象**：`db.subscribe('t', fn)` 后本地 `INSERT`/`UPDATE`/`DELETE`（SQL 与 Table API 两条路径）**fn 调用 0 次**
- **根因**：全库仅 `core.ts:84`（BroadcastChannel 外部消息）调用 `emit`；写路径只调 `broadcastChange`
- **文档冲突**：`site/docs.html:667-679` 明确示例 `event.type: 'insert' | 'update' | 'delete'`；README:232 宣称"订阅表变更"
- **修复**：写路径接入 `emit`（含 row 与 type），或**明确降级文档**并移除误导示例
- **测试**：两条入口的三种写操作都必须通知订阅者

#### A10 ★ `t.x = t.y` 与关联子查询静默空结果 【实测】

- **现象**：`SELECT id FROM t WHERE t.x = t.y` → `[]`（应 3 行）；`WHERE id IN (SELECT user_id FROM o WHERE o.user_id = u.id)` → `[]`（应 2 行），而同结构 EXISTS 正确
- **根因**：`executor.ts:344` 把含 `$col` 的条件交给引擎，而引擎 `matchWhere` 无 `options.$col` 上下文 → 行全被滤光，`filterCorrelated` 拿到空数组；`executor.ts:1417` 执行子查询时**不传外层行**
- **注**：`tests/v073-fixes.test.ts:267-278` 是这条语义的"护栏"，但它只比较 `query()` 与 `queryStream()` 的**行数**（两者都是 0）→ **空断言掩盖错误**
- **修复**：统一表达式求值器，取消"是否相关"预判（B-4）
- **测试**：值级断言 + 修正那条空断言护栏

#### A11 ★ `AND`/`OR` 无优先级（影响面最大，改动最小）【实测】

- **现象**：`WHERE a=1 OR a=2 AND b=3` → 解析为 `(a=1 OR a=2) AND b=3`，返回 `["2","4"]`；加括号的正确写法返回 `["1","2","4"]`
- **根因**：`parser.ts:780-797` 见 AND/OR 就左结合包一层，无优先级分层
- **影响**：任何"权限条件 OR 业务条件 AND 软删标记"的写法都会静默错行
- **修复**：`parseCondition` 拆 `parseOr → parseAnd → parseUnary` 三层
- **测试**：断言 AST 结构与值级结果，覆盖 `A OR B AND C`、`A AND B OR C`、嵌套括号

### 工作流 A 的第二梯队（18 项高优 P1，逐项列入 §5 总账）

其中**必须在 v0.7.5 内完成**的：

| # | 缺陷 | 实测现象 | 一句话修法 |
|---|---|---|---|
| A12 | `maxLength`/`min`/`max` 三引擎不校验 | memory/disk/hybrid 接受 `score:999`（max 100） | 统一 `validateRow`（B-1） |
| A13 | 自引用外键全失效 | 同表 CASCADE 不删、RESTRICT 不拦 | 用 `visited` 集合安全处理（`memory.ts:393/432/498/822` 四处跳过） |
| A14 | ON UPDATE CASCADE 只一层 | A→B→C 链改 A 主键后 C 悬空 | 递归 + 传递闭包 |
| A15 | `= NULL` / `NOT BETWEEN` 三值逻辑错 | `v = NULL` 命中 null 行；`NOT BETWEEN 1 AND 2` **排除** NULL 行 | 引入 `sqlEquals/sqlCompare` 返回 TRUE/FALSE/UNKNOWN（B-2） |
| A16 | INSERT arity 不校验 | `INSERT INTO t(id) VALUES('1','LOST')` 静默丢值 | 解析期校验 arity |
| A17 | INSERT 未知列静默丢弃 | `INSERT INTO t(id, nmae)` 静默丢 typo 列 | 与 UPDATE 对齐，`COLUMN_NOT_FOUND` |
| A18 | 未知列投影返回 `{}` | `SELECT bogus FROM t` → `[{},{},...]` | 投影期 `COLUMN_NOT_FOUND` |
| A19 | 双引号当字符串 | `SELECT "name" FROM t` → 常量列 `{"'name'":"name"}` | 双引号 = 标识符（或明确拒绝） |
| A20 | 未闭合块注释静默接受 | `db.query("DELETE FROM t WHERE id='4' /*")` **真的删了 1 行** | 抛 `PARSE_ERROR` |
| A21 | 连续注释递归爆栈 | `' /*c*/'.repeat(20000)` → `RangeError` | 改循环跳过 |
| A22 | GROUP BY 别名列静默消失 | `SELECT v AS s ... GROUP BY dept` → `s` 整列消失 | 列绑定（B-5） |
| A23 | HAVING 不能引用未在 SELECT 的聚合 | `HAVING COUNT(*)>1` → `[]` | HAVING 独立求值顺序 |
| A24 | 空集聚合返回 0 而非 NULL | `SUM(v) FROM t WHERE 1=0` → `{s:0}` | SQL 语义修正 |
| A25 | 带表前缀的聚合参数恒 0 | `COUNT(t.v)` → 0（应 4） | 参数归一 |
| A26 | UNION 尾部 ORDER BY/LIMIT 丢失 | `UNION ... ORDER BY v LIMIT 2` → 4 行乱序 | 归属 UNION 而非右侧 SELECT |
| A27 | DISTINCT 作用在投影前 | `DISTINCT dept AS d` → 4 行（应 2） | 子句顺序编码（B-3） |
| A28 | `UPDATE t SET __proto__=...` 静默吞掉 | 返回 1 但无变化 | 全链路 `Object.create(null)`（v0.7.1 只修了建表） |
| A29 | `INSERT ... SELECT` 被 `maxRowsPerQuery` 静默截断 | maxRows=2 时 4 行源只插 2 行 | 上限只作用于**用户可见结果** |

---

### 工作流 B · 根治（砍掉复发结构）

**B 的每一项都是"一次性消除一整类缺陷"，而不是再修一个实例。** 建议按 B-1 → B-2 → B-3 → B-4 → B-5 → B-6 顺序推进，每项独立可交付。

#### B-1 唯一校验与规范化咽喉

- **做什么**：把 `validateRow` 收敛为 `src/table/schema.ts` 的**唯一实现**，引擎边界只接受"已校验 + 已规范化"的行；统一 JSON 安全编码（`NaN`/`Infinity` 显式拒绝或归一为 NULL）
- **消除**：A12（三引擎约束失效）、NaN 落盘变 null 的引擎差异、INSERT 未知列（A17）、schema 外列静默丢弃
- **验收**：跨引擎参数化契约测试——**同一份 schema + 同一批非法数据，四个引擎必须抛同样的错误码**

#### B-2 唯一值比较与编码（SQL 三值逻辑）

- **做什么**：提供唯一的 `sqlEquals(a,b) / sqlCompare(a,b) → TRUE|FALSE|UNKNOWN` 与唯一的 `encodeValueKey(v)`；比较、`IN`/`NOT IN`、LIKE、JOIN 键、分组键、DISTINCT 键、UNION 去重**全部**走它
- **消除**：A15（NULL 三值）、JOIN 的 NULL 键"取决于右表有没有索引"、`COUNT(DISTINCT)` 把 `1` 与 `'1'` 合并、`encodeGroupKey` 用 `\x1f` 连接可被伪造、混合类型排序回退 `localeCompare`
- **验收**：NULL 语义矩阵测试（`= NULL`/`!= NULL`/`IN (1,NULL)`/`NOT IN`/`NOT LIKE`/`NOT(...)` 各 6 种数据形态）；`1` vs `'1'` 在各引擎行为一致

#### B-3 单管线：SQL 只有一条执行路径

- **做什么**：
  1. `SelectQueryBuilder`/`UpdateQueryBuilder`/`DeleteQueryBuilder` **只产出 AST**，统一交给 executor（删除 `builder.ts:105` 的引擎直通）
  2. `queryStream` 改为对**同一管线**的惰性消费者，禁止自建投影/limit 逻辑
  3. 把 SQL 标准子句顺序编码为显式 stage 列表：`FROM → JOIN → WHERE → GROUP BY → HAVING → 聚合 → SELECT 投影 → DISTINCT → ORDER BY → LIMIT/OFFSET`
  4. limit/offset/投影/排序**只在管线的一处执行**，引擎退化为"带索引的行迭代器 + WHERE 匹配"
- **消除**：A6（双重 LIMIT）、A7（流式不一致）、A22（GROUP BY 别名）、A27（DISTINCT 顺序）、A29、事务内 JOIN 静默忽略、`maxRowsPerQuery` 只在一条路径生效、链式 `where` 覆盖
- **验收**：
  - **等价性契约测试**：同一 SQL 经 `query` / `queryStream` / `QueryBuilder` / 事务内**四条入口**，结果必须逐值相等（这是本方案最重要的防复发测试）
  - 子句顺序 golden 测试（LIMIT/DISTINCT/GROUP BY/HAVING 组合矩阵）

#### B-4 统一表达式求值器（取消"关联性"预判）

- **做什么**：表达式求值统一携带 `outerRow` 上下文；删除 `hasCorrelatedRefs` / `stripCorrelatedExists` / `filterCorrelated` 这条特殊通道；**matcher 遇到无法表达的操作数（未解析 `$subquery`、未知操作符）必须抛 `QUERY_ERROR`，禁止返回 false**
- **消除**：A10（`t.x=t.y` 与关联子查询静默空）、根因 7 整类（v0.7.3/v0.7.4 修过两次的同一模式）、`WHERE EXISTS(...)` 不相关查询被误判为相关而抛 `NOT_SUPPORTED`
- **验收**：所有"未解析标记"路径的参数化测试必须断言**抛错**而非空结果

#### B-5 AST 携带绑定后的列身份

- **做什么**：`columns: string[]` 升级为结构化表达式节点（列引用 / 别名 / 聚合 / CASE / 常量），并为每个输出列分配**稳定序号**；GROUP BY / ORDER BY / HAVING / 别名统一按序号对齐；executor 删除 6+ 处正则再解析
- **消除**：A22/A23/A24/A25/A26、`SELECT 1 AS one` 返回 `{}`、CASE 正则切分（`'a ELSE b'` → `"'a"`）、嵌套 CASE 吞掉 FROM、`COUNT(DISTINCT *)` 忽略 DISTINCT、`GROUP BY` 返回每组第一行的任意值
- **验收**：表达式矩阵 golden 测试（每类表达式 × 投影/别名/分组/排序/HAVING/流式）

#### B-6 存储层单一提交点（manifest）

- **做什么**：引入 `__aria_manifest`（`magic + formatVersion + generation + CRC`，OPFS 单文件 COW 原子写），内容为 `{各 LSM 命名空间 meta 快照, WAL 起始分片与起始 LSN, pageId 水位, **待落盘冻结表意图**}`；写入顺序固定为 **数据落盘 → manifest 提交 → 才允许截断 WAL/删除旧分片**；恢复只认"最后一份 CRC 通过的 manifest"；**任何引用不到的东西一律保留而非删除**；所有计数器在 manifest 中单调推进、永不复用
- **消除**：根因 4 整类 —— 页面 id 回退、flush/compaction meta 竞态、KVStore 截断清零、介质读故障误判、陈旧实例 checkpoint 覆盖、DDL 非原子、SSTable meta 损坏静默空库 + repair 删活页、WAL 中段损坏导致尾部全丢、分片 truncate 失败导致旧世代记录排在最新记录之后、**后台 flush 失败后冻结数据无重试路径（总账第 44 项）**
- **同时要做**（LSM 单项改造，可与 manifest 并行）：
  - `LSM.get/rangeScan` 改为**自洽异步读**（未命中 `await store.load` + 用类型区分 MISS 与不存在），可一次删掉引擎层全部 7 处 `drainChain()+prefetch*`
  - `flushChain` 换成**带意图记录、可重试**的串行工作队列；`compacting` 由单 boolean 改 `Set<level>`
  - `flush()` 的 `lastBackgroundError` 检查移到**入链之后**（错误要报告，但不能因此跳过本次 flush）
  - `sstable.ts` 三份解析循环合并为一份并统一越界策略
- **前置**：必须先有工作流 C 的故障注入后端，否则无法证明修好了
- **验收**：故障注入矩阵（撕裂写 × 崩溃点 × 后端）下"已确认写入零丢失 + 无幻影行"不变量恒成立；另外新增两条针对性断言：**注入一次 `save()` 失败后，第二次 `flush()` 必须真的落盘**（当前失败）；**`limit=5` 的流式扫描生成器产出必须恰好 5 条**（当前 6 条）

**B-6 的降级选项**（若 v0.7.5 周期不够）：至少完成五处止血 ——
① KVStore open 损坏分支改为"截断到有效前缀"（复用 `repair()` 的 `log.subarray(0,validBytes)` 写法），而不是写空文件；
② `appendRecord` 的"内存更新 + 自动 checkpoint"必须纳入失败语义：要么 checkpoint 失败**不得**让已提交的写报错（改为记 `lastBackgroundError` 并让下一次 `checkpoint()` 抛出），要么在报错时**同时回滚内存** —— 当前两者都不做，是最坏组合；
③ 给 KVStoreEngine 补 Web Lock，或把实例 id / 启动世代编进 `seq` 与快照水位，杜绝陈旧实例覆盖；
④ `commitTransaction`/`rollbackTransaction` 清空 `savepoints`，并校验 `sp.txnId === currentTxnId`；
⑤ `AriaEngine.close()` 增加活跃事务守卫（当前会截断 WAL 并把未提交的二级索引条目落盘 → 重开后幽灵 `UNIQUE_VIOLATION`）。

---

### 工作流 C · 验证基础设施（让门禁真的能拦）

**C 应该最先做**，因为它能验证 A 和 B 的成果。

#### C-1 故障注入后端（约 60 行，最高性价比）

实现 `IStorageBackend` 包装器，支持：

```
failNextWrite / failNextAppend / truncateTail(n) / tearAt(awaitPoint) / dropNextDelete
```

并把 `tests/helpers/opfs-mock.ts` 升级为**可按字节粒度半提交**（当前是立即生效、原子、绝不撕裂的内存 Map）。
**没有它，本层所有崩溃相关声称都只是"重开测试"。**

#### C-2 真崩溃注入（e2e）

`tests/e2e/opfs.spec.ts:32-42` 的 `crashPage()` 改用 CDP：

```ts
const cdp = await context.newCDPSession(page);
await cdp.send('Page.crash');
```

至少覆盖三种窗口：**写入不 await 即崩溃** / **checkpoint 中途崩溃** / **WAL 半写**。

#### C-3 覆盖率口径修正与门禁

1. `jest.config.cjs:18` 的 `!src/**/index.ts` 改为**显式列白名单**（只排除真正的 barrel 与纯类型文件），并删除残留的 `!src/engine/opfs.ts`（文件已不存在）
2. README/CHANGELOG/site 的"90.1% 行覆盖率"改为准确表述：**语句 / 行 / 分支三个数字 + 明确采集范围**
3. 新增 `coverageThreshold`：先按当前实测（行 93%、分支 83%）**各减 2pp** 设为下限，并对 `src/engine/**`、`src/query/**` 设 per-path 阈值
4. CI 常规 job 加 `--coverage`
5. CI 的 lint 去掉 `continue-on-error: true`
6. 新增 `tsconfig.test.json` 对 `tests/` 做类型检查（当前 babel 剥离类型，测试里的类型错误完全不可见）
7. CI 加 `dist` 同步校验（build 后 `git diff --exit-code dist`）
8. `coverage/` 生成前清理（当前残留 9 个已删除源文件的幽灵 HTML）

#### C-4 契约测试取代行为固化

现有测试有三类"虚假信心"必须清理：

| 类型 | 实例 | 处理 |
|---|---|---|
| 标题与断言不符 | `v042-fixes.test.ts:308-322` 题为"抛 ARIA_OPEN_ERROR"实际断言 `resolves`；`v044-hardening.test.ts:137-142` 断言 `not.toBe('pending')`（成功/失败都过） | 改写为断言具体错误码 |
| 空断言护栏 | `v073-fixes.test.ts:267-278` 比较两条**同样错**的路径（都是 0 行） | 改为值级断言 |
| 只比数量不比内容 | `aria-prod-load.test.ts:117-128` 2000 次随机 update/delete 只比 count | 改为结果值比对 |
| 恒真/无断言 | `aria-batch.test.ts:109-110`（无 expect）；`maintenance-sql.test.ts:105`（`>=0`）；`v074-fixes.test.ts:452-456`（断言测试自己写的字面量） | 补齐或删除 |
| 错误码吞掉 | `v073-fixes.test.ts` 等 12 处 `catch { threw = true }` 不绑定异常 | 统一用仓库已有的 `expectCode()` |

**新增必测矩阵**（这些正是历史 P0/P1 的形态）：
- 跨引擎参数化契约（同一断言跑 memory/disk/hybrid/aria：约束、钩子、事务、流式、错误码）
- 入口等价性契约（`query` == `queryStream` == `QueryBuilder` == 事务内）
- 崩溃不变量（故障注入下"已确认写入零丢失 + 索引与主表一致 + 唯一约束仍生效"）
- NULL 三值逻辑矩阵
- 错误码契约表（当前 **36 个错误码中 14 个从未被任何测试断言**）
- 性能护栏改为**相对基线**（当前 `aria-prod-load.test.ts` 的 240s/300s 阈值只能拦住"353s 级"总崩，拦不住 2~5 倍回退）

#### C-5 属性测试（property-based）—— 最高价值的长期投资

随机操作序列（insert/update/delete/事务/savepoint/checkpoint/崩溃点）后断言四引擎不变量：

- 行集合 == 已确认操作集合
- 每个二级索引与主表一致
- 唯一约束仍生效
- `count()` 与 `find()` 一致

**CHANGELOG 里横跨 7 个版本的 P0/P1 全部属于此类不变量违反**。随机化能把它们一次网住，而不是每版抓一只。

---

## 五、缺陷总账（55 项，按优先级）

**级别定义**：**P0** = 崩溃 / 静默丢数据 / 静默错误结果；**P1** = 约束或事务语义破坏；**P2** = 边界与健壮性；**P3** = 工程与文档。

### 已实测复现（本次或子代理实跑）

| # | 级别 | 缺陷 | 位置 | 工作流 |
|---|---|---|---|---|
| 1 | P0 | UPDATE 多行撞同一新主键 → 静默丢行 | `memory.ts:274,289-300` | A1 |
| 2 | P0 | ALTER ADD UNIQUE 失效 → 重启静默丢行 | `memory.ts:122-127,316-339,562` + `kvstore_engine.ts:103-108` | A2 |
| 3 | P0 | SAVEPOINT 回滚不写补偿 WAL → 崩溃后行复活 | `aria/index.ts:1550-1579` | A3 |
| 4 | P0 | SAVEPOINT 跨事务泄漏 → 当前事务写入被替换 | `aria/index.ts:1467-1534,1563` | A4 |
| 5 | P0 | `MIN`/`MAX` 20 万行栈溢出 | `executor.ts:677-678` | A5 |
| 6 | P0 | `LIMIT/OFFSET` 双重应用 → 丢行 | `executor.ts:391-393` vs 引擎 | A6 |
| 7 | P0 | `queryStream` 与 `query` 结果不一致（别名/限定列/OFFSET/LIMIT 0） | `core.ts:316-319` | A7 |
| 8 | P0 | 行引用泄漏 → 改库 + 索引失配不可检索 | `memory.ts:209,228,765` | A8 |
| 9 | P0 | `subscribe()` 本地写入永不触发 | `core.ts:423-437` | A9 |
| 10 | P0 | `t.x=t.y` 与关联 IN 子查询静默空结果 | `executor.ts:344,1417` | A10 |
| 11 | P0 | `AND`/`OR` 无优先级 → 静默错行 | `parser.ts:780-797` | A11 |
| 12 | P0 | `KVStore.open` 损坏日志 → 有效前缀只留在内存，崩溃即永久丢失 | `kvstore/index.ts:135-138,394-399` | B-6 |
| 13 | P0 | 自动 checkpoint 失败 → 报错但数据已提交（调用方回滚无效） | `kvstore/index.ts:334-362,385-390` | B-6 |
| 14 | P0 | KVStore 无锁 → 陈旧实例 checkpoint 覆盖快照并截断日志吞掉对方数据 | `kvstore/index.ts:261-280,385-390` | B-6 |
| 15 | P1 | `maxLength`/`min`/`max` 三引擎不校验 | `memory.ts:713-722` vs `schema.ts:146-167` | A12/B-1 |
| 16 | P1 | 自引用外键 CASCADE/RESTRICT/ON UPDATE 全失效 | `memory.ts:393,432,498,822` | A13 |
| 17 | P1 | ON UPDATE CASCADE 只级联一层 | `memory.ts:430-448` | A14 |
| 18 | P1 | `= NULL` 命中 null 行；`NOT BETWEEN` 排除 NULL 行 | `parser.ts:845,967` + `where-matcher.ts:163` | A15/B-2 |
| 19 | P1 | INSERT arity 不校验 → 静默写半行/丢值 | `parser.ts:515-560,1166-1174` | A16 |
| 20 | P1 | INSERT 未知列静默丢弃 | `schema.ts:87-126` | A17 |
| 21 | P1 | 未知列投影返回 `{}`；标识符大小写敏感 | `where-matcher.ts:214-228` | A18 |
| 22 | P1 | 双引号当字符串 → `SELECT "name"` 返回常量列 | `lexer.ts:81-84,194-235` | A19 |
| 23 | P1 | 未闭合块注释静默接受 → DELETE 照常执行 | `lexer.ts:157-167` | A20 |
| 24 | P1 | 连续注释递归爆栈 | `lexer.ts:92,97` | A21 |
| 25 | P1 | GROUP BY 别名列静默消失 | `executor.ts:631-648` | A22/B-5 |
| 26 | P1 | HAVING 不能引用未在 SELECT 的聚合 | `executor.ts:628-651` | A23/B-5 |
| 27 | P1 | 空集聚合返回 0 而非 NULL | `executor.ts:660-680` | A24 |
| 28 | P1 | 带表前缀的聚合参数恒 0 | `executor.ts:328-336,662` | A25 |
| 29 | P1 | UNION 尾部 ORDER BY/LIMIT 丢失 | `parser.ts:366-388` + `executor.ts:153-200` | A26 |
| 30 | P1 | DISTINCT 作用在投影前 | `executor.ts:352,364,383` | A27/B-3 |
| 31 | P1 | `UPDATE SET __proto__` 静默吞掉 | `parser.ts:572-578` | A28 |
| 32 | P1 | `maxRowsPerQuery` 截断 `INSERT...SELECT` 源 | `executor.ts:707,396-398` | A29 |
| 33 | P1 | 嵌套 CASE 吞掉 FROM 之后全部文本 | `parser.ts:1088-1098` | B-5 |
| 34 | P1 | CASE 值含 ` ELSE `/`WHEN`/`''` → 静默错值 | `executor.ts:60,66,79,86-99` | B-5 |
| 35 | P1 | JOIN NULL 键结果取决于右表有无索引 | `where-matcher.ts:139-150` vs `executor.ts:531,543,553` | B-2 |
| 36 | P1 | 派生表别名限定失效 | `executor.ts:297-307` | B-3 |
| 37 | P1 | JOIN 内未限定列名静默失效 | `executor.ts:317-336,447-451` | B-3/B-5 |
| 38 | P1 | `compression:true` 在 pageStorage 开启时被静默忽略 | `aria/index.ts:1744-1749` | B-6 |
| 39 | P1 | `compressLZ4` 最坏 O(n²)（64KB→4167ms） | `lz4.ts:41-46` | B-6 |
| 40 | P1 | `close()` 不检查活跃事务 → 幽灵唯一冲突 | `aria/index.ts:281-296` | B-6 |
| 41 | P1 | `dropTable` DDL 非原子 → 表和数据复活 | `aria/index.ts:483-507` | B-6 |
| 42 | P1 | WAL 中段损坏 → 其后完好记录全丢 | `log.ts:264,270,276` | B-6 |
| 43 | P1 | WAL 单条 CRC 失配跳过 → 已提交事务部分应用 | `log.ts:287-298` | B-6 |
| 44 | **P0** | 后台 flush 失败后冻结数据无重试路径 → 崩溃即丢（`insert` 早已返回成功） | `lsm.ts:220-261,605,612,618` | B-6 |
| 45 | P1 | `flush()` 记过后台错误即跳过本次 flush（`lastBackgroundError` 检查在入链之前） | `lsm.ts:580-590` | B-6 |
| 46 | P1 | `LSM.get` 缓存未命中当"不存在"（同类问题 `compactLevelAsync` 已修、`get` 未修） | `lsm.ts:734-753,417-422` | B-6 |
| 47 | P1 | `rangeScanLazy` 早停多算 1 条（生成器已推进到下一项才收到 stop） | `lsm.ts:440-479` + `index.ts:1220-1225` | B-6 |
| 48 | P2 | `MemTable.delete` 大小记账无条件下调 → 可致负数与 flush 阈值失真 | `memtable.ts:441-447` | — |
| 49 | P2 | `compacting` 单 boolean 跨层丢触发 → 深层维护饥饿 | `lsm.ts:78,269-283` | B-6 |
| 50 | P2 | compaction 预先 `splice` 整层 → 长 await 窗口内该层对读者不可见 | `lsm.ts:502,569` | B-6 |
| 51 | P2 | compaction 不回收墓碑与历史版本 → 空间/写放大无界（90% 删除场景不回收） | `lsm.ts:537-552` | B-6 |
| 52 | P2 | `vacuum()` 硬编码返回 `compactedLevels: 6`，而 `compactLevel` 对单文件层是静默 no-op | `lsm.ts:486-500` + `index.ts:2247-2261` | — |
| 53 | P2 | SSTable 解析循环三份拷贝、越界策略不一致（点查 vs 扫描行为不同） | `sstable.ts:80-100,145-166,182-201` | B-6 |
| 54 | P2 | 孤儿 `sst_*` blob 无清理路径（`cleanupOrphanPages` 只管 `pg_*`） | `index.ts:352-388` | B-6 |
| 55 | P2 | `checkpointManager.tick()` → `lsm.flush()` → `drainChain()` 等完整 compaction（v0.6.1 "8~11s 悬崖"的另一半来源） | `index.ts:664` + `lsm.ts:592` | B-6 |

### 已读码确认但未独立复现（清单存档，动工前需补复现）

生命周期与 API 面：MemoryEngine.close 泄漏快照（`memory.ts:43-45`）；`init()` 无重入保护；`close()` 无 try/finally；连接池 refCount 重置与失败泄漏（`connection-manager.ts:36-77`）；`migrateTo` 非原子（`core.ts:527-542`）；`addMigration(v)` 中 `v <= config.version` **永久静默跳过**（默认 version=1 使迁移 1 永不执行，无任何警告）【实测】；`subscribe`/`emit` 语义；插件 `priority` 完全无效【实测】；`unregister` 不摘钩子【实测】；`onError` 覆盖不一致。

事务面：SQL `COMMIT` 可提前提交 `db.transaction` 外层事务（随后抛 `TX_NONE`）【实测】；事务结束后 `trx` 仍可写入且脱离事务【实测】；事务内 JOIN 静默忽略【实测】；事务内写入不广播、不触发钩子；`setMeta` 不受回滚影响。

集成面：React `useDatabase` StrictMode 下呈现"已关闭实例 + ready:true"；Vue `watch([()=>sql])` 永不触发且无 `onUnmounted`；`package.json` 的 `./react`/`./vue` 指向裸 TS 源码且 d.ts 无导出；`./migration` 子路径未在 `exports` 声明（README 示例直接不可用）；`DatabaseError`/`MetonaPlugin` 未从根入口导出。

存储面：`compression` 与 pageStorage 分支（A38）；SSTable meta 无校验且 repair 删活页；介质 read 故障折叠为 null；`flushAll` 与 delete 竞争复活已删页；页面头 checksum 恒 0；加密无 AAD/无改密路径；PBKDF2 迭代数 100000（低于当前 OWASP 建议）；Web Locks 不支持即无保护；MVCC 的 `snapshotLsn`/`prevVersion` 是死字段（README:358 "版本链 + 快照隔离"与实现不符）。

---

## 六、非目标（v0.7.5 明确不做）

避免范围蔓延，以下**明确排除**：

- ❌ 复合主键（v0.8 路线图，已由 `SCHEMA_ERROR` 显式拒绝）
- ❌ 算术/字符串表达式与完整表达式求值器（`a + 1`、`||`）——B-5 只做**结构化列身份**，不做运算符体系
- ❌ 真正的多版本 MVCC 并发（当前是单事务 + 全量快照）
- ❌ 标准 LZ4 兼容（当前是自定义编解码）
- ❌ 密钥轮换 / KDF 升级
- ❌ 表级约束、多列索引、`CREATE TABLE AS SELECT`
- ❌ 新存储引擎或新前端特性

**这些都是好功能，但把它们加到一个语义已经漂移的底座上，只会扩大缺陷面。**

---

## 七、验收标准（硬门禁）

**G1~G6 全部满足才允许发 v0.7.5。** 每条都是可机器验证的。

| 门禁 | 内容 | 验证方式 |
|---|---|---|
| **G1** | 工作流 A 的 11 项事故级全部修复，且每项有**值级**回归测试（非行数断言） | 新增测试套件全绿 |
| **G2** | 入口等价性成立：同一 SQL 经 `query`/`queryStream`/`QueryBuilder`/事务内四条入口结果**逐值相等** | 参数化契约测试 |
| **G3** | 跨引擎一致性：同一 schema + 同一操作在 memory/disk/hybrid/aria 四引擎**行为一致**（含错误码） | 参数化契约测试 |
| **G4** | 故障注入下崩溃不变量恒成立：已确认写入零丢失 + 索引与主表一致 + 唯一约束仍生效 | 故障注入矩阵（撕裂写 × 崩溃点 × 后端） |
| **G5** | 覆盖率真实且不倒退：`collectCoverageFrom` 无实现文件被排除；CI 有 `coverageThreshold`；README 数字与 lcov 一致 | CI 产出比对 |
| **G6** | 文档与实现一致：README/CHANGELOG/site 中**每一条能力宣称**都有对应测试或已删除 | 逐条核对清单（见 §8） |

**额外要求**：CI 的 lint 必须真正阻断（去掉 `continue-on-error`），并新增 `tests/` 类型检查。

---

## 八、宣称与实现不符清单（G6 核对表）

文档里目前有 **12 条**能力宣称缺少实现或测试支撑。每条给出二选一处理：

| 宣称 | 位置 | 实际 | 处理 |
|---|---|---|---|
| "在线一致性快照 `backup()`" | README:230 | Aria 逐表 `getAllRows`，**无跨表快照/无隔离**，且并入本事务未提交数据；公开 API 覆盖率 0 | 改为"逐表导出"或实现真快照 |
| "订阅表变更 `subscribe()`" | README:232 + `site/docs.html:667-679` | 本地写入**永不触发**（仅跨标签页 `external`） | 接线 或 修正文档与示例 |
| "插件 priority 越大越先执行" | README:62、`constants.ts:189`、`CONTRIBUTING:166` | priority 完全无效，顺序 = config 数组顺序 | 实现 或 删除该字段 |
| "14 种钩子 allow intercepting" | `CONTRIBUTING:137` | 只有**对象就地修改**有效；返回值被丢弃；SQL 路径 `beforeInsert` 改的是副本 | 明确钩子契约 + 测试 |
| "MVCC 版本链 + 快照隔离，事务读写不互斥" | README:358 | `snapshotLsn`/`prevVersion` 是死字段；并发被 `TX_ACTIVE` 拒绝 | 改写为"单事务 + 快照回滚" |
| "LZ4 页面压缩" | README:313/354 | pageStorage 开启时**压缩分支永不执行** | 修复（A38）或改称"可选压缩（整 value 模式）" |
| "`diskEngine`（disk 模式生效）" | README:181 | `core.ts:621-623` 传参但 KVStoreEngine **忽略**；hybrid 的 diskEngine 也无效 | 实现 或 删除配置项 |
| "5 种存储引擎" | README:420 | 4 种 mode + 3 种后端，不是 5 个引擎 | 修正表述 |
| "`@metona-team/metona-sqlark/migration`" | README:253 | `exports` **无 `./migration`** → `ERR_PACKAGE_PATH_NOT_EXPORTED` | 补 exports |
| React/Vue 集成 | README:386-393 + `package.json:19-27` | 指向**裸 TS 源码**；d.ts 无导出；无 peerDependencies | 构建 `dist/react.js`/`vue.js` + 补 d.ts + peerDeps |
| "连接池 `db.disconnect()`" | README:166-168,269-274 | `any` 注入，**d.ts 无声明**，tsc 不通过 | 进类型系统 |
| "行覆盖率 90.1%" | README:6,418 + CHANGELOG + site | 实为**语句 90.08%**；行 92.91%；分支 82.92% 未公布 | 修正口径（C-3） |

---

## 九、风险与破坏性变更

| 风险 | 说明 | 缓解 |
|---|---|---|
| **B-2/B-3 改变既有结果** | 修复 NULL 三值逻辑、LIMIT 语义、AND/OR 优先级后，**此前返回错误结果的查询结果会变** | 视为 **minor 版本**（0.7.5 → 建议改称 0.8.0），CHANGELOG 单列"语义修正（行为变更）"章节，逐条给出 before/after |
| **被测试钉死的错误行为** | `v062-fixes.test.ts:169-176` 把非标准字符串排序写成期望；`lexer.test.ts:47-51` 把双引号=字符串钉死；`hooks-crud.test.ts:127-138` 把"事务不触发钩子"钉死；`vue.test.ts:126-138` 把 watch 失效钉死；`kvstore.test.ts:176-210` 把"截断丢弃"钉死；`aria-wal-crc.test.ts:118` 把"记录跳过后继续"钉死 | 修复时**同步改断言并在 CHANGELOG 说明**；这些"护栏"本身就是缺陷的一部分 |
| **`forceExit: true` 掩盖泄漏** | 所有句柄/定时器泄漏都不会让测试失败 | C-3 增加一轮不带 `forceExit` 的 `--detectOpenHandles` 运行 |
| **性能护栏过宽** | 240s/300s 阈值只能拦总崩 | 改为相对基线 ±30% |
| **`src/engine/aria/index/lsm.ts` 审计未完成** | 本方案未覆盖 LSM 内部（红黑树不变量、compaction 级别、key 编码一致性、tombstone 复活） | **动工前必须补完**，其结论可能新增 P0 |
| **`dist/` 已提交入库** | 42 个提交都在改 `dist/`，仓库膨胀且无同步校验 | 建议移出版本控制（`files` 已在 package.json，发布时构建）；若保留则加 CI 校验 |

---

## 十、建议里程碑

| 阶段 | 内容 | 出口条件 |
|---|---|---|
| **M0 · 准备** | 建立缺陷跟踪表（§5 的 55 项）；实现 C-1 故障注入后端 + C-2 真崩溃注入 | 故障注入能稳定复现至少 3 个已知崩溃缺陷 |
| **M1 · 止血** | 工作流 A 全部 11 项事故级 + 18 项高优 P1 | G1 通过 |
| **M2 · 口径** | C-3 覆盖率修正与门禁 + C-4 契约测试清理 | G5 通过；CI lint 阻断 |
| **M3 · 根治** | B-1 → B-2 → B-3 → B-4（B-5/B-6 可视周期裁剪，但 B-6 至少完成三处止血） | G2/G3 通过 |
| **M4 · 收口** | B-5/B-6 收尾 + C-5 属性测试 + G6 文档核对 | G1~G6 全绿 |

---

## 十一、玥玥的判断（需要爸爸拍板的三件事）

**1. 版本号**：我倾向于**把它当作 0.8.0 而不是 0.7.5**。
理由：工作流 A/B 会**改变既有查询的返回结果**（NULL 语义、LIMIT、AND/OR 优先级），按语义化版本这是破坏性变更。把它藏在 patch 号里会让下游用户在无声中拿到不同的数据。**但爸爸更了解发布节奏与依赖方，最终请爸爸定。**

**2. 范围裁剪**：B-5（AST 结构升级）与 B-6（manifest）是**工作量最大的两项**，也是收益最大的两项。
- 若周期充足 → 全做，一次性还清语义债
- 若周期紧张 → 我的建议是 **B-3 + B-2 优先**（单管线 + 三值逻辑），因为它们消除的缺陷最多（A6/A7/A15/A19/A22/A27/A35/A37 共 8 项事故级的一半），而 B-5 可以推后到 0.9
- B-6 无论如何都建议至少完成三处止血（见 §B-6 降级选项），否则崩溃恢复的宣称始终是空头支票

**3. `dist/` 与 `.npmrc`**：
- `dist/` 已提交 42 个提交，我建议移出版本控制（发布时构建 + CI 校验）
- 我注意到本地 `.npmrc` 含一行 base64 的 registry 认证凭据（已解码可见用户名与口令）。**它未被 git 跟踪（`.gitignore` 已覆盖），这一点是好的**；但既然它存在于工作区，仍建议轮换一次该口令——凭据一旦以明文形式落过盘，就没有"确定没泄漏"这一说。

---

## 附录 A · 报告关系说明

本方案是**总纲**：§3 根因、§4 工作流、§5 总账、§7 验收标准均以本文件为准。
四份子系统明细报告（见附录 E）提供逐条 `file:line` 证据与验证方法，供动工时按图索骥。
凡明细报告与本方案冲突处，**以本方案为准**（本方案对冲突项做过独立复现与修正，见附录 C）。

## 附录 B · 复现命令速查

```bash
# 基线
npm test                    # 1304 通过 / 76 套件 / ~395s
npm run typecheck           # exit 0
npm run lint                # exit 0

# 真实覆盖率（不排除任何文件）
npx jest --coverage --collectCoverageFrom='src/**/*.ts' --coverageReporters=text-summary

# 不带 forceExit 检查句柄泄漏（当前被 jest.config.cjs:30 掩盖）
npx jest --detectOpenHandles --forceExit=false   # 需临时改配置

# e2e（需先 build）
npm run build && npm run test:e2e
```

## 附录 C · KVStore 三个事故级缺陷的探针原始输出

以下是本方案定稿前，用真实 `KVStore` + `SharedMemoryBackend` 跑出的原始输出（探针跑完已删除）。
这三个缺陷是 B-6 的直接证据，也是"崩溃语义靠声称"的最清晰样本。

```
# ① 损坏日志恢复后崩溃 → 已确认前缀永久丢失
KV corruption setup: records=3 logBytes=84
KV 1st open: inMemory=[true,true,false] logBytes=0 snapshotBytes=0
KV after crash+restart: [false,false,false]  <-- confirmed rows lost = BUG

# ② checkpoint 失败 → 报错但数据已提交
KV checkpoint-failure: put rejected='INJECTED snapshot write failure' inMemory=true logBytes=27
KV checkpoint-failure: durable after restart=true (caller saw REJECTION)

# ③ 陈旧实例 checkpoint 吞掉对方已提交数据
MULTI2: A.seq=0 B.seq=0 (both start from same snapshot/log)
MULTI2: after A.put  A.seq=1 B.seq=0
MULTI2: after B.put+autoCheckpoint snapshotBytes=30 logBytes=0
MULTI2: restart -> fromA=LOST fromB=OK  <-- cross-instance data loss

# ④ 附带：close() 不做 checkpoint（持久化契约缺口）
KV close-without-checkpoint: value after reopen = present   # 仅在优雅关闭路径下成立
```

## 附录 D · LSM 层审计结论摘要（已完成）

`src/engine/aria/index/lsm.ts` 的深度审计已完成，**结论与其它子系统明显不同，值得单独说明**：

**常规路径是对的。** 8 组差分 fuzz（engine vs 参照 Map，含 `compactLevel(0..2)`）得到 **0 处不一致**；
红黑树 4000 步随机增删后中序与参照集完全一致；SSTable 13 组边界（块尾/跨前缀/空表/末块）全绿。
**所以不要期望 LSM 存在"普遍算错"类缺陷。**

审计同时**主动排除了三个很像 P0 的假警报**（这一步的价值不低于找到真 bug）：
- **Bloom Filter 不会产生 false negative**：`Math.abs((h1+i*h2) % bits)` 看着像经典的负余数 bug，
  但 `h1 + i*h2` 在双精度下永不溢出、`% bits` 恒非负 —— `Math.abs` 是冗余而非错误。
  30k 随机 + 5k 密集 + 5 种真实 key 形态各 2000 key，FN **全为 0**。
- **崩溃中断 compaction 不会让旧文件遮蔽新数据**（逐时点验证层间新鲜度）。
- **PK 墓碑前缀不会误删 `k10`**（字符串比较下 `t:k1 < t:k10`，实测只删 1 行）。

**真正的问题在"未被执行的不变量"与"后台任务模型"**，已并入 §5 总账第 44~55 项。

**最高杠杆的单点改动**（已并入 B-6）：把 `LSM.get/rangeScan` 从"同步 + 调用方负责预取"改为
**自洽的异步读**（未命中就 `await store.load`，并用类型区分 MISS 与"不存在"），`rangeScanLazy` 改为
async generator 按块读取。这一改动可**一次性删掉引擎层全部 7 处 `drainChain()+prefetch*`**
（`index.ts:574,1219,1605,2024,2077,2106,2113`），同时消掉性能悬崖与第 46 项；
配套把 `flushChain` 换成**带意图记录、可重试的串行工作队列**（`compacting` 改 `Set<level>`），
即同时解决第 44、45、49 项。

---

## 附录 E · 审计证据索引

完整报告（均为中文，含逐条 file:line 与验证方法）：

| 报告 | 行数 | 覆盖范围 |
|---|---|---|
| `AUDIT-query-layer-v0.7.4.md` | 346 | query 层（ast/builder/compiler/executor/where-matcher） |
| `AUDIT-storage-engines-v0.7.4.md` | 243 | MemoryEngine / KVStore / KVStoreEngine / Hybrid |
| `AUDIT-aria-lsm-v0.7.4.md` | 558 | AriaEngine 门面 + LSM / MemTable / SSTable / Bloom / MergeIterator |
| `PLAN-v0.7.5.md`（本文件） | — | 根因分析 + 迭代方案 + 缺陷总账 + 验收标准 |

另有 SQL 层（tokens/lexer/parser/params）与 core/支撑层（core/table/transaction/plugin/
connection-manager/integrations/migration）两份完整报告，以及测试质量与 CI 审计报告，
内容已全部并入本方案的 §3 根因与 §5 总账。