diff --git a/AUDIT-aria-lsm-v0.7.4.md b/AUDIT-aria-lsm-v0.7.4.md new file mode 100644 index 0000000..11cdf99 --- /dev/null +++ b/AUDIT-aria-lsm-v0.7.4.md @@ -0,0 +1,558 @@ +# AriaEngine LSM-Tree 索引子系统审计报告（v0.7.4） + +> 审计范围：`src/engine/aria/index.ts`（2282 行）、`index/lsm.ts`（801）、`index/memtable.ts`（511）、 +> `index/sstable.ts`（334）、`index/sstable_builder.ts`（253）、`index/merge_iterator.ts`（191）、 +> `index/bloom.ts`（113）、`types.ts`（249），以及 15 个 aria 测试套件与 CHANGELOG v0.7.2–0.7.4。 +> +> 标注约定：**【已读代码确认】**＝直接从代码推出；**【已实测确认】**＝我写了临时探针跑出可复现结果 +> （探针已删除，工作区无残留）；**【推测】**＝机制上成立但未复现，附验证方法。 + +--- + +## 1. 架构概览 + +### 1.1 MemTable：红黑树 + +- **结构**：`RBNode`（`memtable.ts:14-26`）+ `RedBlackTree`（`memtable.ts:32-411`）。私有 `root` / `_size`， + 颜色枚举 `Color{RED,BLACK}`，节点带 `parent` 指针，**无哨兵 NIL 节点**（nil 用 `null` 表示）。 +- **比较器**：全部用 JS 原生 `<` / `>` / `>=` 直接作用于 `string`（`memtable.ts:54,56,80,82,127,136,137`）。 + 即 **UTF-16 码元序**，与 `Array.prototype.sort` 默认序、`SSTable` 索引键序完全一致 —— + 这一点是全链路唯一真正统一的东西（builder 依赖"调用方已排序"，见 1.2）。 +- **插入** `insert(key,value)`（39-74）：迭代下降找位置；命中则**原地替换 value 并 return，不改结构、不加 size** + （58-62）。新节点默认 RED，挂到 parent 后 `fixInsert`（231-272）走标准三情形（叔红上溢 / LL / LR）。 + 根节点强制染黑（271）。 +- **查找** `find`（77-89）与 `findNode`（161-173）是同一算法写了两遍（重复代码）。 +- **删除** `delete(key)`（92-100）→ `deleteNode`（175-213）：零/单子节点走 `transplant`（215-224）； + 双子节点取中序后继、先摘后继再顶替（187-212）。后继颜色为黑时进入 `fixDelete`（274-357）， + 含四情形标准双黑修复（兄弟红 / 双侄黑 / 近侄红 / 远侄红），镜像分支在 319-353。 + CHANGELOG v0.7.4 修的就是这里：`x`（双黑起点）与 `xParent` 必须在 `transplant` 重连**之前**捕获 + （193-194, 209-210），否则 `null` 占位会以 `parent=null` 传入 → `fixDelete` 在 280 行 `break` 掉， + 黑色节点删除后整棵树黑高失衡。 +- **注意**：**`RedBlackTree.delete` 在生产路径上是死代码** —— `LSM.delete` 写墓碑（`lsm.ts:155-164`， + `{__tombstone:true}`）而不是树删除。只有单测 `aria-index.test.ts:104-112,142-149` 直接调用 `MemTable.delete`。 + 即：这棵树上最容易出错的那一半代码，生产环境从未被走到，而它仍带着一处**确定的大小记账缺陷**（见 2.2）。 +- **遍历**： + - `inorder`（104-106）/`getAllEntries`（147-151）：递归中序，物化数组。flush 走这条路径 + （`lsm.ts:221`）。 + - `rangeScan`（109-115）→ `_rangeScan`（400-410）：递归 + 剪枝。注意剪枝用**严格不等号**： + `node.key > start` 才递归左子树、`node.key < end` 才递归右子树（407、409）， + 等于边界的子树被跳过 —— 对本函数是安全的（等于边界的那个节点本身会在 408 行被回调）。 + - **`scanLazy`（121-144）**：v0.7.4 新增。显式栈中序迭代器；先沿路把"≥startKey 的最左祖先链"压栈 + （124-132），然后弹栈产出；`node.key > endKey` 直接 `break`（136）剪掉剩余子树。 + 这是 `findStream` 真流式的底层。 + +### 1.2 SSTable 格式与读写 + +**布局（v2，magic `SSTC`）**：`[Data Block 0..n][Index Block][Bloom Filter][Footer 32B]` +（`sstable_builder.ts:15-34`）。 + +- **Data Block**：`entryCount(u32)` + 重复 `[keyLen(u32)|key|valLen(u32)|val]`，key/value 均为 **UTF-8 字节**， + value 是 `JSON.stringify(row)` 的字节（builder 77-81、185-222）。 +- **Index Block**：`entryCount(u32)` + `[keyLen(u32)|key|blockOffset(u32)|blockSize(u32)]`； + **索引键 = 该块内最后一个 key**（94-103），这是 v0.6.1 那个 P0 漏读 bug 的根源约束。 +- **Footer 32B**：`index_offset|index_size|bloom_offset|bloom_size|bloom_hash_count|entry_count|magic|checksum` + （133-149）。 +- **分块策略**（167-182）：累加 UTF-8 字节，`>=blockSizeLimit` 且块内已有 >1 条时，把**除最后一条外**的全部 + 封块（174-177）。因此块大小 ≈ blockSize（默认 4096），单条超大 value 独占一块。 + 【已实测确认】用 90 字节行插入 10 万行（`aria-prod-load.test.ts:345` 的形态）时， + builder 的 4096 字节上限被**完全绕过**：单块最多可达 ~2×4096+header，索引条目数因此约减半 + （见 3.5，属性能/密度问题而非正确性问题）。 +- **CRC**：整文件 CRC-32 覆盖**除最后 4 字节（checksum 自身）外的全部字节**（146-149）， + 写 0 时改写成 1 以区分旧格式；读取端 `storedChecksum === 0` **直接放行不校验** + （`sstable.ts:41-46`）——这是 v1/早期 v2 文件的兼容豁口（对**新建**文件不生效）。 +- **读取**（`sstable.ts`）： + - `parseFooter`（209-251）：`byteLength < 32` 抛错；magic 决定 u16/u32 长度字段宽度； + 索引越界则**静默 return**（235-237，残缺文件退化为空表）；bloom 越界/解析失败也只是降级为无 bloom（243-250）。 + - `parseIndexBlock`（253-277）：逐个读，越界即 `break`；指向文件外的块条目被 `continue` 跳过（273）。 + - `get`（62-103）：bloom 先否定 → `locateBlock` 二分 → 块内**线性扫描**（79-100）。 + - `rangeScan`（106-115）只是 `scanLazy` 的包装；`scanLazy`（121-168）用 + `locateBlockGE(start)` 起、`min(last, locateBlockLE(end)+1)` 止（126-131）， + 多扫一块以规避"块尾 key 越界"漏读，条目级 `key>=start && key<=end` 过滤（158）。 + - `locateBlock`（294-313）/`locateBlockGE`（315-323）/`locateBlockLE`（325-333）：三套二分，第三个函数 + 在"endKey 小于全部索引键"时返回 **0 而非 -1**（332），靠调用方 `Math.max/clip` 兜住 —— 脆弱但当前正确 + （【已实测确认】13 组范围/边界探针全绿）。 + +### 1.3 MergeIterator 语义 + +- 数据源抽象 `EntrySource{next,reset}`（12-17）；`ArrayEntrySource`（20-36，compaction 用，全量物化） + 与 `GeneratorEntrySource`（43-58，v0.7.4，流式扫描用）。 +- 最小堆 `MinHeap`（71-122）仅按 `key` 比较（100、113-114），**sourceIndex 不参与堆序**。 +- `next()`（148-168）：弹出最小项后立刻从**同一 source** 补种（156），再把堆顶所有 `key === 当前 key` + 的重复项一次性抽干（159-165），其中 `sourceIndex` 最小者胜出（162-164）。因此： + - **去重只在"同一次 `next()` 调用内"发生**；语义是"同一 key 只吐一条，取最新源"。 + - 顺序保证依赖**源加入顺序 = 新鲜度降序**：`LSM.rangeScanLazy`（447-467）先 MemTable、再 + `frozenMemtables` 由新到旧、再 L0→L6，且每层内按 id 降序（`init` 128 行、flush `unshift` 253 行）。 +- **墓碑处理**：MergeIterator 自己**不认识**墓碑（它只是普通 value）。过滤在两处： + - 点查：`unwrapTombstone`（`lsm.ts:727-731`）→ `get` 命中墓碑返回 `null`； + - 扫描：`rangeScanLazy` 内 `if (!v.__tombstone) callback(...)`（472-476）。 + - **compaction 不丢墓碑**（`compactLevelAsync` 把 `drain()` 的全部条目写进新文件，537-552）， + 因此删除不会被旧数据"复活"，代价是墓碑与历史版本**永久留存**（见 3.4）。 +- 快照过滤：MergeIterator **无任何 MVCC 概念**；快照隔离完全在 `AriaEngine.find/getAllRows` 的 + `mergeTxnSnapshot`（index.ts:1620-1638）里做——即先取磁盘视图，再把 `txnSnapshot` 的写/删标记覆盖上去。 + +### 1.4 端到端读取路径 + +| 路径 | 链路 | +|---|---| +| **点查（PK 等值）** | `find`→`tryIndexLookup`(1993-2006) → `lsm.prefetchKeys([key])`（内含 `drainChain`）→ `lsm.get` → MemTable→frozen→L0..L6，命中 `unwrapTombstone` → `mergeTxnSnapshot` → `matchWhere` → `orderBy` → `slice` | +| **二级索引等值** | `tryIndexLookup`(2041-2053) → `indexScanToRows`(2099-2120)：`idxLsm.prefetchRange`→`idxLsm.rangeScan`→收集 pk→`lsm.prefetchKeys(pks)`→逐个 `lsm.get` | +| **二级索引范围** | `tryIndexLookup`(2085-2092)：**放弃下推**，`indexScanToRows(idxLsm,'','\uffff')` 全索引扫描 + 逐行 `lsm.get` + 行级 `matchWhere` | +| **全表** | `getAllRows`/`find`→`lsm.prefetchRange(prefix,prefix+\uffff)`→`lsm.rangeScan`（**物化数组**）→逐行重建 PK → `mergeTxnSnapshot` | +| **流式** | `findStream`(1172-1227)：非事务且无索引命中时 `lsm.prefetchRange` + `rangeScanLazy`，回调返回 `false` 提前终止；事务中回退 `find` 全量物化（1199-1206） | + +### 1.5 Compaction 与后台链 + +- **层级**：固定 7 层（`MAX_LSM_LEVELS`），**`levelSizeMultiplier` 字段被读取后从未使用** + （`lsm.ts:71,90`，全仓 grep 仅赋值无消费）—— 即**没有基于体积的层级容量策略**， + 只有"某层文件数 ≥4 就整层合并到下一层"（258、275-281）。 +- **触发**：`put/delete` 时 `levels[0].length >= 8` → `enqueueCompact(0)`（145-147、156-158）； + flush 完成时 `levels[0].length >= 4` → `scheduleCompact(0)`（258-260）； + 完成后在 `finally` 里级联检查本层与下一层（272-282）。`compactLevelAsync(level, minFiles=4)` + （498-577）：`splice` 整层 → 逐个"缓存优先、`store.load` 兜底" → `verifyChecksum` → `scanAll` 物化 → + `MergeIterator.drain()` → 建成新 SSTable → `save`+`saveMeta` → `levels[level+1].unshift` → + **无条件删除整层旧文件**（572-576）。 +- **后台链序列化**：所有 flush/compaction 挂在单条 Promise 链 `flushChain` 上 + （`enqueueOnChain` 194-204）。`drainChain`（211-217）循环 `await` 直到链引用不再变化 + （因为任务完成时可能级联追加新任务）。`prefetchRange/prefetchPrefixRanges` 开头都 `await drainChain()` + （315、334、372）—— 这是"读之前先把后台任务排空"的**唯一一致性手段**，也是 3.1 性能悬崖的直接来源。 +- **背压**：`compactLevelAsync` 无体积/耗时上限；`LSM.put` 只在 L0≥8 时排队一次 compaction， + 没有限流、没有拒绝写入、没有反压信号给调用方；`cacheLimitBytes` 默认 = `bufferPoolPages × pageSize` + = 256×4096 = 1MB（index.ts:168）。 + +### 1.6 MVCC 分层（实际形态） + +- `MVCCManager`（`transaction/mvcc.ts`）维护 `versionStore` / `activeTxns` / `globalCommitLsn` / + `txnWriteKeys`。`writeVersion` 建链（115-135）、`deleteVersion` 写 `__mvcc_tombstone`（140-142）。 +- **关键事实：AriaEngine 的事务隔离不靠 MVCC，靠 `txnSnapshot`（一个 `Map`）**： + - 事务内写只进快照 + `mvcc.writeVersion`（index.ts:637-644、820-830、1011-1017）； + - `find/getAllRows/count/update/delete` 都先拿磁盘视图再 `mergeTxnSnapshot` 覆盖（1620-1638）； + - `commitTransaction`（1467-1495）在 WAL COMMIT 落盘后，把**整个快照**逐键 `lsm.put/delete`； + - `commitTransaction` 里 `mvcc.commitTransaction` 会**删除本事务全部版本**（mvcc.ts:60-80）—— + v0.6.3 的注释明确写了"快照读取已移除，版本链仅作 undo 记录"。 +- 因此 **`mvcc.gc(maxVersionsPerKey)`（168-176）几乎无事可做**（链在每次提交时已被清空）， + `tryGC`（index.ts:2127-2133）每 10 次写操作调用它、`vacuum` 调 `gc(10)` 都只是空转； + `vacuum()` 返回的 `gcVersions` 实际是 `getGlobalLSN()`（提交序号）而非回收版本数（2258-2260）——**误导性指标**。 +- **二级索引不参与 MVCC/快照**：`updateSecondaryIndexes`（1926-1957）在事务内**立即**改写索引 LSM， + 回滚/savepoint 回滚后靠 `reindexTable` 全量重建（1529-1533、1573-1578）。这带来一个结构性副作用： + **事务内索引领先于主表**（见 2.6）。 + +### 1.7 Flush / Checkpoint 路径 + +``` +insert/update/delete + └─ wal.appendBatch（full=逐批落盘 / batch=缓冲 / none=不写） + └─ opCounter += n ; checkMemoryBudget()（maxMemoryMB 超限 → 不等待的 lsm.flush()） + └─ checkpointManager.tick() ← opCount>=interval 或 WAL 字节>=16MB + └─ CheckpointManager.checkpoint() + ├─ lsm.flush() ← 内含 drainChain()，会等**全部**后台 compaction + ├─ flushAll() ← 主 LSM + 全部二级索引 LSM 各自 flush() + └─ wal.checkpoint() ← 截断 WAL（活跃事务时 skip，index.ts:252-259） +``` +`LSM.flush()`（580-620）：先查 `lastBackgroundError` → `drainChain` → 把 `immutableMemtable` 入链 → +若活跃 memtable 非空则 `freezeMemtable()` 并把新的 immutable 入链 → 再 `drainChain` → 清理空 frozen。 +`freezeMemtable`（182-191）把当前 memtable 冻结、塞进 `frozenMemtables`、用 `memtableSizeThreshold` +新建一张（v0.4.2 修的就是"新表阈值衰减"）。 + +### 1.8 二级索引 LSM 与主 LSM 的关系 + +- 每个 `index/unique` 列一个独立 `LSM` 实例（index.ts:194-204 重启恢复、452-461 建表、 + 1353-1362 createIndex），**独立 SSTableStore 命名空间**（`createSSTableStore`，1719-1814： + 文件前缀 `sst_idx___`、meta key `__aria_lsm_meta_`、**独立 id 序列**）。 +- 索引条目格式：key = `${String(value)}:${pk}`，value = `{pk}`（1382、1953、2237）。 +- 查询：`tryIndexLookup`（1960-2096）递归展开 `$and`（1974-1984），PK 走主 LSM 精确/`$in`/范围， + 其他列走 `idxLsm`。失败则返回 `null` → 主表全扫兜底（`find` 680 行）。 +- **两个 LSM 之间没有任何事务/原子性耦合**：索引写成功了主表写失败（或反过来）只能靠 + `reindexTable`/`repair` 事后修（2209-2242、331-334）。 + +--- + +## 2. 缺陷清单 + +> 排序：P0 数据丢失/腐坏 → P1 错误结果 → P2 健壮性/性能 → P3 风格（已按要求忽略纯风格项）。 + +### P0-1　compaction 后 `get()` 在同一层内"先读到旧值"的顺序保证，依赖一个从未被断言的不变量 +- **文件:行号**：`src/engine/aria/index/lsm.ts:401-426`（get 的层级短路）、`498-577`（compaction）、 + `index.ts:625-627`（`__txn_deleted` 标记复用）。 +- **现象**：`get` 的语义是"遇到第一个匹配即 return，**命中墓碑直接返回 null**"（404、409）。 + 这要求"层号越小 ⇒ 数据越新"这条全局不变量**永远**成立。 +- **根因**：compaction 只做 `levels[L] → levels[L+1]`，且**不与 `levels[L+1]` 已有文件做 k 路归并** + （554-569 直接 `unshift` 新文件），于是层内出现**区间重叠文件**；层间新鲜度完全靠"所有写都从 L0 进" + 这一时序事实维持。任何绕过 L0 的写（重放、外部直接 `compactLevel`、未来加的 repair 路径）都会打破它。 +- **严重级别**：P1（错误结果）为当前实际等级；若被打破即 P0。 +- **复现思路**：【已实测/已证伪】我按 7 组时序（含 2 文件/层、跨层交替、崩溃窗口）构造探针， + 未复现出错误值 —— 因为当前所有路径都经 L0，不变量成立。**验证方法**：写一个测试直接 + `engine.lsm.levels[2].push(meta)` 注入一份"更新"数据（模拟重放/repair 写错层）， + 再 `get` 同 key，即可看到旧值胜出。**建议**：`get` 遇到墓碑不应立刻 `return null` 而是 + `continue` 到更低层（前提是层序=新鲜度），或改为"收集所有命中取最小层号"。 + +### P0-2　`MemTable.delete` 的大小记账无条件下调，与树删除结果脱钩（潜在重复 flush / 无限刷盘） +- **文件:行号**：`src/engine/aria/index/memtable.ts:441-447`（`delete`）、`497-510`（`estimateEntrySize`）、 + `lsm.ts:159-163`（生产路径改用墓碑，故当前只被测试与潜在调用方触发）。 +- **现象**：`delete` 先 `find` 取旧值并 `_estimatedSize -= size(oldVal)`，**然后**才 `tree.delete(key)`； + 当 key 不存在（`find` 返回 null）时 `estimateEntrySize` 返回 0，**减法照做**，`_estimatedSize` 被凭空扣减。 +- **根因**：`if (oldVal) { ... }` 只保护了"减多少"，没保护"是否该减"。返回值 `tree.delete` 的布尔结果 + 被丢弃（444-446）。 +- **严重级别**：P2（健壮性/性能；可放大为 P2 级写放大与 SSTable 膨胀）。 +- **复现思路**：【已实测确认】`new MemTable(1000); mt.delete('ghost')` 后 `getEstimatedSize()` 变为负数； + 随后每次 `put` 都在负基线上加，`shouldFlush()` 被推迟；反之在频繁删除不存在键的场景（例如 + 应用层"删了再删"）会让计数漂移。**验证方法**：单测断言 + `mt.delete('absent'); expect(mt.getEstimatedSize()).toBe(0)` —— 当前会失败。 + +### P1-1　`LSM.get` 缓存未命中返回 `null`（"不存在"），与"数据不可用"不可区分 +- **文件:行号**：`src/engine/aria/index/lsm.ts:734-753`（`loadSSTableReader` 未命中即 `return null`）、 + `417-422`（调用方 `if (!reader) continue;`）；对比 `compactLevelAsync` 已经修好的 + "从存储兜底加载"（508-515）。 +- **现象**：只要某个 SSTable 不在 `sstableCache` 里，该层就被**静默跳过**。读路径依赖"每次查询前 + `prefetchKeys/prefetchRange` 已把需要的文件装进缓存"这一约定（`prefetchRange` 314-328、 + `prefetchKeys` 331-352）。 +- **根因**：`cacheLimitBytes` 会驱逐（`trimCache` 792-799），而 `prefetch*` 只对"目标 key 命中区间"的文件 + 做 `toLoad`（320-322、341-344）；**单文件大于 `cacheLimitBytes` 时缓存会在下一次 `trimCache` 时被清空** + （793-798），此时"目标文件本身被更早装入的大文件挤出缓存"就变成可能。尽管每条读路径都紧跟一次 + prefetch 使其难以稳定触发，但代码本身没有"未命中就回源"的兜底，属于**同类问题只修了一半** + （compaction 修了、get 没修）。 +- **严重级别**：P1（理论上返回缺失行）。**当前实践等级 P2**（我 5 组探针未能稳定构造）。 +- **复现思路**：【已实测确认】单文件 > cacheLimit 时，`trimCache` 后 `sstableCache` 被清空 + （cacheSize 由 6202 → 0），`lsm.get` 直接返回 null；公开 `find` 仍正确，因为它在读之前又做了一次 + prefetch。构造稳定复现需要在**一次 `prefetchKeys` 内**装入的两个文件都大于 cacheLimit + （先装的后被目标文件挤出）—— 由于 L0≥8 会触发 compaction，我未能在稳定配置下达成。 + **验证方法**：给 `AriaEngine` 加一个"禁止 prefetch"的测试开关，或直接构造 + `prefetchKeys(['t:a','t:z'])` 后立即 `get('t:a')`（两 key 各命中一个超大文件，cacheLimit 小于单文件）。 + **建议**：`loadSSTableReader` 改为 async 回源（或让 `get` 走 `getWithFallback`）， + 至少把"缓存未命中"与"确实不存在"在类型上分开（`null` vs `undefined`/`MISS`）。 + +### P1-2　`rangeScanLazy` 的 `callback` 返回值契约与 `rangeScan` 包装自相矛盾（早停未真正生效） +- **文件:行号**：`src/engine/aria/index/lsm.ts:440-479`（`callback` 声明返回 `boolean | void`， + 473-475 `if (cont === false) return;`）、`428-432`（`rangeScan` 的包装回调 `{ result.push(...) }` + **返回 undefined**，天然无法早停）、`index.ts:1220-1225`（`findStream` 依赖 `false` 早停）。 +- **现象**：`findStream` 的 limit 早停是"**多读一条再返回**"：`for...of` 在消费完 yield 值之后才会 + 执行 `callback()` 并据此决定是否中断，而生成器已经推进到了下一条（`merge_iterator.ts:50-53` + + `memtable.ts:133-143` 的 `stack.pop()` 之后才 `yield`）。即"未消费块/子树不再解析"的 v0.7.4 宣称 + **方向正确但边界多算 1 条**；更实际的问题是 `rangeScan` 包装层使早停能力对内部调用者不可见。 +- **根因**：`EntrySource.next()` 是"推送一条"的游标语义，缺少 `peek()`/`close()`； + 生成器在 `yield` 后无法收到"下游不要了"的信号（`GeneratorEntrySource.reset()` 是空实现，55-57）。 +- **严重级别**：P2（性能/接口语义），P3 级别的一行偏差。 +- **复现思路**：【已实测确认】`limit=5` 的流式扫描中，生成器实际产出 6 条（produced=6）。 + **验证方法**：在 `findStream` 里统计 `scanLazy` 的 `next()` 调用次数，或断言 + "produced === limit"。 + +### P1-3　`SSTableReader` 有三处重复且各自独立的解析循环（解析语义漂移风险） +- **文件:行号**：`src/engine/aria/index/sstable.ts:80-100`（`get` 的手写循环）、`145-166`（`scanLazy`）、 + `182-201`（`scanAll`）；三处都各自重算 `lenFieldSize()`、各自 `new TextDecoder()`、各自做越界 `break`。 +- **现象**：三份实现的越界策略并不一致：`get` 在长度字段越界时 **`break` 整个块并返回 null**， + `scanLazy/scanAll` 同样 `break` 但继续下一块。同一份损坏文件在"点查"与"扫描"下表现不同， + 且 v0.6.1 的"多扫一块"修复只加在 `scanLazy`（131）——`get` 依赖 `locateBlock` 的另一种归纳（302-306）。 +- **严重级别**：P2（可维护性直接转化为正确性风险，历史上已多次在此处出 P0）。 +- **复现思路**：**验证方法**：属性测试——对随机 SSTable（含单条超大 value、全同前缀 key、 + 空块、末块只 1 条）断言 `get(k) === scanLazy(k,k)[0]` 且 `scanAll()` 与 + `scanLazy('','\uffff\uffff')` 元素级相等。 + +### P1-4　事务内二级索引领先于主表 + `mergeTxnSnapshot` 只按 PK 去重，存在"索引返回陈旧行"的缝隙 +- **文件:行号**：`index.ts:647`（`updateSecondaryIndexes` 事务内立即写索引）、`684`（`find` 先索引后合并）、 + `1620-1638`（`mergeTxnSnapshot`：`rows.findIndex(r => r[pkCol] === pk)`，命中才替换、未命中则 **push**）。 +- **现象**：事务内 `INSERT/UPDATE/DELETE` 走"索引立即生效、主表延后"，而 `find/getAllRows` 是 + "先索引/磁盘视图，再叠加快照"。当索引给出一行、而该行的**快照版本 PK 与磁盘版本 PK 不同**时， + `findIndex` 找不到对应行 → 同一行被 **push** 成两条。 +- **根因**：快照只存行内容、不存"原 PK"；`updateSecondaryIndexes(table, newPk, updated, row)`（852） + 在主表键变更时把索引迁到 newPk，而 `mergeTxnSnapshot` 无法把"索引里的 oldPk 结果"与 + "快照里的 newPk 行"识别为同一实体。 +- **严重级别**：P1（错误结果，事务内重复行）。**当前为"推测"**：我按 + "事务内更新索引列 + 按旧值查询"以及"人工植入陈旧索引条目"两种路径探针，**均未复现** + （因为 v0.6.2 起 `updateSecondaryIndexes` 会同步删掉旧索引条目）。触发需要对 + 索引 LSM 与主 LSM 的**新增/删除顺序**有更细的时序（例如 `applyForeignKeyRules` 的 + SET NULL 分支 1139-1161 与主循环 1028 的组合）。 +- **复现思路**：**建议验证法**——在 `mergeTxnSnapshot` 前后各打一次 `rows.length` 与 PK 去重后的长度， + 跑 `aria-matrix-audit.test.ts:70-99`（事务内 100 次 update + 索引断言）并把 + `WHERE` 换成被更新列的**旧值**；若出现 `rows.length > uniquePk` 即命中。 + +### P1-5　`compacting` 是全局单标志，跨层 compaction 触发会被静默丢弃（维护饥饿） +- **文件:行号**：`lsm.ts:78`（单 boolean）、`269-283`（`scheduleCompact`：`if (this.compacting) return;`）、 + `286-302`（`enqueueCompact` 同判断）；`finally` 里的 `this.compacting = false`（273、293、296） + 会被**较早任务**的 finally 提前清零，从而允许两个 compaction 任务同时在链上排队。 +- **现象**：① 只要有一个层的 compaction 在跑（可能耗秒级），**其它层的触发全部被丢弃**， + 只有"当前层完成后的级联检查"能补一次（275-281），于是深层/次层的维护会被持续饿死； + ② 反方向：标志被提前清零 → 同一层可能被排两次（`compactLevelAsync` 开头有 `length < minFiles` 保护， + 第二次是空转，故不致命）。 +- **严重级别**：P2（层级失衡 → 读放大与空间放大持续恶化）。若未来 compaction 承担墓碑清理，会升级为 P1。 +- **复现思路**：【已读代码确认】：构造 `memtableSizeThreshold` 很小、写入集中在两张表/两个索引 LSM 的场景， + 在 `compactLevelAsync` 里插桩计数，可观察到 `scheduleCompact(1..6)` 因 `compacting===true` 被 drop。 + **验证方法**：断言"稳定态下 `levelCounts[i] <= 4`"，当前在大批量写入下不成立。 + +### P1-6　`flush()` 一旦记录过后台错误就**永久拒绝**执行真正的 flush（WAL 永不截断） +- **文件:行号**：`lsm.ts:580-590`（`if (this.lastBackgroundError !== null) { ...; throw ... }` 位于 + `drainChain()` 与所有入链动作**之前**）、`193-204`（错误只写不清）、`194-204` 的 catch 恢复链。 +- **现象**：任何一次后台 flush/compaction 抛错（例如 `store.save` 配额不足），此后**每一次** + `lsm.flush()` 都在第 582-590 行直接抛 `ARIA_BACKGROUND_ERROR` —— memtable **永远不落盘**， + `wal.checkpoint()` 永不执行（WAL 无界增长），`close()` 也在第 284 行抛出而跳过后续清理， + 应用层除 `repair()` 外无自愈出口。 +- **根因**：把"报告上一次错误"与"执行本次 flush"耦合在同一函数入口，且错误用"消费一次"的语义 + （583-584 清空）却放在会抛出的路径上 —— 第一次抛错后错误虽被清空，但调用方拿不到"已经 flush 成功"， + 且**这次调用根本没有 flush**。 +- **严重级别**：P2（可用性/持久化停滞；若进程随后崩溃则内存中的数据全丢 = 实际 P0，见 P0-3）。 +- **复现思路**：**验证方法**——注入一个 `save()` 第一次抛错、之后正常的 `SSTableStore`： + `await lsm.put(...); await lsm.flush().catch(()=>{}); await lsm.flush()` → 第二次仍抛错 + 且 `getStats().sstableCount` 为 0。 + +### P0-3　后台 flush 失败后，内存中的冻结数据没有重试路径（进程崩溃即丢） +- **文件:行号**：`lsm.ts:220-261`（`flushImmutableAsync` 在 `save`/`saveMeta` 抛错时， + `frozenMemtables` 的清理（255）与 `levels[0].unshift`（253）都不会执行）、`619` + （`flush()` 末尾 `filter(f => f.getEntryCount() > 0)` 保留非空冻结表但**不会重新入链**）。 +- **现象**：冻结表留在 `frozenMemtables` 里可读（所以在线查询看似正常），但它只被 `flush()` 里 + "当前 immutable"那一次入链机会覆盖；一旦那一次失败，后续 `flush()` 受 P1-6 阻断， + 这些数据**只存在于内存**。此时进程崩溃 → 数据丢失，而调用方早已收到 `insert()` 成功。 +- **根因**：入链是"事件驱动一次"，没有"待落盘队列 + 重试"的持久化意图记录； + `lastBackgroundError` 只报告不重试；`frozenMemtables` 语义在"读可见集合"与"待落盘队列"之间摇摆。 +- **严重级别**：**P0（数据丢失）**。 +- **复现思路**：【已读代码确认】+ 可测：注入首次 `save` 失败的 store，`insert` → `flush`（吞错）→ + 断言 `frozenMemtables.length > 0` 且 `levels[0].length === 0`；再调用 `flush()` 观察其抛错且仍未落盘。 + **验证方法**：在第二次 `flush()` 后断言 `sstableCount > 0` —— 当前失败。 + +### P2-1　`compactLevel(level, minFiles=2)` 对单文件层是静默 no-op，`vacuum()` 仍宣称压缩了 6 层 +- **文件:行号**：`lsm.ts:486-500`（`if (this.levels[level].length < minFiles) return;`）、 + `index.ts:2247-2261`（循环 0..5，`if levelCounts[level] >= 2` 才调用，最后 `return { compiledLevels: 6 }`）。 +- **现象**：`levelCounts[level] === 1` 的层永远不会被压缩（尤其 L6，`compactLevelAsync` 还要求 + `level < MAX_LSM_LEVELS-1`，499），而 `vacuum()` **硬编码返回 `compactedLevels: 6`**， + 与 `aria-maintenance.test.ts:70-74` 只断言"属性存在"的弱断言互相掩盖。 +- **严重级别**：P2（空间回收失败 + 指标失真）。 +- **复现思路**：【已实测确认】探针中 `compactLevel(1)` 在 L1 只有 1 个文件时直接返回，层结构不变。 + **验证方法**：断言 `vacuum()` 的 `compactedLevels` 等于实际执行合并的层数（统计 compaction 前后 + SSTable 数量差）。 + +### P2-2　compaction 不丢弃被覆盖/被墓碑遮蔽的历史版本（空间与写放大无界） +- **文件:行号**：`lsm.ts:537-552`（`drain()` 全量写回新文件，无"同一 key 只保留最新"与 + "墓碑可丢"的判定）。 +- **现象**：`MergeIterator` 本身已保证同 key 只吐一条（`merge_iterator.ts:148-168`），所以同一份 + compaction 产物内部没有重复版本；**但墓碑与"已被墓碑遮蔽的更旧版本"只要不在同一次 compaction 中出现， + 就会各自留存**。典型放大：先写 v1（L1）、再写 v2（L2）、再删（L0），三次 compaction 后 + 三个物理条目仍在，只有最外层墓碑生效。90% 删除场景下空间几乎不回收。 +- **严重级别**：P2（空间/写放大；在"删多写少"负载下会退化到不可用）。 +- **复现思路**：**验证方法**——`aria-prod-load.test.ts:222-256`（删 90%）后断言 + `Σ totalSize` 显著小于删除前体量；当前只会看到总量持平或上涨。 + +### P2-3　崩溃窗口内 `saveMeta` 与 `deleteMeta`/`delete` 之间无 WAL/事务保护 +- **文件:行号**：`lsm.ts:565-576`（顺序：`cacheSSTable` → `save` → `saveMeta` → `unshift` → + `deleteMeta`+`delete` 旧文件）；`init` 119-129 仅按 `listMeta()` 重建。 +- **现象**：崩溃落在 `saveMeta(new)` 之后、`deleteMeta(old)` 之前时，磁盘上会**同时**存在新文件与旧文件 + 的两条 meta；重开时 `init()` 全部加载，层内出现**重叠文件**。我逐一验证了每个时点的层间新鲜度， + 结论是**当前不会返回错误值**（新文件总是被删文件的超集且更新，同名 key 的新值一定在新文件里）， + 所以这条不是错误结果 bug；但它① 让层内重叠成为常态，② 泄漏已 `delete` 掉的文件引用会让 + `validateSSTable` 在下次打开时**删除对应 meta**（685-711 → 713-725）， + ③ 孤儿 `sst_*` blob **没有任何清理路径**（`cleanupOrphanPages` 只清理 `pg_*`，`index.ts:352-388`）。 +- **严重级别**：P2（元数据/存储泄漏与"重叠层"常态化；若未来引入跨层归并会立刻变成 P1）。 +- **复现思路**：【已实测确认】按真实时序（`saveMeta` 后模拟崩溃）重建磁盘状态并重开，层结构为 + `L0: old@L0 | L1: new@L1`；数据读取仍正确，但**旧文件残留**。 + **验证方法**：断言 compaction 结束后 `listKeys()` 中的 `sst_*` 数量 == `Σ levelCounts`。 + +### P2-4　`compaction` 预先 `splice` 整层，长 `await` 期间该层对读者不可见 +- **文件:行号**：`lsm.ts:502`（`splice` 清空该层）→ `506-535`（逐个 `await store.load` + `scanAll`）→ + `569`（`unshift` 新 meta）。 +- **现象**：从 `splice` 到 `unshift` 之间（含 N 次磁盘读 + 全量解析 + 构建 + `save` + `saveMeta`）， + 该层的所有数据**从 `levels` 中消失**。上层数据仍在，所以最终结果通常完整 —— 但若某个 key + **只**存在于该层（例如它已被从上层 compaction 下沉），这段时间内 `get` 会返回"不存在"。 + 另外 `compactLevel` 是 public（`index.ts:2252-2254` 直接调用）， + 期间任何并发 `insert`（不 await 链）都可能观察到半完成状态。 +- **严重级别**：P2（窗口期内的错误结果；窗口长度正比于层体积）。 +- **复现思路**：**验证方法**——在被 splice 的层里放一个"仅此一份"的 key，在 compaction 的 + `await store.load` 处注入延迟（monkey-patch），并发 `find` 该 key，应观察到空结果。 + +### P2-5　`enqueueCompact` 未走 `enqueueOnChain`，其 Promise 无终结处理器 +- **文件:行号**：`lsm.ts:286-302`（`this.flushChain = this.flushChain.then(...).catch(...)`） + 对比 `enqueueOnChain`（194-204，走 `.catch` 且链保持 resolved）。 +- **现象**：`enqueueCompact` 里的 `.catch` 返回 `undefined`，链会恢复；但它的 `.then` 与 `catch` + 之间若 `finally` 内（元数据操作）再抛错，错误会逃逸到无人 `await` 的链尾。由于 `put/delete` + 是**同步**调用 `enqueueCompact`（145-147、156-158），调用方拿不到这个 Promise， + Node 环境会打印 `unhandledRejection`，浏览器控制台出现噪声，错误处理语义与另一条路径不一致。 +- **严重级别**：P3（当前仅噪声；若策略变为 `unhandledRejection` 致命则升级）。 +- **复现思路**：**验证方法**——让 `enqueueCompact` 的任务抛错并监听 `process.on('unhandledRejection')`。 + +### P2-6　`checkpoint` 只对 `currentTxnId` 做保护，事务活跃期间 WAL 缓冲可能被截断的相邻风险 +- **文件:行号**：`index.ts:249-276`（`checkpoint`/`flush` 回调：`if (this.currentTxnId) return;`）、 + `wal/log.ts` 的 `flush`/`checkpoint` 语义。 +- **现象**：保护只覆盖 Aria 自己的"单活跃事务"字段。事务提交路径是 + `wal.append(COMMIT)` → `wal.flush()` → 合并快照（`index.ts:1473-1489`）， + 其间 `currentTxnId` 仍非空，保护有效 —— 但 `commitTransaction` 把 `currentTxnId = null` + （1493）放在**快照合并之后**，即"快照合并完成 → 置空"之间存在一个窗口， + 此时若并发的 `insert()` 触发 `checkpointManager.tick()`（`index.ts:664`）→ `checkpoint()` + 会立刻执行 `lsm.flush()` + `wal.checkpoint()`，把刚刚 COMMIT 的 WAL 截断。 + 截断本身安全（数据已在 LSM），但**它同时会 drain 掉正在排队的后台 compaction** —— 属于时序耦合。 +- **严重级别**：P3（当前不丢数据，但依赖"合并先于置空"的隐含顺序）。 +- **复现思路**：**验证方法**——在 `commitTransaction` 的 `lsm.put` 循环中插入 `await checkpoint.tick()` + 的并发调用，断言不会出现"WAL 已截断而 LSM 未落盘"的组合；建议把置空提前到合并**之前**并用 + 独立的 `committing` 标志保护。 + +### P2-7　内存预算只统计主 LSM 的估算，且 `cacheLimitBytes` 按索引 LSM 数量线性放大 +- **文件:行号**：`index.ts:2143-2151`（`checkMemoryBudget` 只查 `this.lsm.getEstimatedMemory()`）、 + `lsm.ts:167-172`（估算含 `cacheSize`）、`index.ts:168,199,457,1358`（每个 LSM 各自 + `cacheLimitBytes = bufferPoolPages × pageSize`）。 +- **现象**：N 个二级索引 LSM ⇒ N×1MB 的 SSTable 缓存 + 每索引各自的 `MemTable` + （每个默认阈值 4MB，见 `lsm.ts:88-89`）+ 主 LSM 1MB；`maxMemoryMB`（默认 64）**完全看不到**这部分。 + 再叠加页面化后同一份 SSTable 同时存在于 `BufferPool` 页缓存与 LSM 整文件缓存， + 且各索引 `MemTable` 在 `walSyncMode:'none'/'batch'` 下**不落盘也不设上限**。 +- **严重级别**：P2（OOM/GC 压力；"maxMemoryMB=64" 的宣称无法兑现）。 +- **复现思路**：**验证方法**——建 10 个索引列，写入后断言 + `Σ(lsm.getEstimatedMemory()) <= maxMemoryMB*1024*1024`；当前会超。 + +### P3-1　`applyWALRecord` 不做任何校验/墓碑语义转换，直接 `lsm.put` +- **文件:行号**：`index.ts:1829-1856`。重放 INSERT/UPDATE 直接 `this.lsm.put(key, record.data)`。 +- **现象**：WAL 中的行若含 schema 外列或已删除列（历史版本写过），重放会原样落库， + 绕过 `validateRow`（与 v0.7.4 修"UPDATE 未知列静默入库"的方向相反）。 +- **严重级别**：P3（恢复路径的防御缺口，需先有脏 WAL 才成立）。 +- **复现思路**：**验证方法**——伪造一条含 `{ ghost: 1 }` 的 INSERT WAL 记录后重开，断言该列被丢弃。 + +### P3-2　`serialize()` 返回内部缓冲区引用；`page_sstable_store.load()` 会 `pageIds.delete(id)` +- **文件:行号**：`bloom.ts:66-68`（`return this.bits`，未拷贝）、 + `store/page_sstable_store.ts:81`（`this.pageIds.delete(id)` 在**读**路径上执行）。 +- **现象**：前者使调用方一旦持有序列化结果后再 `insert` 就会修改"已写出"的字节； + 当前 `build()` 的调用顺序（108 行取 bloom → 113 行分配 buf → 119-130 写出，**不再 insert**）恰好安全。 + 后者使"同一 SSTable 先 `load` 再 `saveMeta`"会丢掉 `pageIds`（`index.ts:1800` 取不到 → + meta 无 pageIds → 页面变孤儿）。当前 `save → saveMeta` 紧邻（`lsm.ts:249-250`）故安全， + 但 `compactLevelAsync` 的 `load`（511）与本 LSM 的 `saveMeta` 之间**隔着整个合并流程**， + 一旦将来把 `pageStore.load` 复用到这里就会踩雷。 +- **严重级别**：P3（当前安全，属"靠调用顺序维持"的隐式契约）。 +- **复现思路**：**验证方法**——单测：`bf.serialize()` 后再 `bf.insert('x')`，断言先前返回的字节未变（应失败）； + `pageStore.load(id, ids, size)` 后 `getPageIds(id)` 应仍返回 ids（应失败）。 + +### 已排除的怀疑（避免误导） + +| 怀疑 | 结论 | 依据 | +|---|---|---| +| Bloom Filter 会产生 false negative | **排除（对未损坏文件）** | 【已实测确认】`h1 ∈ [0,2^32)`、`h2 ∈ [0,2^31)`，`h1 + i*h2` 永不溢出双精度安全整数，`% bits` 结果**恒非负**，故 `Math.abs` 是冗余而非错误；`bits` 恒为 8 的倍数，索引恒在界内。30k 随机 key 单键过滤器 + 5k 随机 key 密集过滤器 + 5 种真实 key 形态各 2000 key，**FN 全部为 0**；真实 SSTable 2000 key 全覆盖读取 0 缺失 | +| `Math.abs((h1+i*h2) % bits)` 是哈希 bug（负余数取绝对值） | 排除（同上） | 同上；但 `fromData` 若传入与写入端**不同**的 `numHashes` 会 100% 产生 FN（实测 10 键 9 个 FN）—— 当前文件路径读写都用 footer 里的同一值（`sstable_builder.ts:138` ↔ `sstable.ts:230,246`），故不成立 | +| 崩溃中断 compaction 会让旧文件遮蔽新数据 | **排除** | 【已实测确认】逐时点验证层间新鲜度：新产物恒为被删文件的超集且更新，同名 key 的新值必在新文件中 | +| PK 删除墓碑 `t:k1\uffff` 会误删 `t:k10` | **排除** | 【已实测确认】`key <= endKey` 的字符串比较下 `t:k1 < t:k10`（第 4 字符 `'\uffff'` vs `'0'`），memtable 与 compaction 后均只删 1 行 | +| 红黑树删除/旋转会破坏中序有序性 | **排除（4000 步压力下）** | 【已实测确认】400 键 × 4000 次随机 put/delete 后 `getAllEntries` 与排序参照集**完全一致**，`_size` 准确，`rangeScan` 与过滤结果一致 | +| `rangeScan` 边界/`locateBlock` 系列二分有 off-by-one | **排除** | 【已实测确认】`aria-sstable.test.ts` 的 13 组边界（块尾、跨前缀、空表、末块）+ 我的补充探针全绿 | +| LSM 端到端会产生错误结果 | **当前未发现（常规路径）** | 【已实测确认】8 组差分 fuzz（插入/更新/删除/按索引列批量更新/按 tag 查索引，400-600 步 × 含/不含 `compactLevel(0..2)`，与参照 Map 全量比对 + 每列索引计数比对）：**problems = 0** | + +--- + +## 3. 性能议题 + +### 3.1 每次写批次都 `drainChain`，compaction 期间写路径整体停摆 +`checkpointManager.tick()`（`index.ts:664`）→ `CheckpointManager.checkpoint()`（`checkpoint.ts:62-69`） +→ `lsm.flush()`（`lsm.ts:580`）→ `await this.drainChain()`（592）。 +`drainChain` 会等到**链上全部后台任务**（含正在跑的整层 compaction：N 次 `store.load` + 全量解析 + +构建 + `save`）结束。默认 `checkpointInterval = 1000`，即**每 1000 个操作就要等一次完整 compaction**。 +这正是 CHANGELOG v0.6.1 记录的"10 万行 kv 插入 353s、每批 8~11s"的机制来源； +v0.6.1 只移除了"逐行 prefetch"这一半，`tick()` 里的等待仍在。 +**观察点**：`aria-prod-load.test.ts:320` 的日志与 240s 护栏就是它的间接度量。 + +### 3.2 一次扫描把**全表** SSTable 拉进缓存 +`getAllRows`（`index.ts:1601-1614`）与 `findStream`（1219）都先 +`prefetchRange(prefix, prefix+'\uffff')` → 遍历**所有层所有 meta**（`lsm.ts:318-327`）→ +逐个 `preloadSSTable`（整文件字节读入 + `verifyChecksum` 全文件 CRC + 构造 Reader）。 +对 100k 行表意味着把整个表读进 1MB 上限的缓存（随后被 `trimCache` 清掉）， +每次范围查询重复一次全量 I/O。**没有按需/分块读取**。 + +### 3.3 二级索引范围查询退化为"全索引扫描 + 逐行主表点查" +`tryIndexLookup`（`index.ts:2085-2092`）：`$gt/$gte/$lt/$lte` 走 +`indexScanToRows(idxLsm, '', '\uffff')` —— **扫全部索引条目**（`prefetchRange('','\uffff')` 把整个 +索引拉进缓存），然后对每个 pk 做一次 `lsm.get`（`index.ts:2115-2118`，每次 `get` 会在每层 +最多做一次 bloom + 一次块内线性扫描）。复杂度 = O(索引全量) + O(命中行数 × 层数 × 块内扫描)。 +更根本的问题在**索引键编码**：`${String(value)}:${pk}` 是**字典序**， +数值范围在字典序下不可用（`"10" < "9"`），所以就算把下推逻辑修好也无法做数值区间扫描。 +注释（2086-2089）也坦白这是"为修复 v0.6.2 的丢数据而改为全扫"。 + +### 3.4 compaction 不做版本/墓碑回收 → 空间与写放大随层数累积 +见 P2-2。每一层的"整层合并"都会把该层**所有**物理条目（含无数历史版本与墓碑）重写一遍， +`compactLevelAsync` 还会先把整层 `scanAll` **物化到内存数组**（531-534）。 +在"更新同一批行"的负载下，每次 L0→L1 的产物体积 ≈ L0 体积 + L1 既有体积， +形成典型写放大螺旋；`aria-cache.test.ts:212-237`（同一行更新 20 次）之所以能过， +是因为数据量小到看不出来。 + +### 3.5 SSTable 块密度低于配置值（索引条目 ≈ 2× 需要） +`splitIntoBlocks`（`sstable_builder.ts:171-178`）在"加入当前条目后 ≥ 上限"才封块， +且封块时**把最后一条留到下一块**（175-176），于是首块只含 1 条、其余块 ≈ 上限+1 条。 +【已实测确认】用 ~90 字节的行、4096 上限构建时，单块实际可达 ~8.2KB， +块数因此约为理想值的 **1/2**：`IndexEntry` 数组更大（内存）、索引块更大、 +`locateBlock` 的二分目标更多、每次点查的"块内线性扫描"更长（`sstable.ts:80`）。 +此外 `indexEntries` 在 Reader 构造时**全量物化**（`sstable.ts:253-277`）， +每个 Reader 都持有一份"每块一个 key"的索引键数组（按上述密度，10 万行约 1.2 万条/文件）—— +**每层每个文件各一份**，且 `prefetchRange` 会把命中的文件全部构造 Reader。 +（我把"分块策略错误"降级为性能问题：它的正确性被 `aria-sstable.test.ts:88-159` 的跨块用例覆盖了。） + +### 3.6 其他可量化热点 +- **`MemTable.put` 每次做两次 `Object.entries` + 一次额外树查找**（`memtable.ts:429-431` + + `497-510`）：`estimateEntrySize` 对每个字段做 `typeof` 分支，且 `this.tree.find(key)` 是完整一次下降。 +- **WAL 编码逐条 `JSON.stringify` + 逐条 `TextEncoder`**（`wal/log.ts:90-109`）， + 大批量插入时 `appendBatch` 会把整批序列化两遍（编码 + 合并）。 +- **`analyzeTable` 的 `avgRowSize` 用 `JSON.stringify(row).length` 逐行再序列化**（`index.ts:2177`）， + 且 `columnStats` 用 `new Set(rows.map(String))` 再扫一遍 —— 大表上 ANALYZE 是 3~4 遍全表 CPU。 +- **`count()` 恒定物化全表**（`index.ts:1229-1236`），无 where 时依然走 `getAllRows`。 +- **`alterTable`、`applyDropTableRecovery`、`dropTable` 都是"扫描全表 → 逐行 put/delete"** + （`index.ts:1314-1338`、1874-1878、483-487）：DROP TABLE 10 万行 = 10 万次 `lsm.put`/`delete` + （每次都带 `estimateEntrySize`）+ 10 万条 WAL。 +- **`update` 的批内唯一互查/计划阶段对每行调用 `checkUniqueSync`**（`index.ts:1900-1923`）， + 其中 `idxLsm.rangeScan` 每次都会走完整 `prefetchRange`+`rangeScanLazy`（虽然是单前缀）。 +- **`trimAllCaches` 在 `find/update/delete` 末尾各遍历一次全部二级索引**（`index.ts:2136-2141`）， + 与 `prefetch*` 里的 `trimCache` 叠加导致"装入-驱逐-再装入"抖动。 + +--- + +## 4. 系统性观察 + +### 4.1 反复出 bug 的结构性原因 + +1. **键编码散落在 10+ 处，没有单一编码模块。** 主键 `t:pk`（`index.ts:571,1006,1223`…）、 + 二级索引 `value:pk`（1382、1953、2237）、索引前缀探针 `v:` ~ `v:\uffff`（605-606、751-758、2063）、 + 删除 `v:pk`（1945）、唯一性检查（1911-1912）、表范围 `prefix` ~ `prefix+\uffff`（1315、1605、1873、2023）、 + 命名空间 `idx_${table}_${col}`（200）。任何一处想改（比如给值加类型前缀以修复字典序问题） + 都要同步 10 处，漏一处就是静默丢数据 —— v0.6.2 的"索引范围查询丢数据"就是这个模式。 +2. **SSTable 解析循环被抄了三份**（`sstable.ts:80/145/182`），越界策略各不相同。 + v0.6.1 的 P0（块尾 key 越界漏读）只需要修一处，但另外两处仍在，下一次同类 bug 仍会出现。 +3. **不变量没有被断言，也没有被文档化。** 至少五条隐式不变量：① 层号越小越新； + ② 同一层文件区间不重叠；③ 索引键 = 块内最后一个 key；④ `minKey/maxKey` 覆盖文件全部内容； + ⑤ bloom 的 `numHashes`/位数与写入端一致。它们散落在注释里，没有任何 `assert`、 + 没有 debug 模式校验、没有属性测试。P0-1 / P1-1 / P2-3 全都是"不变量没人守"的直接后果。 +4. **后台任务模型是"fire-and-forget + 吞错 + 单标志互斥"。** + `compacting`（一个 boolean 管 6 个层）、`lastBackgroundError`（一次性报告、语义含混）、 + `flushChain`（Promise 链自我修补）、`setTimeout` 曾被用来分片后来又被移除（v0.4.3 注释）—— + v0.4.2/v0.4.3/v0.6.1/v0.6.3 的修复记录（链被 rejected 卡死、close 后定时器写库、 + meta 竞态丢 75% 数据、重复 flush 出 3 个文件）**全部**出自这一块。 +5. **"缓存未命中 ⇒ 当作不存在"是本子系统最危险的隐式约定。** 为了保持 `get/rangeScan` 同步， + 引擎被迫在**每次**读取前 `drainChain + prefetch`（`index.ts:574,1219,1605,2024,2106,2113,2077`）， + 这既制造了 3.1/3.2 的性能悬崖，也让"漏一次 prefetch 就静默丢数据"成为常态风险。 + `compactLevelAsync` 已经被迫单独修过这个问题（508-515），而 `get` 仍未修 —— 同类修复只做一半。 +6. **测试是端到端 + 弱断言为主。** 大量 `expect(x).toBeGreaterThanOrEqual(0)` 形态 + （如 `aria-maintenance.test.ts:41,72`），性能测试用 240s 宽护栏掩盖机制性问题， + 没有针对 compaction/bloom/块边界的**属性测试**。这解释了为什么 + "10 万行 0 错误" 与 "同一个函数里有 3 份解析循环" 能长期共存。 + +### 4.2 最高杠杆的架构改动（一条） + +> **把 LSM 从"同步读 + 调用方负责预取"改成"自洽的异步读"，并让后台工作变成显式持久化的任务队列。** + +具体分两步、但核心是第一步： + +1. **让 `get` / `rangeScan` 自己负责 I/O 与缓存罚失**：`LSM.get` 改为 + `async get(key): Promise`，内部对每层调用 + `await this.readerFor(meta)`（缓存命中直接用，未命中 `store.load` + CRC + 入缓存）， + MISS 与"不存在"用不同类型区分；`rangeScanLazy` 改为 async generator， + 每块按需 `await` 读取（配合已有的 `scanLazy` 块级生成器，天然支持）。 + 一旦如此：引擎层所有 `drainChain()+prefetch*` 的调用点（7 处）全部可以删掉， + 3.1 的"每批写等 compaction"与 3.2 的"全表预载"同时消失， + P1-1（缓存罚失当作不存在）从"靠约定"变成"结构上不可能"。 +2. **把 `flushChain` 换成带意图记录的串行工作队列**：`pending: Array<{kind:'flush'|'compact', level?, frozen?}>` + + 每个任务的终态（成功/失败/待重试）显式记录，失败任务**保留在队列里可重试** + （直接解决 P0-3、P1-6），`compacting` 单标志换成 `Set`（解决 P1-5）， + 并发 compaction 的层集合由队列调度器保证互斥。 + +配套（低成本、高收益）：抽出唯一的 `keyCodec` 模块（`encodePk/encodeIdx/encodeIdxValueRange/tableRange`）， +把 `sstable.ts` 的三份解析循环合并为一份"块迭代器"（`get`/`scanLazy`/`scanAll` 都基于它）， +并在 `SSTableReader` 构造时加 debug 断言（索引键单调递增、块偏移在文件内、`minKey<=maxKey`）。 + +--- + +### 附：本次审计中已删除的探针清单（工作区无残留） + +`tests/engine/` 下共 16 个临时测试文件，已全部 `rm`（`git status` 已确认无残留）： + +``` +zz-probe1.test.ts zz-probe2.test.ts zz-lsmprobe.test.ts zz-lsmprobe2.test.ts +zz-crash-probe.test.ts zz-delprobe.test.ts zz-delprobe2.test.ts zz-fuzz.test.ts +zz-txnprobe.test.ts zz-dup-probe.test.ts zz-idx-probe.test.ts +zz-cache-hole.test.ts zz-cache-hole2.test.ts zz-cache-hole3.test.ts +zz-cache-hole4.test.ts zz-cache-hole5.test.ts +``` + +（编号 3–8 的 bloom 探针是在 `zz-probe1.test.ts` 内迭代改写后重跑，未额外留文件。） +审计未修改任何 `src/` 文件；`tests/zz-verify-kv*.test.ts` 与三份 `AUDIT-*/PLAN-*` 属其它会话产物，非本次创建。 diff --git a/AUDIT-query-layer-v0.7.4.md b/AUDIT-query-layer-v0.7.4.md new file mode 100644 index 0000000..2e97bcd --- /dev/null +++ b/AUDIT-query-layer-v0.7.4.md @@ -0,0 +1,346 @@ +# MetonaSqlark v0.7.4 — 查询层（AST / Builder / Compiler / Executor / Where-Matcher）深度审计报告 + +审计范围：`src/query/{ast,builder,compiler,executor,where-matcher,index}.ts`（逐行读完）、 +`tests/query/query-system.test.ts`、`tests/{join,subquery,groupby}.test.ts`、 +`tests/v07{0,1,2,3,4}-*.test.ts`、`tests/{foreign-key-cascade,transaction-rollback}.test.ts`、 +README（核心特性 / API 速览 / 已知限制）、CHANGELOG 1–300 行。 + +方法：先逐行读码定位可疑路径，再写临时 jest 探针（`tests/zz-audit-probe*.test.ts`，已删除）实跑验证。 +下文每条标注 **[已验证]**（有实跑输出）或 **[读码确认]**（未实跑，但根因路径可指到具体行）。 + +--- + +## 1. 架构概览 + +### 1.1 SQL 字符串 → 解析 → 编译 → 引擎 + +| 阶段 | 位置 | 实际做的事 | +|---|---|---| +| 入口 | `core.ts:207-242` | `bindParameters`（`sql/params.ts`）→ `parseAll` → 逐条 `executor.execute(stmt)`；**多语句顺序执行、返回最后一条结果、无事务包裹** | +| 解析 | `sql/parser.ts`（递归下降，1331 行） | 产出 `query/ast.ts` 的 AST。子查询不建关系算子，而是打成 `$subquery` / `$col` / `$exists` 标记（parser.ts:845/920/961/977） | +| 编译 | `query/compiler.ts:21-57` | **只做平铺映射**：`{table, columns, where, orderBy, limit, offset}`。没有算子树、没有投影/表达式编译、没有代价模型；JOIN/GROUP BY/DISTINCT/HAVING/聚合全部被丢弃。只有 SELECT/DELETE/UPDATE 可编译，其余抛 `COMPILE_ERROR` | +| 执行 | `query/executor.ts` | 关系语义全部在 JS 里做：JOIN、GROUP BY、DISTINCT、HAVING、关联子查询、UNION、投影 | +| Builder 旁路 | `builder.ts:97-113` | `SelectQueryBuilder.execute()`：**有 JOIN 才走 Executor，无 JOIN 直接 `engine.find`**（builder.ts:105）；`UpdateQueryBuilder`/`DeleteQueryBuilder` 永远直通引擎（`builder.ts:160` / `builder.ts:199`）→ 同一语义两套路径 | + +`compileStatement` 的产物 `QueryPlan` 只描述单表扫描；`stmt.joins/groupBy/distinct/having` 从不进 plan。因此"编译"在本项目里约等于"把 WHERE 交给引擎"，不存在下推优化器（唯一的优化是 JOIN 查询里主表别名等值条件的抽取下推，`executor.ts:413-417 / 457-471`）。 + +### 1.2 Executor 如何逐子句处理（`executeSelect`，`executor.ts:282-400`） + +决策树（282-356）： + +1. `fromSubquery`（派生表）→ 先跑子查询取行；有 JOIN 则给行加 `<别名>.` 前缀后进入 JOIN 路径（297-307）。 +2. 无 FROM 且无 JOIN（`SELECT 1`）→ 单行空上下文（308-310）。 +3. 有 JOIN → `executeJoinSelect`（311-313）。 +4. 普通单表（314-355）：先把 WHERE / ORDER BY / GROUP BY / SELECT 列里的主表别名前缀剥掉（316-336）；若 WHERE 命中 `$col`，走 `filterCorrelated` 逐行求值（339-345），否则 `resolveSubqueries` 后交给 `engine.find`（346-355）。 + - **`needsRawRows`（有 CASE）/`hasSelectAlias`（有 `AS`）时强制 `plan.columns = ['*']`，即放弃引擎投影（352）**，投影改在 executor 端做。 + - **`orderByAlias` 为真时清掉 plan 的 orderBy/limit/offset（353）**，留到投影后重排。 + +后处理顺序（358-398，**注意与 SQL 标准顺序不一致**）： + +``` +聚合(无 GROUP BY) 359-361 → GROUP BY 363 → DISTINCT 364 → HAVING 365-378 +→ ORDER BY 379 → 投影 383-386 → ORDER BY(别名, 第二次) 388-390 +→ slice(offset, offset+limit) 391-393 → maxRowsPerQuery 截断 396-398 +``` + +关键偏差：**DISTINCT 在投影之前**（364 vs 383）、**LIMIT/OFFSET 同时下推给引擎又在此再切一次**、**HAVING 是对投影后的组行做 `matchWhere`**。 + +### 1.3 子查询 / 关联引用 + +- `resolveSubqueries`（1336-1385）递归遍历 WHERE：`$exists` 执行子查询置换为 boolean（1345-1356）；`$and/$or/$not` 递归；字段级交给 `resolveOperatorSubqueries`（1390-1439）。 +- `resolveOperatorSubqueries`：`$in/$nin` 取子查询**第一列**的值列表（1419-1423），其它运算符取**第一行第一列**（1425-1431）；空结果标量 → `null`。 +- `$col` 绑定：`bindColumnRefs`（1291-1309）从 `contextRow` 取列值。 +- 关联上下文只有一条通路：`hasCorrelatedRefs`（1159-1181，纯语法嗅探）→ `filterCorrelated`（1226-1238）逐行 `bindWhereRefs` + 执行 `$exists`。**`resolveOperatorSubqueries` 调 `executeSelect(subStmt)` 时（1417）不传外层行**，所以 `IN (SELECT … WHERE 内层列 = 外层列)` / 标量关联子查询拿不到外层上下文（见缺陷 P1-4）。 +- 代价：关联路径 = 外层每行一次子查询执行，无缓存（1228-1236）。 + +### 1.4 JOIN 实现 + +- 主表：整表（或仅主表别名等值条件下推）物化并加前缀（408-418）；非 JOIN 分支不做前缀。 +- 每个 JOIN：`tryHashJoin`（480-566）→ 条件为"纯等值列对"且右表**至少一列有索引/主键/唯一**时，收集左表探测列去重值 → 一次 `$in` 查询右表 → 复合键 `Map`（键为 `String(v ?? '\0')` 拼接，543/553）→ 左行探测；LEFT 无命中补右表全 null 行（560-562）。 +- 否则 `joinRows` 嵌套循环（569-612）：`matchWhere(merged, on, {$col:true})`；LEFT 用**右表第一行的键集**补 null（593）；RIGHT 再对右表全扫一遍找未匹配行（598-610），并把它们**追加在末尾**。 +- 不支持哈希：CROSS / RIGHT（486），以及 ON 含 `$or`/`$not`/非等值（496/506）→ **右表无条件整表物化**（429）。 + +### 1.5 投影 / 排序 / 分组键编码 + +- 行 = 扁平 `Record`；JOIN 行键为 `alias.col`（447-451），普通行为裸列名。 +- 投影 `projectRow`（1010-1063）：逐行用**正则重新解析** `*`、`col AS alias`、字符串常量、`CASE…END`；`projectColumns`（where-matcher.ts:214-228）先精确匹配键，否则 `key.endsWith('.'+col)` 兜底。 +- 分组/去重键 `encodeGroupKey`（31-39）：类型前缀（`n/u/s/d/b/o/x`），以 `\x1f` 连接（621 / 689 / 170 / 178）。 +- 排序 `applyOrderBy`（where-matcher.ts:183-208）：逐键比较；显式 `NULLS FIRST/LAST` 时 NULL 位置固定，未指定时 NULL 视为最大值（升序在末尾、降序在开头 = PostgreSQL 语义）；类型不同回退 `localeCompare(String(a), String(b))`。 +- **哈希连接、`$in` 探测、`COUNT(DISTINCT)` 不复用 `encodeGroupKey`**（543/553 用 `String(v ?? '\0')`，executor.ts:668 用 `String(v)`）。 + +### 1.6 四引擎的行为分叉点 + +Executor 本身引擎无关，分叉来自被调用的引擎方法： + +| 分叉点 | Memory / Disk(KVStore) / Hybrid | Aria | +|---|---|---| +| 行顺序（无 ORDER BY） | 插入顺序（Map 迭代） | 主键升序（LSM key 顺序）**[已验证]** | +| 主键值类型 | 原类型（number 保持 number） | 全表/范围路径用 `key.slice()` → **字符串**；`$eq` 快速路径用查询字面量原类型（aria/index.ts:1998/2005 vs 2028/1223）**[已验证]** | +| 索引等值 | `Map.get(原始值)`，无条目直接 `return []`（memory.ts:760-768） | `String(value)` 索引键 + 前缀 rangeScan（aria/index.ts:2045/2062） | +| 流式 | `findStream` 同源实现（memory.ts:213-233） | 真惰性 LSM 扫描（aria/index.ts:1172-1227） | +| LIMIT/OFFSET | 引擎内 `slice`（memory.ts:203-205） | 引擎内 `slice`（aria/index.ts:696-699）—— 与 executor 重复 | +| 未解析 `$col/$subquery` 防护 | 仅 update/delete 有（memory.ts:245） | 仅 update/delete 有（aria/index.ts:721） | + +--- + +## 2. 缺陷清单 + +### P0 — 崩溃 + +**P0-1 `MIN`/`MAX` 大分组栈溢出（崩溃）** **[已验证]** +- 文件行号：`src/query/executor.ts:677-678` +- 现象：`SELECT MAX(v) FROM big`（20 万行同组）抛 `RangeError: Maximum call stack size exceeded`；`SUM`/`AVG` 正常（reduce 实现）。 +- 根因：`Math.min(...distinctNums)` / `Math.max(...distinctNums)` 把整组值展开成实参，超过 JS 引擎实参上限。 +- 复现：`CREATE TABLE big (id NUMBER PRIMARY KEY, v NUMBER)`，`insertMany` 20 万行，`SELECT MAX(v) FROM big`。 +- 备注：函数签名 `computeAggregate(...): number`（655）也说明聚合返回类型被硬编码为 number（见 P1-8）。 + +--- + +### P1 — 错误结果 / 静默数据丢失（全部有实跑复现） + +**P1-1 LIMIT/OFFSET 被应用两次（OFFSET 结果截断）** **[已验证]** +- 行号：`executor.ts:391-393`（executor 再切一次）；`compiler.ts:40-41`（limit/offset 进 plan）；`engine/memory.ts:203-205`、`engine/aria/index.ts:696-699`（引擎已切过） +- 现象：id=1..4 的表，`SELECT id FROM t ORDER BY id LIMIT 2 OFFSET 1` → `[{id:3}]`（应为 2,3）；`LIMIT 10 OFFSET 3` → `[]`（应为 4,5）；`OFFSET 2` → 只剩 1 行。 +- 根因：plan 带着 offset/limit 交给 `engine.find`（354），引擎 `slice(offset, offset+limit)` 之后 executor 又 `rows.slice(offset, offset+limit)`（391-393）。只有 `orderByUsesSelectAlias` 为真的查询在 353 行清掉了 plan 的 limit/offset 因而"碰巧正确"。 +- 反证（同 executor 内自相矛盾）：JOIN 路径（405-432 的 `engine.find` 不传 limit）与派生表路径结果正确；`SELECT a.id FROM a JOIN b ON a.k=b.k ORDER BY a.id LIMIT 2 OFFSET 1` → 2,3 正确。 +- 复现：`SELECT id FROM t ORDER BY id LIMIT 2 OFFSET 1`。 + +**P1-2 LIMIT 被下推到 DISTINCT / GROUP BY / 聚合之下** **[已验证]** +- 行号：`executor.ts:352`（`plan.columns=['*']` 但保留 limit）+ `364`（DISTINCT 在切片之前）+ `391-393` +- 现象：`SELECT DISTINCT dept FROM e LIMIT 2` → 1 行（Eng）；`SELECT dept, COUNT(*) AS c FROM e GROUP BY dept LIMIT 2` → 1 组（先被引擎截到 2 行原始行再分组）。 +- 根因：LIMIT 属于最终结果集，却被编译进单表扫描计划（compiler.ts:41），在分组/去重之前就截断了输入行。 +- 复现：5 行 3 个 dept 的表执行上述两条 SQL。 + +**P1-3 `WHERE 表别名.a = 表别名.b`（列对列）在普通单表查询中恒返回 0 行** **[已验证]** +- 行号：`executor.ts:339-345`（关联路径）→ `344` 把 `stripCorrelatedExists(stmt.where)` 交给引擎；`executor.ts:1205-1223`（该函数只剥 `$exists` 与 CASE 键，**保留 `$col` 字段条件**）；`where-matcher.ts:139-150`（`$col` 只有在 `options.$col` 为真时才绑定） +- 现象：`SELECT * FROM t1 WHERE t1.x = t1.y`（(1,5,5),(2,10,3)）→ `[]`（应为 id=1）。`WHERE x = y` 直接 PARSE_ERROR（parser 只在 `ident.ident` 形式才识别列引用，parser.ts:956-963）。 +- 根因：引擎层先执行了带未绑定 `$col` 的条件（`value === {$col:'y'}` 恒 false），把行全部过滤光，`filterCorrelated` 拿到的是空数组。 +- 附带：`tests/v073-fixes.test.ts:267-278` 是这条语义的"回归护栏"，但它只比较 `query()` 与 `queryStream()` 的行数（都是 0）→ **该测试是空断言，掩盖了错误**。 +- 复现：见上（注意必须带表别名前缀，否则解析失败）。 + +**P1-4 关联引用出现在 `IN (SELECT …)` / 标量子查询中被静默丢弃（恒 0 行）** **[已验证]** +- 行号：`executor.ts:1415-1423`（`$in` 分支）与 `1425-1431`（标量分支）都调 `this.executeSelect(subStmt)`（1417），**不传 contextRow**；对比 `$exists` 分支（1351-1353）显式 `bindWhereRefs` 外层行。 +- 现象：`SELECT id FROM u WHERE id IN (SELECT user_id FROM o WHERE o.user_id = u.id)` → `[]`（应为 1,2）；EXISTS 形式（同样的 SQL 结构）能正确返回 1,2。 +- 根因：子查询内 `u.id` 被当作**子查询自身行**的列（`bindColumnRefs` 用子查询行的 contextRow → `undefined`），条件恒 false。 +- 复现：users(1,2,3) / orders(o1→1,o2→1,o3→2)，执行上述 SQL。 + +**P1-5 完全没有三值逻辑：`!=` / `NOT IN` / `NOT LIKE` / `NOT(…)` 把 NULL 行当"真"** **[已验证]** +- 行号：`where-matcher.ts:161-177`（`$eq/$ne/$in/$nin/$like` 全用 JS `===`/`includes`）、`98-101`（`$not` 是布尔取反）、`132-134`（裸值走 `===`） +- 现象（表 (1,'Alice'),(2,'Bob'),(3,NULL)）： + - `WHERE name != 'Alice'` → 2、3（SQL 只应 2） + - `WHERE name NOT IN ('Alice')` / `NOT LIKE 'A%'` / `NOT (name='Alice')` → 同上 + - `WHERE n IN (1, NULL)`（n 为 1、2、NULL）→ 返回 1 和 NULL 行（SQL 只应 1） + - `WHERE n NOT IN (1, NULL)` → 返回 2（SQL 0 行） + - `WHERE name = NULL` → 返回 NULL 行，`!= NULL` → 返回所有非 NULL 行（`= NULL`/`!= NULL` 与 IS NULL/IS NOT NULL 不可区分） +- 根因：没有任何 UNKNOWN 态；NULL 被当作普通值参与 `===`。`$eq: null` 恰好等价于 IS NULL，是"顺带正确"。 +- 复现：上述 6 条。 + +**P1-6 `NOT IN (子查询)` 遇子查询结果含 NULL → 多返回行** **[已验证]** +- 行号：`executor.ts:1419-1423`（原样把第一列值列表塞进 `$nin`）→ `where-matcher.ts:170` +- 现象：users(1,2,3)、orders(o1→'1', o2→NULL)：`SELECT id FROM u WHERE id NOT IN (SELECT user_id FROM o)` → `[2,3]`（SQL 应为 0 行）。 +- 根因：同 P1-5；SQL 中 `x NOT IN (…, NULL)` 永不为真。`$in` 侧（`id IN (SELECT …)`）恰好与 SQL 一致，说明差异纯粹来自 NULL 语义缺失。 + +**P1-7 HAVING 不能引用"未出现在 SELECT 列表里的聚合"** **[已验证]** +- 行号：`executor.ts:628-651`（`executeGroupBy` 只为 `stmt.columns` 里的聚合表达式算值并写入组行）、`365-378`（HAVING 用 `matchWhere` 对组行求值） +- 现象：`SELECT dept FROM e GROUP BY dept HAVING COUNT(*) > 1` → `[]`（应为 Eng、Sales）；`HAVING SUM(salary) > 2000` → `[]`（应为 Eng）。而 `SELECT dept, COUNT(*) AS c … HAVING COUNT(*) > 1` 正常。 +- 根因：HAVING 的键 `'COUNT(*)'`（parser.ts:1058-1067 生成）在组行里不存在 → `matchField(undefined, {$gt:1})` → false；`_aggAliasMap`（626-651）只做"表达式键→别名键"的重命名，不能补算缺失聚合。 +- 复现：employees(id,dept,salary) 5 行，执行上述两条。 + +**P1-8 聚合的 NULL/类型语义：空集/全 NULL 返回 0 而非 NULL；MIN/MAX 走 `Number()` 数值化** **[已验证]** +- 行号：`executor.ts:660-680`（`argCol` 原样取列；`663` 过滤 null；`672` `rawValues.map(Number)`；`675-678` SUM 初值 0、AVG/MIN/MAX 空集返回 0、MIN/MAX 用 `Math.min/max`） +- 现象： + - 空集或全 NULL：`SUM/AVG/MIN/MAX` → `0`（SQL 为 NULL） + - 文本列：`MIN(s)/MAX(s)` over ('9','10') → `9 / 10`（文本序应为 '10' / '9'）；列表含 'abc' 时整列变 `NaN`（JSON 序列化为 `null`） + - `MIN(id)/MAX(id)` 对字符串主键返回数字 + - `AVG(文本列)` → NaN + - 合计：COUNT(col) 跳过 NULL（正确）、COUNT(*) = 行数（正确） +- 根因：聚合只实现了数值语义；`computeAggregate` 返回类型硬编码 `number`（655），没有 NULL 传播、没有"文本聚合 vs 数值聚合"分支。 +- 复现：`SELECT MIN(s), MAX(s) FROM t`（s = '9','10','abc'）。 + +**P1-9 非 JOIN 路径下"带表前缀的聚合参数"恒为 0** **[已验证]** +- 行号：`executor.ts:328-336`（`/^(COUNT|SUM|AVG|MIN|MAX)\(/` 的列原样保留，不剥前缀）→ `662` `r[argCol]`，此时行键是裸列名 +- 现象：`SELECT COUNT(o.id) FROM orders o` → 0（应为 3）；`SELECT SUM(o.amount) FROM orders o` → 0（应为 300）；`COUNT(*)` 正常。 +- 反证：JOIN 路径行键带前缀（447-451），同样的 `COUNT(o.id)` 在 JOIN 查询里是对的 → 路径分叉。 +- 复现：orders(o1,100),(o2,200),(o3,NULL)。 + +**P1-10 JOIN 的 NULL 键：嵌套循环认为 NULL=NULL 成立，哈希连接认为不成立 → 结果取决于右表是否有索引** **[已验证]** +- 行号：`where-matcher.ts:139-150`（`options.$col` 分支 `value === row[col]`，NULL===NULL 为真）用在 `executor.ts:586/602`；哈希路径 `executor.ts:531`（左值滤掉 null/undefined）、`543/553`（`String(v ?? '\0')`） +- 现象（a(a1,NULL),(a2,'x')；b/c 同为 (·,NULL),(·,'x')，区别是 c.k 有索引）： + - `INNER JOIN` on 未索引列 → a1–b1 + a2–b2（SQL 只应 a2–b2） + - `INNER JOIN` on 已索引列 → 仅 a2–c2（正确） + - `LEFT JOIN` on 未索引列 → a1–b1、a2–b2（SQL 应为 a1–NULL、a2–b2） + - `LEFT JOIN` on 已索引列 → a1–NULL、a2–c2（正确） +- 根因：两套连接实现各自解释 NULL；`$col` 比较缺三值逻辑，哈希键用 `'\0'` 哨兵代替 NULL（还可能把 NULL 与字符串 "\0" 混同）。 +- 复现：同一份数据建 3 张表（右表索引与否不同）跑同一条 JOIN。 + +**P1-11 派生表（FROM 子查询）的别名限定：WHERE 恒空、投影出空对象** **[已验证]** +- 行号：`executor.ts:297-307`（非 JOIN 派生路径不加前缀、不剥别名，只在 303-307 对 where 做 `resolveSubqueries` 后 `matchWhere`）；`where-matcher.ts:214-228`（`projectColumns` 的 `key.endsWith('.'+col)` 对 `col='d.age'` 永不成立） +- 现象：`SELECT * FROM (SELECT id, age FROM users) d WHERE d.age > 25` → `[]`（应为 2 行）；`SELECT d.age FROM (SELECT id, age FROM users) d` → `[{},{},{}]`；去掉前缀（`WHERE age > 25`）才正确。 +- 根因：外层 WHERE/投影里的 `d.age` 从未被映射到派生行的裸键；JOIN 分支因为先 `prefixRow(row, stmt.alias ?? '')`（301）才"看起来正常"，但别名缺省时会生成 `.col` 这种坏键。 +- 复现：见上。 + +**P1-12 JOIN 查询里的"未限定列名"静默失效（WHERE 空集 / GROUP BY 并成一组 / ORDER BY 不排序）** **[已验证]** +- 行号：`executor.ts:317-336`（别名剥离只发生在非 JOIN 分支）、`447-451`（JOIN 行键全部带前缀）、`379`（排序按裸键取不到值） +- 现象： + - `SELECT u.id FROM u INNER JOIN o ON u.id=o.user_id WHERE dept = 'Eng'` → `[]`（应为 3 行） + - `SELECT dept, COUNT(*) AS c FROM u INNER JOIN o ON u.id=o.user_id GROUP BY dept` → `[{c:4}]`（应为 Eng=3、Sales=1；所有行落进 `undefined` 组） + - `SELECT users.name FROM users INNER JOIN departments … ORDER BY name DESC` → 顺序未变（静默不排序） + - `SELECT name FROM users JOIN departments …` → 静默取 `users.name`（SQL 应报歧义；`projectColumns` 取第一个 `endsWith('.name')` 的键） +- 根因：列标识在不同路径下分别是"裸名/前缀名"，匹配全靠字符串；JOIN 路径没有做"未限定名→唯一候选列"的解析。 +- 复现：见上。 + +**P1-13 DISTINCT 作用在"原始行"而不是"投影后的行"** **[已验证]** +- 行号：`executor.ts:290-295 + 352`（有 `AS` 别名或 CASE → `plan.columns=['*']`）→ `364`（DISTINCT 在 `383-386` 投影之前） +- 现象：employees(1,Eng),(2,Eng),(3,Sales)：`SELECT DISTINCT dept AS d FROM e` → 3 行（应为 2）；`SELECT DISTINCT g AS k FROM t ORDER BY k DESC` → `[b,a,a]`（应为 b,a）。 +- 根因：去重键用整行 `Object.values(row)`（689），把未被投影的 id 也算进去。 +- 复现：见上（注意 `SELECT DISTINCT dept FROM e`（无别名）因为引擎已投影所以是对的 → 又是路径分叉）。 + +**P1-14 UNION：语句级 ORDER BY/LIMIT 挂到最后一个 SELECT 上；列数不校验；空左操作数改变结果列名** **[已验证]** +- 行号：`sql/parser.ts:366-388 + 394-409`（`parseSelect` 先吃掉 ORDER BY/LIMIT，再在 386 判 UNION，于是尾部的 ORDER BY/LIMIT 属于**右侧** SELECT）；`executor.ts:153-200`（`executeSelectUnion` 全程不看 orderBy/limit/offset，也不做 maxRows 保护）；`158`（`leftCols` 取自左结果第一行）、`192-200`（`projectUnionRow` 按位置映射、多余列丢弃） +- 现象： + - AST 实证：`SELECT v FROM t1 UNION SELECT v FROM t2 ORDER BY v LIMIT 2` → `right = {orderBy:[v], limit:2}`、`left` 无排序无限制 + - `SELECT v FROM t1 UNION SELECT v FROM t2 ORDER BY v` → `[c,a,b,d]`（乱序）；`… LIMIT 2` → 4 行；`UNION ALL … LIMIT 2` → 4 行 + - `SELECT v FROM t1 UNION SELECT v, id FROM t2` → 不报错（SQL 应报列数不匹配） + - 左侧为空时 `leftCols=[]` → 右侧行保持自己的列名：`SELECT v FROM t1 WHERE id<'0' UNION SELECT amount FROM t2` → `[{amount:42}]`（左侧非空时为 `[{v:'x'},{v:42}]`） +- 根因：UNION 没有自己的 ORDER BY/LIMIT 承载结构（ast.ts:153-161 的 `SelectUnionStatement` 无 orderBy/limit 字段），执行器也不对合并集合做收尾。 +- 复现：见上。 + +**P1-15 `SELECT <数字常量>` 投影出空对象** **[已验证]** +- 行号：`sql/parser.ts:1044-1049`（数字常量作为列文本 '1'）→ `executor.ts:1017-1042`（`projectRow` 只处理 `*` / CASE / `AS` / 字符串常量，没有数字分支）→ `1046` `projectColumns` 找不到 '1' 键 → `{}` +- 现象：`SELECT 1 FROM t` → `[{},{}]`；`SELECT 1 AS one FROM t` → `[{}]`（别名分支取 `row['1']` → undefined）；`SELECT id, 1 AS one FROM t` → `[{id:'1'},{id:'2'}]`（常量列消失）。 +- 备注：EXISTS 子查询只关心行数所以掩盖了这个问题；注释（parser.ts:1044）明确把它当特性。 +- 复现：见上。 + +**P1-16 标量子查询：多行不报错（静默取第一行）、空结果被当 NULL 值匹配** **[已验证]** +- 行号：`executor.ts:1425-1431` +- 现象：`SELECT id FROM u WHERE age = (SELECT age FROM u)`（3 行年龄）→ 返回 id=1（SQL 应报 "subquery returned more than one row"）；`age > (SELECT age FROM u)` → 取第一行年龄比较；`age = (SELECT age FROM u WHERE id='nope')`（空）→ `$eq: null` → 返回 age IS NULL 的行（SQL 0 行）。 +- 根因：标量语义被实现为"第一行第一列/空则 null"，没有基数检查，也没有 UNKNOWN 语义。 +- 复现：见上。 + +**P1-17 AND/OR 无优先级（左结合）** **[已验证]** +- 行号：`sql/parser.ts:780-797`（`while (AND|OR)` 逐个子条件左折，不区分优先级） +- 现象：AST 实证 `a = 1 OR b = 1 AND id = 'r2'` → `{$and:[{$or:[a,b]}, {id:'r2'}]}`（SQL 应为 `a OR (b AND id)`）；数据 r1(a=1,b=0)、r2(a=0,b=1)、r3(a=0,b=0) 时返回 `[r2]`（应为 r1、r2）。 +- 根因：`parseCondition` 缺少 `parseOr → parseAnd → parseSimple` 分层。 +- 复现：见上。影响所有引擎与所有语句（WHERE/ON/HAVING 共用 `parseCondition`）。 + +**P1-18 GROUP BY 下"带别名的非聚合列"被静默改名或整个丢弃** **[已验证]** +- 行号：`executor.ts:631-648`（`colExpr` 与 `stmt.groupBy` 做**字符串全等**比较；不匹配就走 646 的 `aggregated[colExpr] = groupRows[0][colExpr]`） +- 现象： + - `SELECT dept AS d, COUNT(*) AS c FROM e GROUP BY dept` → `[{dept:'Eng',c:2}]`（别名 d 丢失，键变成 dept） + - `SELECT salary AS s, COUNT(*) AS c FROM e GROUP BY dept` → s 列**整列消失**（值为 undefined，JSON 序列化时被抹掉，无报错） + - `ORDER BY d`（分组列的别名）静默不排序 +- 根因：组行的键空间是"SELECT 列表字符串 + groupBy 字符串"的拼接，别名/前缀/空白只要不一致就落到 first-row 分支；`ORDER BY` 在投影前按裸键取值（379）。 +- 复现：见上。 + +**P1-19 `maxRowsPerQuery` 会静默截断 `INSERT … SELECT` 的源数据（静默丢数据）** **[已验证]** +- 行号：`executor.ts:707`（`executeInsert` 用 `executeSelectPart` 取源行）→ `396-398`（`maxRowsPerQuery` 截断在 `executeSelect` 内） +- 现象：`maxRowsPerQuery: 2` 时，`INSERT INTO b SELECT id FROM a`（a 有 4 行）**只插入 2 行且不报错**。 +- 根因：行数上限保护放在"查询结果"层，而读路径同时被写语句复用，没有区分"面向用户的结果集"与"内部行源"。 +- 复现：配置 maxRowsPerQuery=2，见上。 + +--- + +### P2 — 边界与健壮性 + +| # | 文件:行号 | 现象 / 根因 | 状态 | +|---|---|---|---| +| P2-1 | `executor.ts:645-647` | `SELECT dept, salary FROM e GROUP BY dept` 返回每组**第一行**的 salary（MySQL 式 ANY_VALUE），标准 SQL 应报错；结果依赖扫描顺序 → 引擎相关 | [已验证] | +| P2-2 | `executor.ts:383-386 + 447-451` | JOIN 查询 `SELECT *` 返回 `users.id`/`departments.name` 这类**带前缀列名**，与单表 `SELECT *` 的裸列名不一致 | [已验证] | +| P2-3 | `where-matcher.ts:220-225` | 未限定列名在 JOIN 中静默取"第一个后缀匹配"的列（歧义应报错） | [已验证] | +| P2-4 | `executor.ts:591-595, 602-609` | LEFT/RIGHT 的 NULL 补行用**第一行的键集**（`rightRows[0]`/`leftRows[0]`）构造，键集异质（ALTER ADD/DROP 后、空表）时补行缺列；RIGHT 未匹配行被追加在结果末尾（顺序非 SQL 语义） | [读码确认] | +| P2-5 | `executor.ts:1169-1174` + `766-777` | `hasCorrelatedRefs` 把**任何** `$exists` 都判为关联 → `DELETE FROM t WHERE EXISTS (SELECT 1 FROM u)`（完全不相关）抛 `NOT_SUPPORTED`；同时非关联 EXISTS 被逐行重复执行（见 P3-2） | [已验证] | +| P2-6 | `builder.ts:105-112` + `memory.ts:192-210` | QueryBuilder 非 JOIN 路径直通 `engine.find`，**find 没有 `containsUnresolvedSubqueries` 防护**（只有 update/delete 有）→ `.where({id:{$eq:{$col:'v'}}})` 静默返回 `[]` | [已验证] | +| P2-7 | `executor.ts:305,317,322-336,367,375,440,651` | 就地改写调用方的 AST（where/columns/orderBy/groupBy），并在 `stmt` 上挂 `_aggAliasMap` 侧信道 → 同一 AST 二次执行（`toAST()` 复用、EXPLAIN + 执行）语义漂移 | [读码确认] | +| P2-8 | `engine/aria/index.ts:1223,2028` vs `1998,2005` | Aria 主键类型随访问路径翻转：全表/范围扫描 `key.slice()` → 字符串；`$eq` 快速路径用查询字面量原类型 → 同一列在 `SELECT *` 与 `WHERE id = 3` 下分别是 `'3'` 和 `3`；memory/disk/hybrid 恒为原类型 | [已验证] | +| P2-9 | 无 SQL 层保证 | 无 ORDER BY 时行序引擎相关（memory/disk/hybrid 插入序 vs aria 主键序）→ `LIMIT/OFFSET` 选出的行引擎间不一致；README"已知限制"未提 | [已验证] | +| P2-10 | `where-matcher.ts:18-28` | `LIKE` 编译为正则带 `i` 标志 → **大小写不敏感**（'C%' 命中 'c'）；与 PostgreSQL 不同、与 SQLite ASCII 行为相近，但没有任何文档说明 | [已验证] | +| P2-11 | `executor.ts:665-670` | `COUNT(DISTINCT *)` 在第 666 行就 `return rows.length`，DISTINCT 被忽略（SQL 应语法报错） | [已验证] | +| P2-12 | `executor.ts:668` | `COUNT(DISTINCT col)` 用 `String(v)` 去重（无类型前缀）→ `1` 与 `'1'`、`true` 与 `'true'` 合并；与 v0.7.4 专门引入 `encodeGroupKey` 的理由自相矛盾 | [读码确认] | +| P2-13 | `core.ts:218-241` | 分号多语句**逐条执行、无事务**，失败时前面的语句已提交（实测 `INSERT; INSERT` 第二条 DUPLICATE_KEY，第一条留存）；返回值只有最后一条结果 | [已验证] | +| P2-14 | `executor.ts:829-841` | ALTER DROP COLUMN 的通用路径靠"`engine.find` 返回行引用，直接 `delete row[col]`"清理数据；注释自认依赖 Memory 的引用语义 → 换引擎即静默失效（Aria 走引擎 alterTable 才没事） | [读码确认] | +| P2-15 | `sql/parser.ts:828-833` | `(CASE … END) = 'x'` PARSE_ERROR（括号分支返回内层条件后不再继续解析运算符）；`ORDER BY COUNT(*)`、`(SELECT …) > 0`、任何算术表达式（`a+1`、`n/0`）都 PARSE_ERROR → executor 里为 CASE/表达式准备的分支（1010-1063、1240-1266）只能被很窄的语法触达 | [已验证] | +| P2-16 | `executor.ts:1070-1072` | `_hasAggregateColumn` 要求列文本**以聚合名开头** → `SELECT CASE WHEN COUNT(*) > 1 THEN …` 不触发聚合路径；组内 `evaluateCase` 把 `COUNT(*)` 当列引用（`resolveCaseValue` 95-97）→ null | [读码确认] | +| P2-17 | `executor.ts:95-97` | CASE 的 THEN/条件里的列引用按**精确键**取（`row[v]`）→ JOIN 场景下未限定列取不到（`THEN id` 在带前缀行里是 undefined → null） | [读码确认] | +| P2-18 | `executor.ts:1269-1288` | `caseConditionMatches` 对未知操作符 `default: break`（静默视为满足），与 v0.7.2 让 `matchOperator` 抛 `QUERY_ERROR` 的硬化方向不一致 | [读码确认] | + +--- + +### P3 — 性能 + +| # | 文件:行号 | 问题 | +|---|---|---| +| P3-1 | `executor.ts:429`、`569-612` | JOIN 非哈希时**每张右表整表物化**再嵌套循环，每对候选都 `{...l,...r}` 造对象（585）；RIGHT JOIN 再全扫一遍右表（598-610）→ O(N·M) 两遍 | +| P3-2 | `executor.ts:1226-1238` | `filterCorrelated` 外层**每行执行一次子查询**（含完全不相关的 EXISTS，因 1169-1174 的过宽判定），无缓存/去相关 | +| P3-3 | `executor.ts:379` + `388-390` | ORDER BY 别名场景排序两次，第一次作用在投影前的行上（键全 undefined）纯属浪费 | +| P3-4 | `memory.ts:195-208`、`aria/index.ts:686-704` | 同样的 order/limit/project 在引擎里做一遍、executor 再做一遍（复制 + 排序 + 切片 ×2） | +| P3-5 | `where-matcher.ts:16-28` | `likeCache` 是**模块级无上界 Map**，动态（用户输入）LIKE 模式持续增长 → 内存泄漏 | +| P3-6 | `executor.ts:211-215` | `EXPLAIN SELECT` **真执行查询**；`estimatedRows` 就是真实行数；`EXPLAIN` 还会跑 `resolveWriteWhere`（218-223）触发子查询执行 | +| P3-7 | `executor.ts:153-200, 297-307`；`core.ts:307-324` | UNION / 派生表 / 任何带 JOIN、ORDER BY、DISTINCT、聚合的查询都全量物化；`queryStream` 只对最简 SELECT 走真流式 | +| P3-8 | `executor.ts:677-678` | `Math.min(...arr)` 展开实参：O(n) 栈 + 崩溃（P0-1） | +| P3-9 | `executor.ts:1010-1063`、`59-83` | 投影表达式**逐行重新正则解析**（`parseCaseExpression` 每行每列一次）、`projectColumns` 未命中时对每行键做 O(cols×keys) 扫描；无预编译投影/表达式 | +| P3-10 | `executor.ts:31-39, 37` | `encodeGroupKey` 对 object 值 `JSON.stringify`（每行每值），分组/去重键无长度前缀 | +| P3-11 | `executor.ts:531-538` | 哈希连接把所有左表探测值（可能百万级）一次性放进单个 `$in` 查询，无分块 | +| P3-12 | `executor.ts:457-471` | WHERE 下推只覆盖"主表别名前缀 + 普通等值"，其余（未限定列、$and 内部非等值、JOIN 表条件）全部在内存里逐行过滤 | + +--- + +### 疑似（未实跑，读码推断） + +- **S-1 分组/去重键可被伪造**：`encodeGroupKey` 各列值用 `'\x1f'` 连接且无长度前缀/转义（`executor.ts:621/689/170/178`），字符串值自身含 `'\x1f'` 时不同列组合可撞键（如 `('a\x1fss','b')` 与 `('a','ss\x1fb')`）→ DISTINCT/GROUP BY/UNION 误合并。哈希连接键（543/553）与 `$in` 探测用 `'\0'` 哨兵，同类问题且会把 NULL 与真实 `"\0"` 混同。 +- **S-2 json 列分组**：`JSON.stringify` 的对象键顺序不同 → 逻辑相等的对象落入不同组（37）。 +- **S-3 行键顺序敏感**：DISTINCT/UNION 用 `Object.values(row)`（689/170），同值但键序不同的行（ALTER ADD/DROP 后、异质行）不会去重。 +- **S-4 Aria 索引键 `String()` 归一**：`1`/`'1'`、`true`/`'true'` 在二级索引里同一键（aria/index.ts:2045/2062）；当前只造成多余候选（后续 `matchWhere` 会过滤），但语义上是类型混同。 +- **S-5 `hasSelectAlias` 正则误判**：`/\s+AS\s+\w+$/i`（executor.ts:295）对含 " AS " 的列文本可能误判（已实测字符串常量 `'a AS b'` 不会误判，因为结尾是引号；但其它未加引号文本未穷举）。 +- **S-6 混合类型排序**：`compare` 回退 `localeCompare(String(a),String(b))`（where-matcher.ts:207）→ 数字/字符串混合列按字典序、且依赖 locale。 +- **S-7 哈希连接列对方向**：`keyIsLeft` 只看 `mainAlias` 前缀（executor.ts:508-512），第二个 JOIN 的 ON 若引用前一个 JOIN 表，`pairs` 会左右颠倒；目前通常因"取值列表为空"回退嵌套循环（531-532），但这是巧合而非保证。 +- **S-8 `$like` 未处理 `\` 转义与 `%`/`_` 字面量**（where-matcher.ts:21-24 先转义正则字符再替换通配符；无 ESCAPE 支持），且正则无回溯保护 → 恶意模式（如 `%a%a%a%…`）可能触发灾难性回溯。 + +--- + +## 3. 性能议题（汇总） + +1. **JOIN 是"整表物化 + 嵌套循环"**（P3-1）：右表无条件全量读入（executor.ts:429），只有"ON 为纯等值 + 右表有索引"时才退化为一次 `$in` 探测的哈希连接（480-566）。没有块嵌套、没有排序合并、没有把 WHERE 下推到连接前（除了主表别名等值那一种）。 +2. **完全不做投影下推**：`needsRawRows || hasSelectAlias` 时 `plan.columns=['*']`（352），GROUP BY/聚合路径也强制 `['*']`（340/351）→ 引擎把整行读出来再由 JS 投影/分组。列存式裁剪无从谈起。 +3. **LIMIT 下推错位**（P1-2）：本该减少工作量的下推反而造成错误结果；正确做法是只在"无 DISTINCT/GROUP BY/ORDER BY 别名"时下推。 +4. **重复劳动 ×2**：引擎与 executor 各排一次序、各切一次片、各投影一次（P3-4、P3-3）。 +5. **关联子查询逐行执行**（P3-2）：N 行 = N 次子查询（每次都是一次完整 SELECT），且**不相关的 EXISTS 也被当成相关**。 +6. **全量物化点**：UNION、派生表、ORDER BY 别名、DISTINCT、GROUP BY、JOIN 全部先物化再处理（P3-7）；`queryStream` 只在最简 SELECT 上真流式。 +7. **无上界增长**：`likeCache`（P3-5）、哈希连接 `$in` 值数组（P3-11）、分组 Map（每行都进 `groups`，输出组数无上限）、`maxRowsPerQuery` 是唯一的结果集上限（且会误伤 INSERT…SELECT，P1-19）。 +8. **逐行重解析**：表达式/别名/CASE 的文本解析在行循环里（P3-9）；`executor.ts:59` 的 CASE 正则每个 CASE 列每行跑一次，且用 `[\s\S]*?` 惰性匹配 + `exec` 循环。 +9. **EXPLAIN 变成真执行**（P3-6）：成本翻倍，且给不出真实估算（`estimatedRows` = 实际行数）。 +10. **错误路径上的性能悬崖**：P0-1 的 `Math.min(...)` 同时也是 O(n) 实参构造；索引命中后仍要全条件 `matchWhere`（memory.ts:197-199 / aria:687-689），等值索引查出的行本可跳过该列比较。 + +--- + +## 4. 系统性观察：为什么这一层反复出 bug，哪里一刀能砍掉一整类 + +1. **同一语义有两份实现，且按"查询长什么样"分流** + - 有 JOIN → executor；无 JOIN → 引擎（builder.ts:99-113 与 executor.ts:311-355）。 + - 有 `AS`/CASE → 引擎不投影、executor 投影；否则引擎投影（executor.ts:290-295/352）。 + - ORDER BY 用别名 → 清空 plan 的 order/limit；否则把 limit 下推（353）。 + - 这些分流处**每一个**都对应上面的一个 P1（P1-1/2/9/12/13 全是"同一个 SQL 换条路径就对"）。LIMIT 下推是典型：JOIN 路径对、单表路径错。 + - **一刀**：把"扫描→过滤→连接→分组→去重→投影→排序→截断"写成一条固定管线，且 **limit/offset/projection 只在一个地方执行**；引擎退化为"只提供带索引的行迭代器 + WHERE 匹配"。 +2. **没有 NULL / 三值逻辑模型** + - `where-matcher` 用 JS `===`，哈希连接用 `String(v ?? '\0')`，`$in/$nin` 用 `includes`，分组键另起一套 `encodeGroupKey`，`COUNT(DISTINCT)` 又用 `String(v)`。P1-5/6/10 以及 S-1/S-4 都是同一根因的不同外显。 + - **一刀**：引入唯一的 `sqlEquals/sqlCompare`（三态：TRUE/FALSE/UNKNOWN）+ 唯一的值编码（含 NULL 与类型）。所有比较、IN/NOT IN、JOIN 键、分组键、DISTINCT 键都调它 → NULL 类 bug 整类消失。 +3. **列/表达式身份是"字符串"，没有绑定阶段** + - 列是文本：`'dept AS d'`、`'COUNT(o.id)'`、`'CASE … END AS k'`；于是别名要在 6 处正则里再解析（295/633/977/1017/1027/1079），GROUP BY 靠字符串全等比较（645），HAVING 靠字符串映射（369-376），表前缀靠 `startsWith` 剥（1149-1156）。P1-9/18、P2-3/16/17 都源于此。 + - **一刀**：解析期把列解析成 `{table?, column|expr, alias}` 并在编译期绑定到输出序号；GROUP BY/ORDER BY/HAVING 全部按"列序号"而非字符串对齐。 +4. **行编码是"临时约定的键字符串"** + - JOIN 前缀键（447-451）、裸键、`undefined` vs `null`、`Object.values` 顺序、引擎投不投影 —— 全都会改变分组/去重/排序结果（P1-12/13、P2-4、S-3）。 + - **一刀**：行 = 定长元组 + 列清单（schema of the projection），投影/去重/排序按**位置**进行；"前缀"只存在于连接阶段的符号表里，不进入结果行。 +5. **关联子查询靠"语法嗅探 + 特殊通道"** + - `hasCorrelatedRefs`（1159-1181）是纯文本检测，命中就把整条 WHERE 丢进逐行路径；而 `$exists` 与 `$in`/标量走了两条不同的执行分支（1351-1356 vs 1417），其中一条忘了传外层行 → P1-4；过宽判定 → P2-5/P3-2；`stripCorrelatedExists`（1205-1223）想"先粗筛再精筛"却漏了 `$col` → P1-3。 + - **一刀**：统一的表达式求值器携带 `outer row` 参数（子查询执行时传入），WHERE 的求值=对每行调用同一函数；不需要"是否相关"的预判，也就没有漏传上下文/粗筛过滤光的问题。 +6. **SQL 子句顺序没有被编码** + - 代码里的顺序是"聚合→分组→DISTINCT→HAVING→排序→投影→再排序→截断"，而 SQL 是 FROM→WHERE→GROUP→HAVING→SELECT→DISTINCT→ORDER→LIMIT。HAVING 在投影后求值导致 P1-7/18，DISTINCT 在投影前导致 P1-13，LIMIT 下推到扫描导致 P1-2。 + - **一刀**：把上面那条标准顺序写成显式的 stage 列表（每个 stage 有明确的输入/输出列集），任何新特性只需插到正确位置。 +7. **测试固化的是"长度/不抛错"而不是值** + - `tests/join.test.ts:57-99` 只断言行数（注释里甚至写 "column projection may vary"）；`tests/v073-fixes.test.ts:267-278` 比较两条同样错的路径；`groupby.test.ts` 只测 HAVING 引用了 SELECT 里已有的聚合。 + - 结果：P1-3/7/12/13/14 这类"结果错但不崩溃"的语义长期存活，且每次 CHANGELOG 的"P1 修复"都只在某一条路径上打补丁（v0.7.4 修了 queryStream/写路径的子查询，却留下 P1-4 的关联 IN）。 + - **建议**：补"值级 golden 测试"，重点覆盖 NULL/三值逻辑、别名与未限定列、UNION + ORDER/LIMIT、LIMIT/OFFSET（含 OFFSET>0 与左侧为空的 UNION）、空集聚合、以及**同一 SQL 在 join/非 join、memory/aria 两种路径下的结果一致性**。 + +### 优先级建议（若要排修复顺序） + +1. P0-1（崩）→ P1-19（静默丢数据）→ P1-1（OFFSET 结果错）→ P1-5/6（NULL 三值逻辑）→ P1-4/3（关联子查询静默空）→ P1-17（AND/OR 优先级，影响面最大且最易修）→ P1-7/8/13/14/18（聚合与集合语义）→ P1-9/11/12（路径分叉）→ P1-15/16。 +2. 结构性投入（收益最大）：统一值比较/编码（第 2 条）+ 列绑定（第 3 条）+ 单条执行管线（第 1、6 条）。这三件事落地后，本报告 P1 中的绝大多数会作为"整类"消失，而不是逐条打补丁。 diff --git a/AUDIT-storage-engines-v0.7.4.md b/AUDIT-storage-engines-v0.7.4.md new file mode 100644 index 0000000..b9a0a9e --- /dev/null +++ b/AUDIT-storage-engines-v0.7.4.md @@ -0,0 +1,243 @@ +# MetonaSqlark v0.7.4 存储引擎审计报告 +> 范围：`MemoryEngine` / `KVStore`（自研事务 KV）/ `KVStoreEngine`（KV 包装）/ `HybridEngine`（write-through） +> 方法：逐行精读 8 个源文件 + 10 个测试文件 + CHANGELOG(1-200) + README「存储引擎」；对可疑项编写临时 jest 用例注入故障复现（全部用例已删除，仓库无残留）。文中标注 **[已复现]** = 可执行实验证实；**[读码确认]** = 代码路径确定但未注入实验；**[疑似]** = 推理所得、未完全证实。 + +--- + +## 1. 架构概览 + +### 1.1 MemoryEngine（`src/engine/memory.ts`） + +**数据结构（memory.ts:15-33）** +- `tables: Map>` —— 行存储，PK 直接由 `String(validatedRow[pkColumn])` 得到（memory.ts:163/177），**没有独立的主键索引结构**：PK map 就是行存储本身。 +- `indexes: Map>>>` —— 二级哈希索引；只有 `colDef.index || colDef.unique` 的列在 `createTable` 时建桶（memory.ts:81-85）。索引只记录非 null 值（memory.ts:780、793）。 +- `schemas: Map`（createTable 时深拷贝列定义，memory.ts:75-79，防止 Hybrid 双引擎共享 schema 对象）。 +- `uniqueIndexCols: Set<"table:col">` —— 仅标记 `CREATE UNIQUE INDEX` 来源的 unique（memory.ts:26、593），供 `dropIndex` 区分「建表约束」与「索引来源约束」（memory.ts:613-623）。 +- `metaStore`、`snapshot`（事务快照，memory.ts:29-33）。 + +**查找路径（memory.ts:192-210, 725-772）**：`find` 先 `tryIndexLookup`：递归展开顶层 `$and`（memory.ts:734-745）收集等值条件 → 命中某列索引则用 `colIndex.get(value)` 取 pk 集合回表（memory.ts:763-767）；**索引未命中直接 `return []`（memory.ts:768）——正确性完全依赖索引与行一致**；null/undefined 条件跳过索引回退全表（memory.ts:759）。随后仍用完整 `matchWhere` 过滤（子集语义安全）、`applyOrderBy`、`slice(offset,limit)`、`projectColumns`。`findStream`（memory.ts:213-233）单次迭代不物化，但**完全忽略 `query.orderBy`**。 + +**insert（memory.ts:146-183）**：v0.7.3 两阶段。阶段 1 逐行 `validateRow` + 批内 PK `Set` 互查（memory.ts:165）+ `checkInsertUniqueness`（批内 Set + 索引查，memory.ts:309-341）；阶段 2 落 row + `updateIndexes`。 + +**update（memory.ts:235-302）**：`stripUndefinedUpdates` → 未知列报错（254-258）→ 未解析子查询报错（245-250）→ 阶段 1 逐行匹配/校验/唯一预检/**新主键撞已有主键检查**（memory.ts:274）→ 阶段 1b `checkUpdateRestrict`（RESTRICT 与 SET NULL+required 整体拒绝，memory.ts:391-421）→ 阶段 2 先 `removeIndexEntries` 再（主键变更时）`applyUpdateCascade`、`table.delete(old)`、`table.set(new)`、`updateIndexes`。 + +**delete（memory.ts:450-486）**：先扫出全部待删行 → 对每行 `checkCascadeRestrict` 递归预检（memory.ts:492-529）→ 通过后才 `removeIndexEntries` + `cascadeDelete`（memory.ts:810-878）→ 最后删父行。返回 `toDelete.length + cascadeCount`。 + +**事务（memory.ts:633-653）**：`beginTransaction` 深拷贝 tables（浅拷贝行对象 `{...iv}`，memory.ts:661）、浅拷贝 schemas（`new Map(this.schemas)`，memory.ts:638）、深拷贝 indexes；`rollback` 直接换回三个 Map；`commit` 只丢弃快照。**没有写锁、没有快照隔离**：事务期间任何非事务写入直接落到同一份 live Map 上。 + +**外键级联**：`checkCascadeRestrict`（预检）与 `cascadeDelete`（执行）都在表循环里 `if (refTableName === tableName) continue;`（memory.ts:498、822），即**自引用外键被整体跳过**；`applyUpdateCascade` 只处理直接引用被改表的列（memory.ts:430-448），不递归。 + +### 1.2 KVStore（`src/engine/kvstore/*`） + +**磁盘格式** +- 键空间：`__kv_log` / `__kv_snapshot` / `__kv_meta`（index.ts:32-34）。 +- **日志记录**（log.ts:9-18, 47-92）：`[recordLen u32][seq u32][entryCount u32] (每条 entry: [op u8][keyLen][key][valueLen][value]) [crc u32]`，大端，`crc32` 覆盖除 CRC 外全部字节；`recordLen` 含自身不含 CRC（log.ts:79）。操作码 PUT=1 / DELETE=2 / APPEND=3（log.ts:23-28）。**一条记录 = 一个原子事务**（putMany/deleteMany/writeBatch 都编码成单条记录，index.ts:209-242）。 +- **快照**（snapshot.ts:8-13, 29-59）：`[magic "KVSN"][seq u32][entryCount] (keyLen/key/valueLen/value)* [crc]`；`seq` 是内嵌日志水位。 +- **介质抽象**（`src/engine/aria/store/backend.ts:13-48`）：`IStorageBackend`（open/close/read/write/append?/writeMany/delete/deleteMany/listKeys/exists/clear）。浏览器走 `OPFSBackend`（每 key 一个文件，`write` 用 createWritable COW，`append` 用 keepExistingData+seek 到 `existing.size`，opfs_backend.ts:84-113）；Node/测试走 `SharedMemoryBackend`（模块级 registry 跨实例共享、close 不清数据，shared_memory_medium.ts:15-43），默认选择逻辑在 index.ts:44-50。 +- **内存索引**：`index: Map`（index.ts:58）是唯一读路径，`get/size/listKeys` 全部 O(1)（index.ts:177-195）。 + +**恢复流程（index.ts:85-142）**：读快照 → `decodeSnapshot` 失败则置空索引并从 0 重放 → 读日志 → `parseLogRecords` 顺序解析，`record.seq <= snapshotSeq` 跳过（幂等），否则 `applyRecord` 并推进 `this.seq` → 命中损坏记录（长度越界/CRC 失败/entry 越界）回调返回 true 停止扫描 → **调用 `truncateLog()` 把整条日志写成 0 字节**（index.ts:135-138 + 394-399）。`__kv_meta` 在 checkpoint 时写（index.ts:275-276）但**恢复时从不读取**（v0.6.1 起水位只信快照内嵌 seq，index.ts:113-118）。 + +**写入与 checkpoint（index.ts:334-391, 261-280）**：所有写经 `enqueue` 串行队列（index.ts:327-331）→ `seq++` → `medium.append`（真追加，否则 read+拼+write 回退，index.ts:344-356）→ 成功后更新内存索引与 `logBytes`；失败 `seq--`、记 `lastBackgroundError` 并抛 `KV_LOG_ERROR`（内存不更新）。`checkpoint` = 写快照 → 写 meta → 截断日志；`appendRecord` 内还有一条**按字节阈值的自动 checkpoint**（index.ts:385-390，默认 16MB，index.ts:37），**这段不在 try/catch 内**。 + +### 1.3 KVStoreEngine（`src/engine/kvstore_engine.ts`） + +**三层缓存**：介质文件 → `KVStore.index`（ArrayBuffer 权威视图）→ `MemoryEngine`（解码后的行 + 二级索引）。**读全部走 MemoryEngine**（kvstore_engine.ts:292-300, 419-422），介质只在 open/checkpoint 碰。 + +**键布局**：`__schema`（全部表 schema 的 JSON 一次写全）、`__meta:{key}`、`t:{table}:{pk}`（kvstore_engine.ts:28-29, 65-71）。 + +**open（kvstore_engine.ts:75-123）**：`kv.open` → `memory.open` → 解析 `__schema`（JSON 失败抛 `KV_SCHEMA_ERROR`）→ 逐 key 解析行名（`key.indexOf(':', 2)` 取第一个冒号，kvstore_engine.ts:99-101）→ 表存在则 `memory.insert(table,[row])`，**异常被 catch 静默吞掉**（kvstore_engine.ts:103-108）→ 之后一段「重建二级索引」循环（kvstore_engine.ts:111-120）实际是死代码（`createTable` 已建桶且 `createIndex` 见 `colDef.index/unique` 立即 return，memory.ts:562）。`this.opened = true` 在**最后**才置位（kvstore_engine.ts:122）。 + +**写入（非事务）**：insert = memory 先行 + `putMany` 持久化 **memory 中的 validated 行**（kvstore_engine.ts:283-288）；update = 先 `collectMatchingPks` 预取受影响主键（kvstore_engine.ts:316）→ `memory.update` → 主键变更走 `affectedTables` 传递闭包 + `collectTableDiff` 整表 diff，普通更新走「单次全表扫描 + 受影响集合过滤 + 剩余主键删除」（kvstore_engine.ts:345-380）；delete = 预取主键 + memory.delete + 本级表按主键删 + 级联表整表 diff，合并成一次 `writeBatch`（kvstore_engine.ts:406-415）。 + +**事务**：`beginTransaction` = memory 快照 + 复位 4 个 tx 集合（kvstore_engine.ts:476-485）；写入路径按 `txActive` 分叉，把变更记入 `txChanges`（行级 put/delete）或降级为 `txFullTables`（主键变更/级联影响表）或 `txClearedTables`（事务内 clear）；`commitTransaction` 把这些合并成 **一次** `kv.writeBatch`，随后**单独** `persistSchema`（kvstore_engine.ts:545-549），最后 `memory.commitTransaction`；`rollbackTransaction` 只回滚内存与集合（kvstore_engine.ts:561-571）。`setMeta` 是直写 `kv.put('__meta:*')`（kvstore_engine.ts:181-183），与事务无关。 + +### 1.4 HybridEngine（`src/hybrid/index.ts`） + +`memoryEngine: MemoryEngine` + `diskEngine: KVStoreEngine`（hybrid/index.ts:30-35）。读全部走内存（222-225）；写 = 内存先行、磁盘 write-through（insert 211-220 / update 232-241 / delete 243-252 / clear 258-265 / DDL 141-189）；磁盘失败回调 `recoverMemoryAfterDiskError`：`reloadMemoryFromDisk()` 把内存对齐磁盘后重抛原错误（hybrid/index.ts:199-209）。`reloadMemoryFromDisk`（hybrid/index.ts:56-85）= 关/开内存引擎 → `disk.reload()` → 遍历磁盘表 `createTable` + `find` 全表 + `insert` 回灌，**单表回灌失败只 `console.warn`**（79-82）。事务 = 双引擎 begin（293-303，磁盘失败补偿回滚内存）/ commit（磁盘先、内存后，内存失败抛 `TX_COMMIT_ERROR` 且磁盘已提交，305-319）/ rollback（内存先、磁盘后，321-324）。 + +### 1.5 语义对照（同为「关系语义」的四份实现） + +| 语义 | Memory | KVStore/KVStoreEngine | Hybrid | Aria（对照） | +|---|---|---|---|---| +| 行/索引 | PK=行 Map；col→Set\ | 复用 Memory + `t:table:pk` 键 | 复用 Memory ×2 | LSM 二级索引 | +| 约束校验 | 自带 `validateRow/checkType`（**无 maxLength/min/max**，memory.ts:713-722） | 复用 Memory | 复用 Memory | 共享 `checkFieldType`（含 maxLength/min/max，aria/index.ts:1672） | +| 唯一 | 建表标记 + `uniqueIndexCols` | schema 持久化后再由 createTable 建桶 | 双份 | 自有重建 | +| 事务内 DDL | ALTER/CREATE/DROP INDEX 拒绝（memory.ts:114/552/599），create/dropTable 可回滚 | ALTER/CREATE/DROP INDEX 拒绝（kvstore_engine.ts:236/442/459），create/dropTable 随 commit | 委托两侧 | ALTER 拒绝 | +| 事务原子性 | 快照交换 | 内存快照 + 单条日志批 + **schema 另写** | 双引擎 | MVCC + WAL | +| 失败中途 | 语句级两阶段；级联两阶段 | 内存先行，落盘失败回滚不了内存 | 重载内存对齐 | WAL 领先内存 | +| 级联影响面 | 直接引用表（自引用被跳过、ON UPDATE 只一层） | `affectedTables` 传递闭包（整表 diff） | 委托 | 自有实现 | + +--- + +## 2. 缺陷清单 + +### P0 — 静默丢数据 / 破坏崩溃恢复 + +**P0-1　单条 UPDATE 把多行改到同一新主键 → 静默覆盖丢行** **[已复现]** +- 位置：`src/engine/memory.ts:274`（阶段 1 只检查 `table.has(newPk)`）、`memory.ts:289-300`（阶段 2 直接 `set`）。 +- 现象：`UPDATE t SET id='X'`（匹配 2 行）返回 affected=2，但表中只剩 1 行；SQL 路径与引擎路径一致。 +- 根因：阶段 1 只与「语句执行前的表」比对，批内新主键互查缺失；阶段 2 逐行 `table.delete(old); table.set(new, updated)`，后者覆盖前者的成果。`primaryKey: true` 不隐含 `unique: true`，`checkUpdateUniqueness`（memory.ts:348-385）只遍历 `colDef.unique` 列，兜不住。 +- 复现：2 行表 → `engine.update('t',{table:'t'},{id:'X'})` → `find` 返回 1 行。（INSERT 路径 v0.7.3 已做批内 PK `Set` 互查，UPDATE 漏了。） + +**P0-2　唯一约束永久失效 → 重启静默丢行（组合链）** **[已复现]** +- 位置：`memory.ts:562`（`if (colDef.index || colDef.unique) return;`）、`memory.ts:122-127`（ALTER ADD 只写 `schema.columns`，**不建索引桶**）、`memory.ts:316-339`（唯一预检依赖 `tableIndexes.get(colName)`，桶缺失即 `colIndex===undefined` → 整段跳过）、`kvstore_engine.ts:103-108`（open 回灌 `insert` 异常被吞）。 +- 现象（端到端实测）：`ALTER TABLE t ADD COLUMN email STRING UNIQUE` → 连续插入两条 `email='a@x.com'` **都不报错**（rows=2）→ close/reopen → 只剩 1 行，**无任何错误或警告**。 +- 根因：唯一性检查完全由二级索引桶承载，而 ALTER ADD 不建桶；重启时 `createTable` 依据 schema 建桶，回灌第 2 行触发 `UNIQUE_VIOLATION`，异常被 `catch {}` 吞掉 → 该行永久消失。同理 `CREATE UNIQUE INDEX` 落在一个已有普通索引的列上会静默 no-op（`memory.ts:562`），约束不生效。 +- 复现：见上（`tests` 临时用例已验证 `dupErr='' | before=2 | after=1`）。 + +**P0-3　`KVStore.open()` 命中损坏日志后把整条日志清零 → 已确认数据只剩内存，再崩溃即永久丢失** **[已复现]** +- 位置：`src/engine/kvstore/index.ts:135-138`（检测到损坏 → `truncateLog()`）、`index.ts:394-399`（`truncateLog` 写 `new ArrayBuffer(0)`，**不是** `log.subarray(0, validBytes)`）。 +- 现象：日志尾部有一条坏记录时，open 会先把坏记录之前**全部有效记录**应用到内存，然后清空整条日志；此时快照可能是上一次 checkpoint 的旧值甚至不存在。随后若进程崩溃（未 close、未 checkpoint），这些「已确认」的数据没有任何持久副本 → 永久丢失。 +- 佐证：`tests/engine/kvstore.test.ts:176-210` 只验证了**同一会话内** `confirmed/confirmed2` 仍在、且新写的 `after` 能跨一次重启（因为 after 是截断后新追加的记录），**从未验证第二次重启后 confirmed 仍在**。实测：`kv2.open()` 后日志字节数 = 0，第二次重启 `get('confirmed') === null`。 +- 附带影响：`KVStore.reload()`（index.ts:148-156）会清空索引再重新 open，若此前发生过错损截断，reload 直接把库变成空库——而 Hybrid 的跨标签页同步（`src/core.ts:86-90`）会周期性调用它。 +- 修复方向：open 截断应写回「有效前缀」或先落一次快照再清日志。 + +**P0-4　自动 checkpoint 失败发生在「日志已追加 + 内存已更新」之后 → 报错为假、事务回滚无效（数据复活）** **[已复现]** +- 位置：`kvstore/index.ts:334-362`（try/catch 只包住 `medium.append`，末尾 `logBytes +=` 与自动 checkpoint 在 catch 之外）、`kvstore/index.ts:385-390`（快照/meta/truncate 失败会以异常形式冒泡给 `put/putMany/writeBatch` 调用方）、`kvstore_engine.ts:545-553`（commit 里 `writeBatch` 抛错 → 内存 `commitTransaction` 未执行，调用方按惯例回滚）。 +- 现象（端到端实测）：事务 insert 一行 → 让快照写入失败 → `commitTransaction()` 抛错 → `rollbackTransaction()` 后内存 count=0 → **重启后 count=1**（被回滚的事务复活）。裸 `KVStore.put` 同样：rejects 但 `get` 有值、重启后 durable。 +- 根因：原子语义要求「日志追加失败 ⇒ 内存不更新」，但反向窗口（内存/日志已提交 ⇒ 必须报成功）没有保证；checkpoint 失败被算作写失败。`lastBackgroundError` 也只覆盖 append 失败路径。 +- 复现：注入 `medium.write('__kv_snapshot')` 抛错 + `checkpointThreshold` 设小。 + +### P1 — 结果错误 / 约束与事务语义破坏 + +**P1-1　maxLength / min / max 约束在 Memory/KVStore/Hybrid 上完全失效** **[已复现]** +- 位置：`memory.ts:691-711` 自带 `validateRow` + `memory.ts:713-722` `checkType` **只做类型判断**；而共享实现 `src/table/schema.ts:129-202` 的 `checkFieldType` 才校验 `maxLength`(146)、`min`(161)、`max`(167)。AriaEngine 走共享版（`src/engine/aria/index.ts:12,1672`）。 +- 现象：`maxLength:3` 的列插入 8 字符、`min:10/max:20` 的列插入 999 均成功（Aria 同 schema 会抛错）。 +- 影响面：README:56 明确宣称「输入校验（required / maxLength / min / max）」；三引擎静默接受越界数据 = 数据完整性缺口 + 引擎间行为漂移。 + +**P1-2　`find` 返回存储行引用（读到即能改库）** **[已复现]** +- 位置：`memory.ts:209`（无投影直接 `return results`）、`memory.ts:765-766`（索引路径回表得到的就是存储行对象）、`memory.ts:228`（`findStream` 回调传存储行）、`hybrid/index.ts:224`、`kvstore_engine.ts:294`（纯委托）。 +- 现象：`const rows = await db.query('SELECT * FROM t'); rows[0].name='HACKED'` → 再查已是 HACKED（在 Hybrid 下更严重：见 P2-4，调用方的改动会被后续无关 update 持久化到磁盘）。 +- 影响：绕过所有校验/钩子/审计、破坏事务快照（见 P2-5）、`find` 结果集共享导致的隐蔽耦合。`projectColumns`（`src/query/where-matcher.ts:214-228`）只做浅拷贝，嵌套 json 值仍共享。 + +**P1-3　自引用外键（同表 `references` 本表）的级联/RESTRICT 全部不生效** **[已复现]** +- 位置：`memory.ts:498`（`checkCascadeRestrict` 跳过同表）、`memory.ts:822`（`cascadeDelete` 跳过同表）、`memory.ts:432`（`applyUpdateCascade` 跳过同表）、`memory.ts:393`（`checkUpdateRestrict` 同样 `if (refTableName === tableName) continue`）。 +- 现象（实测三种）：`nodes.parent REFERENCES nodes(id) ON DELETE CASCADE` 删父行后子行残留（悬空引用）；`ON DELETE RESTRICT` 不抛错直接删掉父行；`ON UPDATE CASCADE` 改主键后子行 `parent` 仍是旧值。 +- 根因：三处「避免自引用无限递归」的保守跳过，用 `visited` 集合本可安全处理（`visited` 已经在用，memory.ts:493-495/817-818）。 + +**P1-4　ON UPDATE CASCADE 只级联一层 → 多层引用链断裂** **[已复现]** +- 位置：`memory.ts:430-448`：只遍历「列 `references` 的第一段 === 被改表」的直接引用表，修改的是引用表的**普通列**（如 `orders.user_id`），不会继续对 `orders.user_id` 的下游引用（如 `shipments.order_user REFERENCES orders.user_id ON UPDATE CASCADE`）做传递处理，也不进入 `planned`/预检体系。 +- 现象：`users.id: u1→u2` 后 `orders.user_id=u2`（已改），`shipments.order_user` 仍为 `u1` → 悬空引用。对照 `kvstore_engine.ts:599-621` 的 `affectedTables` 反而做了传递闭包（两边语义不一致：磁盘会重写孙表但内容仍是错的）。 + +**P1-5　事务期间的非事务写入被卷入事务并一起回滚** **[已复现]** +- 位置：`memory.ts` 所有写路径都**不检查 `snapshot`**（只有 DDL 检查，memory.ts:114/552/599）；`kvstore_engine.ts:261/318/389/427` 用全局 `txActive` 决定写入是否进 tx 变更集。 +- 现象：`beginTransaction(); insert('in-tx'); insert('concurrent-no-tx'); rollbackTransaction()` → 两行都没了。任何在事务 await 间隙由「另一个调用方」发起的写，都会被并进当前事务并随回滚消失（或随提交意外生效）。 +- 影响：引擎实例级「一个全局事务」的隐含假设；`db.transaction()` 与并发的 `db.table().insert()` 交错即触发。 + +**P1-6　KVStoreEngine：事务 commit 的 schema 落盘不在原子批内 → 部分提交 + 孤儿行** **[已复现]** +- 位置：`kvstore_engine.ts:545`（`writeBatch(puts,deletes)` 一条日志记录）与 `kvstore_engine.ts:547-549`（`persistSchema()` = 另一次 `kv.put('__schema')`）。CHANGELOG v0.6.1 宣称「一条日志记录 = 真原子，多表事务中途崩溃不会部分提交」，但 DDL 事务的这一半在批外。 +- 现象（实测）：事务内 `createTable('newt') + insert`，让 `__schema` 写入失败 → commit 抛错 → rollback → 重启后表不存在、**但 `t:newt:1` 已永久留在日志/快照里**（孤儿数据，open 时因表不存在被跳过，永不回收）。 +- 附带：反向窗口（行批失败、schema 已写）会留下「有表无行」的空表。 + +**P1-7　KVStoreEngine：非事务写落盘失败 → 内存/磁盘分叉，同一会话可读到幻影行** **[已复现]** +- 位置：`kvstore_engine.ts:258-290`（`memory.insert` 先提交，`kv.putMany` 后失败无补偿）、同类 `update`(302-382)/`delete`(384-417)/`clear`(424-436)。 +- 现象：注入 append 失败 → `insert` rejects，但 `find` 仍返回该行（同一会话可见），磁盘上没有；重启后行消失。Hybrid 有 v0.7.2 的 `recoverMemoryAfterDiskError` 补偿（hybrid/index.ts:199-209，实测有效），**纯 disk 模式没有这层保护**。 + +**P1-8　KVStoreEngine：open 回灌时的行级失败被静默吞掉** **[已复现]** +- 位置：`kvstore_engine.ts:103-108`（`try { JSON.parse; memory.insert } catch { /* 单行损坏跳过 */ }`）——注释设想的是「JSON 损坏」，但真实触发点还包括唯一冲突、类型不符、required 缺失等 schema 语义冲突。 +- 现象：schema 收紧（`email` 加 `unique`）后重启，磁盘 2 行、内存 1 行，**无日志、无计数、`repair()` 也不报**。与 P0-2 组成完整丢数据链。 + +**P1-9　KVStoreEngine：事务进行中 reload → commit 静默成功但一行未写（事务数据静默丢失）** **[已复现]** +- 位置：`kvstore_engine.ts:148-157`（`reload()` 无 `txActive` 守卫，`memory.close()/open()` 清空内存态但 `txChanges` 仍在）、`memory.ts:43-45`（`close()` **不清 `snapshot`**，所以后续 `memory.commitTransaction()` 反而成功）、`kvstore_engine.ts:540-542`（残留的 `'put'` 项被丢弃，既不 put 也不 delete）。 +- 现象：`beginTransaction(); insert('a'); reload(); commitTransaction()` → **不抛错**，count=0，数据消失。 +- 可达路径：`Hybrid.reloadMemoryFromDisk()` 由 BroadcastChannel 外部变更事件触发（`src/core.ts:79-91`），**任何时刻**（含事务中途）都可能打断正在执行的事务。 + +**P1-10　`setMeta` 不受事务回滚影响** **[已复现]** +- 位置：`kvstore_engine.ts:181-183`（直写 `kv.put`，无 tx 记录）、`176-179`（读同一层）。 +- 现象：`begin; setMeta('version','9'); rollback` → `getMeta('version') === '9'`。 +- 影响：迁移版本号（core.ts:107-114 `__metona_version`）一旦在事务内推进就无法回滚 → 迁移重跑判定失效（数据未迁移但版本已升）。 + +**P1-11　`MemoryEngine.close()` 遗留事务快照 → 重开后永久 `TX_ACTIVE`** **[已复现]** +- 位置：`memory.ts:43-45`（只清 tables/schemas/indexes/metaStore/opened，不动 `this.snapshot`）。 +- 现象：`beginTransaction(); close(); open();` → `beginTransaction()` 永远抛「Transaction already in progress」，`alterTable/createIndex/dropIndex` 永远抛 `NOT_SUPPORTED`（memory.ts:114/552/599）。 +- 可达路径：`KVStoreEngine.close()` 虽会先 rollback，但 `KVStoreEngine.reload()`/`repair()` 直接 `memory.close()`（kvstore_engine.ts:153、163）——这正是 P1-9 的成因之一。 + +**P1-12　介质层错误语义被折叠 → 不可恢复的「假空库」** **[读码确认]** +- 位置：`src/engine/aria/store/opfs_backend.ts:69-78`（`read` 把所有异常折叠为 `null`：文件不存在与 I/O 错误无法区分）、`opfs_backend.ts:84-113`（`dbDir===null`（已 close）时 `write/append` **静默 return**，调用方以为写成功）。 +- 链路：`kvstore/index.ts:98-111`（`read` 返回 null ⇒ 认为「无快照」）→ `index.ts:119-139`（无日志 ⇒ 空索引）→ 下一次 `checkpoint()`（index.ts:272-278）把空索引写成新快照并截断日志 ⇒ 介质上原有数据被永久覆盖。同理 close 之后的写入在 KVStore 内存索引里「成功」，重启即丢。 +- 建议：介质接口区分「不存在」与「读取失败」，写路径检查 `isOpen()` 并抛错。 + +### P2 — 健壮性 / 一致性 + +**P2-1　KVStoreEngine.open 失败后实例永久不可用，且真实错误被掩盖** **[已复现]** +- 位置：`kvstore_engine.ts:122`（`opened` 末尾才置位）、`75/79/80`（`kv.open`/`memory.open` 幂等早退）、`84-93`（catch 把 `createTable` 抛的「Table "a" already exists」重新包装成 `Corrupted schema in KVStore`）。 +- 现象：schema 半损坏 → 第一次 open 抛 KV_SCHEMA_ERROR；**第二次 open 仍抛同一个错误**（因为上次已建好的表再次 `createTable` 失败），永远无法打开，除非换实例。错误信息指向「schema 损坏」，真实原因是「表已存在」，可诊断性差。 + +**P2-2　行键编码用冒号拼接，表名含 `':'` 时重启串表/丢行** **[已复现]** +- 位置：`kvstore_engine.ts:65-71`（`t:${table}:${pk}`）与 `kvstore_engine.ts:99-101`（按**第一个**冒号切成 table/pk）。 +- 现象（实测两种）：表 `a:b` 的行键 `t:a:b:1` 在重启时被解析成 table=`a`、pk=`b:1`；`a` 不存在则整行跳过（`count('a:b')` 1→0，数据蒸发）；`a` 存在则**行被塞进表 `a`**（实测 `count('a')=1`、`rows(a)=[{"id":"1"}]`），即跨表数据污染。`collectTableDiff` 的 `startsWith(rowPrefix(table))` 前缀匹配（kvstore_engine.ts:638-661）同类风险（删表 `a` 会连带删掉 `a:1` 表的行）。 + +**P2-3　KVStore 的「假失败」还会留下重复 seq** **[读码确认 + 部分复现]** +- 位置：`kvstore/index.ts:357-362`（append 抛错即 `this.seq--`）。 +- 若失败发生在「数据已写但 API 抛错」（OPFS `close()` 阶段报错、配额错误等），日志里已有 seq=N，而内存水位退回 N-1；下一次成功写入又是 seq=N → 日志出现两条同 seq 记录。恢复按顺序应用（后者覆盖前者），最终值不一定等于写成功的那一条；`repair()`/`findValidLogLength` 也不会检测 seq 单调性。 + +**P2-4　Hybrid：json/数组等嵌套值在两个引擎间共享引用，调用方改动会被持久化** **[已复现]** +- 位置：`hybrid/index.ts:75-83`（`diskEngine.find` 返回的**存储行引用**直接交给 `memoryEngine.insert`）、`memory.ts:691-711`（`validateRow` 只浅拷贝顶层，嵌套对象按引用传递）。 +- 现象：`h.find(...)` 取出 `meta` 对象就地改 `flag`（不是一次 DB 写）→ 之后任意一次无关 `h.update(...,{v:2})` → 磁盘引擎把被污染的 `meta` 落盘，重启后读回 `MUTATED-BY-CALLER`。 + +**P2-5　事务快照是浅拷贝，嵌套值不在回滚范围内** **[读码确认]** +- 位置：`memory.ts:661`（`{...iv}`）、`memory.ts:638`（`new Map(this.schemas)`，schema/列定义对象共享）。 +- 影响：与 P1-2/P2-4 组合——事务内通过读结果就地修改嵌套对象，`rollbackTransaction` 无法还原；`schemas` 的共享对象也是 v0.7.2 必须「事务内禁止 DDL」的根因（memory.ts:111-119 注释自陈）。 + +**P2-6　Hybrid 双引擎分叉无任何校验/补偿** **[读码确认]** +- 位置：`hybrid/index.ts:232-241`、`243-252`（只返回内存引擎的 count，忽略磁盘引擎的 count）、`321-324`（rollback 内存先、磁盘后，内存抛错则磁盘不回滚）。 +- 影响：一旦两侧状态因任何原因（P1-7、失败补偿、reload）分叉，后续每次读写都在扩大分叉，且没有任何一致性检查点可用（`repair()` 只对齐一侧：hybrid/index.ts:99-104 修磁盘后重载内存）。 + +**P2-7　SharedMemoryBackend 的 materialized 缓存跨实例失效** **[读码确认]** +- 位置：`shared_memory_medium.ts:49-67`（`read` 缓存拼接结果）、`74-83`（`append` 只失效**本实例**缓存）、`15`（chunks 存于模块级 registry）。 +- 影响：A 实例读过 `__kv_log` 后，B 实例写入 → A 再 `read` 仍拿到旧缓冲；只有 `open()` 会重置缓存（`shared_memory_medium.ts:36`）。KVStore 的 `reload()` 恰好会 `medium.open()` 所以侥幸绕过，但 `repair()`、`listKeys` 类直接介质调用会有陈旧视图。仅测试/Node 介质，故 P2。 + +**P2-8　KVStoreEngine 非事务路径与介质层都缺少事务/生命周期守卫** **[读码确认]** +- `kvstore_engine.ts:170-174`（`clearAll` 在事务中直接 `kv.clear()` + `memory.clearAll()`，snapshot 仍在，rollback 会「复活」旧结构）、`kvstore_engine.ts:176-183`（`getMeta/setMeta` 不加 `ensureOpen`，未 open 也能写）。KVStore 侧 `put/delete/writeBatch` 不检查 `opened`（index.ts:202-254），close 后仍更新内存索引。 + +**P2-9　重启后 `CREATE UNIQUE INDEX` 来源标记丢失 → 无法再 DROP 该索引** **[已复现]** +- 位置：`memory.ts:26`（`uniqueIndexCols` 纯内存）、`kvstore_engine.ts:84-93`（open 只回灌 schema，不回灌来源标记）、`memory.ts:617-623`。 +- 现象：同一次生命周期内 `createIndex('t','email',true)` → `dropIndex` 可用；重启后同一个索引 `dropIndex` 抛 `NOT_SUPPORTED`。CHANGELOG v0.7.4 已把「重启后一律按建表约束保护」写成显式取舍，但这是一处「重启前后行为不同」的功能回退（P3 级体验，P2 级一致性）。 + +### P3 — 契约/可维护性（仅列有实际语义影响的） + +- **P3-1　`findStream` 忽略 `orderBy`**：`memory.ts:213-233` 从不读 `query.orderBy`，且 `limit/offset` 在**未排序**的迭代序上生效；接口文档却承诺「有 orderBy 时实现可回退物化」（`interface.ts:46-47`）。当前 SQL 侧不可达（`core.ts:307-309` 把 ORDER BY 判为不可流式），但 `table().stream()` 之外任何未来调用方都会静默拿到错误结果。 +- **P3-2　KVStoreEngine.open 的「重建二级索引」是死代码**（`kvstore_engine.ts:111-120`）：`createTable` 已建桶，`createIndex` 见 `colDef.index/unique` 立即 return（`memory.ts:562`），该循环从未起作用——但注释给人以「索引有独立重建步骤」的错误印象（真实重建靠 `createTable` + 回灌 insert）。 +- **P3-3　`__kv_meta` 只写不读**（`index.ts:275-276` 写、`95-118` 恢复时明确忽略），是纯冗余状态；`logBytes` 记账同样与实际日志长度脱节（`index.ts:132-134`、`382`、`398`：截断失败也置 0）。 +- **P3-4　CREATE INDEX 幂等静默 / DROP 不存在报错不对称**（`memory.ts:562` vs `memory.ts:610-612`）；SQLite 语义下重复 CREATE INDEX 应报错。 +- **P3-5　delete 返回「含级联」的行数**（`memory.ts:485`、`kvstore_engine.ts:416`），与 SQL「affected rows 仅指目标表」不同；Aria 测试已把级联计数钉死（`tests/aria-cascade.test.ts:26,44`），属四引擎共同语义债。 + +--- + +## 3. 性能议题 + +1. **主键变更 = 整表重写（写放大 ~1.8 万倍）** **[已实测]**：`kvstore_engine.ts:347-353` 走 `affectedTables` 传递闭包 + `collectTableDiff` 全表 put。2 万行表改 1 行主键 → **单条日志记录 1,877,821 字节**；同一表普通单行更新 103 字节。风险不止带宽：`encodeLogRecord`（`log.ts:47-92`）会一次性物化整条记录的 `Uint8Array`（含逐值 `new Uint8Array(e.value)` 拷贝），大表事务/级联删除会在内存里再造一份全表；10 万行级库（`tests/engine/kvstore-stress.test.ts` 只做 insert/update/delete，未覆盖主键变更与级联）可能直接 OOM 或产生数十 MB 单记录。 +2. **每次 UPDATE/DELETE 都是多趟全表扫描**：`kvstore_engine.ts:316`（`collectMatchingPks` → 一次 `find`）→ `memory.update` 的阶段 1 + 阶段 2（`memory.ts:267`、`289`）→ 落盘前再扫一遍（`kvstore_engine.ts:359`）。Hybrid 下每趟再 ×2（内存引擎 + 磁盘引擎各跑一次）。有索引时 `collectMatchingPks` 那趟能走索引，其余趟仍是全表。 +3. **`count()` 永不使用索引**（`memory.ts:531-538`）：`COUNT(*) WHERE indexed_col = ?` 全表扫描，而同样的 `find` 可以 O(1)。 +4. **`find` 无 where 时 `Array.from(table.values())` 全量物化**（`memory.ts:729/771`），即使 `limit:1`；`tryIndexLookup` 命中索引时也会新建结果数组（`memory.ts:764`）。10 万行库上「取第一行」是 O(n) 分配。 +5. **级联路径是 O(n·m) 双倍扫描**：`delete` 先 `checkCascadeRestrict` 对每个待删行扫描每一张引用表（`memory.ts:505-508`），执行阶段 `cascadeDelete` 再扫一遍（`memory.ts:834-839`）；`applyUpdateCascade`/`checkUpdateRestrict` 同样各扫一遍全表（`memory.ts:400-410`、`440-445`）。且级联按列嵌套循环（表 × 列），没有基于索引的定位。 +6. **`affectedTables` 是 O(T²·C) 的定点迭代**（`kvstore_engine.ts:599-621`），且每张表都 `await getTableSchema`（每次一次 Promise 往返）；它把「所有可能受影响的表」整表 diff，而实际只有极少数行会变。 +7. **每行一次 async/await + 序列化**：`KVStoreEngine.open` 恢复循环每行一次 `await memory.hasTable` + `await memory.insert`（`kvstore_engine.ts:97-109`），10 万行 = 20 万次微任务 + 每行 `JSON.parse`；写路径每行 `JSON.stringify` + `TextEncoder.encode`（`kvstore_engine.ts:286/363/534/650`）。 +8. **checkpoint 是全量 O(库大小) 且阻塞所有写**：`encodeSnapshot`（`snapshot.ts:29-59`）逐值复制整库；它跑在 `opQueue` 里（`index.ts:327-331`），期间任何 `put` 都要排队等待；`close()`/`commit` 前后的大库 checkpoint 直接体现为写延迟尖刺。自动阈值 16MB（`index.ts:37`）意味着单次 checkpoint 可能处理数万行。 +9. **大表 diff 的单记录上限风险**：`writeBatch` 把所有 put/delete 编进**一条**记录（`index.ts:237-242`）。行数越多，单个 append 越大，OPFS 的 COW 写需要整文件复制语义（`opfs_backend.ts:102-113`），峰值内存 ≈ 原日志 + 新记录；没有分片/批量上限保护。 +10. **测试对 10 万级只做了「写入 + 抽样读」**（`tests/engine/kvstore-stress.test.ts:23-61` 采样 4 个 key；第 2 例只校验 1001 个值）——没有覆盖主键变更、级联、事务回滚、自动 checkpoint 失败等重路径，性能悬崖（上述 1/8）都在覆盖面之外。 + +--- + +## 4. 系统性观察：四份「关系语义」实现的漂移与收敛点 + +**已发生的行为漂移（可举证的重复实现代价）** +1. **校验规则两份**：`memory.ts:691-722` 的私有 `validateRow/checkType` 与 `src/table/schema.ts:87-202` 的共享版并存，前者漏掉 `maxLength/min/max` —— 漂移已经真实发生（P1-1），且 README 的宣称只对 Aria 成立。 +2. **主键解析三份**：`memory.ts:686-689`、`table/schema.ts:66-71`、`kvstore_engine.ts:579-584` 三处同样的「找 primaryKey，否则第一列」。 +3. **「受影响表」三种定义**：MemoryEngine 的级联只认「列 references 的第一段 === 被删/改表」（`memory.ts:497-503`、`433-436`，自引用被跳过、ON UPDATE 不传递）↔ KVStoreEngine 的 `affectedTables` 做**传递闭包**（`kvstore_engine.ts:599-621`）↔ Aria 自有实现。结果：同一句 `DELETE`/`UPDATE`，内存里的级联范围与磁盘重写范围不同（P1-4 里磁盘重写了孙表、但内容依旧错误）。 +4. **事务内 DDL 三种语义**：Memory/KVStore 拒绝 ALTER/CREATE INDEX/DROP INDEX 但允许 create/dropTable（`memory.ts:114/552/599`、`kvstore_engine.ts:236/442/459`），Aria 拒绝 ALTER；而 KVStore 的 createTable 在事务里可回滚、schema 却在 commit 的原子批之外（P1-6）。 +5. **唯一索引三处状态机**：`colDef.unique`（schema 标志）+ `indexes` 桶 + `uniqueIndexCols`（来源）+ 重启后的「一律视为建表约束」（P0-2、P2-9）。任一环缺失就出现「约束静默失效」或「重启后不可 DROP」。 +6. **索引一致性靠人工纪律**：`removeIndexEntries/updateIndexes` 的调用点分散在 update 阶段 2、cascadeDelete、applyUpdateCascade、clear、alterTable DROP、dropIndex 共 8 处（`memory.ts:135/179/291/298/442/444/481/544/628/791/855/868`），CHANGELOG 里 v0.3.3/v0.6.3/v0.7.3 连续三个版本都在修「某条路径忘了清/建索引」——这是典型的、还会继续发生的缺陷类别。 +7. **行/键编解码两份**：Memory 用 `String(pk)`，KVStoreEngine 用 `t:${table}:${pk}` 且按第一个冒号解析（P2-2），Aria 另有布局；`String()` 归一也意味着 number PK 与 string PK 在键空间理论上可碰撞（当前被 `checkType` 挡住）。 + +**收敛建议（按性价比排序）** +1. **统一校验**：删除 `MemoryEngine.validateRow/checkType`，改用 `table/schema.ts` 的 `validateRow`（已含 default/required/PK 非空/maxLength/min/max），一处修复即同时修复 Memory/KVStore/Hybrid（P1-1），并让四引擎的 `VALIDATION_ERROR` 文案一致。 +2. **抽出共享「外键规则引擎」**：输入（schemas + 变更集合 + 方向），输出（RESTRICT 违规 / 需 CASCADE 的行 / 需 SET NULL 的行），**递归 + 自引用 + visited 都在同一处实现**，供 Memory 与 Aria 直接调用，供 KVStoreEngine 生成「受影响主键集合」而不是「整表 diff」。这能一次性消灭 P1-3/P1-4、第 3 节的写放大与 O(n·m) 扫描，并让四个引擎的 delete/update 计数语义统一。 +3. **让 MemoryEngine 自己产出变更日志（change hook）**：insert/update/delete 时回调「(table, pk, 'put'|'delete')」，KVStoreEngine 只负责把这份日志刷成日志记录。这样 `txChanges/txFullTables/txClearedTables/collectMatchingPks/collectTableDiff/affectedTables` 六个启发式结构（以及它们导致的 P1-6/P1-7/P1-9）可以整体删除，「持久化 = 内存变更的重放」成为结构性保证而非逐路径补丁。 +4. **统一行键编解码**：零依赖的长度前缀或转义编码（或干脆把 table 名放进独立键段），消灭 P2-2 一类「拼接分隔符」缺陷；`String(pk)` 归一集中一处并显式声明 PK 的键空间规则。 +5. **把 schema 纳入同一条原子记录**：commit 时把 `__schema` 与行变更放进同一 `writeBatch`（或在快照内统一版本化），P1-6 的孤儿数据与「有表无行」窗口即消失。 +6. **内存引擎补写锁/事务互斥**：至少让写路径在 `snapshot !== null` 时拒绝或加入事务（`txActive` 显式化），并在 `close()` 中清空快照；这消除 P1-5、P1-9、P1-11 一类「状态泄漏 → 静默丢数据」问题。 +7. **KVStore 恢复路径的原子化契约**：open 截断必须落盘等价状态（先快照或写回有效前缀），写失败不得在内存/日志之间产生「半提交」，介质接口区分「不存在/读失败/已关闭」。这是 P0-3、P0-4、P2-3、P2-6 的共同根因——**恢复路径缺少「内存状态 ↔ 介质状态」的等价性证明**，目前依赖调用方（KVStoreEngine.close）恰好会 checkpoint。 + +**测试覆盖的结构性缺口**（直接影响上述风险的可回归性）：现有用例把「结果」钉死了，但缺**第二次崩溃**（`kvstore.test.ts:176-210` 只重启一次）、缺**注入 checkpoint 失败**、缺 **reload/close 期间的事务**、缺 **ALTER 后的约束行为**、缺 **自引用/多层外键**、缺 **10 万级的主键变更与级联**。这七类恰是本次 P0/P1 的高发区。 diff --git a/PLAN-v0.7.5.md b/PLAN-v0.7.5.md new file mode 100644 index 0000000..ed05bbc --- /dev/null +++ b/PLAN-v0.7.5.md @@ -0,0 +1,694 @@ +# 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` + - `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`）， +即同时解决第 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 总账。