MetonaSqlark/CHANGELOG.md

Changelog

All notable changes to MetonaSqlark will be documented in this file.

[0.6.1] - 2026-08-10

生产可用性深度审查（异常场景）

以"生产可用"标准全面审查：修复级联环无限递归、多表事务原子性缺口、 统一未 open 防护，并新增 27 个异常场景测试。

Fixed

• 二级索引范围扫描漏读尾部数据（P0） — SSTable 索引块记录的是"块内最后一个 key" （builder 约定），读端 locateBlockLE 却按块首 key 语义二分：范围查询 endKey 落在 某块尾部时，下一块（尾 key 越界但首 key 仍在范围内）被排除 → 二级索引条件查询 静默丢数据（5 万行写入查 tag='t5' 丢 106~771 条，主表全扫描完整）。 修复：rangeScan 的 endBlockIdx 多扫一个块（条目级过滤兜底，不丢不错）； 新增 4 个 SSTable 边界回归（跨前缀尾部/精确块尾/超出全量/多前缀一致性）
  • 重建 3 个二级索引大数据量回归（5 万行/高频小批量/多索引列，含崩溃恢复）
• checkpoint 未落盘二级索引（P1） — checkpoint 只 flush 主 LSM，截断 WAL 后崩溃时 索引 memtable 未落盘、WAL 为空跳过重建 → 二级索引静默丢失最后一批条目。 checkpoint 的 flushAll 同步 flush 全部二级索引 LSM
• kv 后端页面化缺失 — pageStorage 默认只对 opfs 生效；kv 后端整 value SSTable （4MB）超过 1MB 页面缓存时每次读取全量重载。kv 后端同样启用页面化， 读放大消除；SharedMemoryBackend 改为 chunk 列表（append O(1)）+ 惰性拼接缓存
• MemoryEngine 级联环无限递归（P0） — A→B→A 循环引用 + CASCADE 删除导致栈溢出 （RangeError: Maximum call stack size exceeded）—— MemoryEngine.cascadeDelete 无环路保护， AriaEngine 已有 visited 保护（v0.4.1），Memory 侧缺失。新增 visited 集合（表:主键）， 与 Aria 语义对齐；A→B→A 环 + 深链 A→B→C→D 均有回归测试
• KVStore 快照损坏水位 bug（P0） — baseSeq = max(metaSeq, snapshotSeq) 在快照损坏 回退全量日志重放时，meta.seq（最后一次 checkpoint 水位）错误跳过日志中 checkpoint 后 的有效记录 → 静默丢数据。水位只信任快照内嵌 seq
• 多表事务 commit 非原子（P1） — 事务 commit 逐表 flush：中途失败/崩溃 → 部分表已提交。 重构为全部 dirty 表合并单次 putMany/deleteMany（一条日志记录 = 真原子）
• 级联更新/删除非原子（P1） — update 主键变更/delete 的级联影响表逐表 diff 分多次写。 重构 collectTableDiff 合并到单次原子写（主表 + 全部级联表同一条日志记录）
• 未 open 防护不一致 — getTableNames/hasTable/getTableSchema 未检查 DB_NOT_OPEN （返回空而非报错，与其余方法不一致）。统一 ensureOpen
• 测试盲区 — 快照损坏测试此前篡改未生效（close 后介质不可读），从未真正覆盖损坏路径； 修复并新增 metaSeq 超前回归测试
• 批量插入性能悬崖（P1） — insert 循环内逐行 lsm.prefetchKeys([key])， 每行 await drainChain() 排空后台链：后台 compaction 在链上数秒时每行阻塞数秒 → 10 万级插入从 5ms/批暴跌到 811s/批（kv 后端 10 万行共 353s）。 修复：批级预加载本批全部 PK（一次 drainChain），循环内 lsm.get 由 memtable/flush 产物（自动入缓存）兜底，完整性与批量语义不变。 实测：kv 后端 10 万行 353s → 12.5s（28 倍），opfs 后端 25s； 新增 kv/opfs 双后端 10 万行回归（性能护栏 + 索引完整 + 崩溃恢复）

Added

• AriaEngine 可选自研 KVStore 后端（storageBackend: 'kv' / diskEngine: 'kv'）：
  • aria 完全跑在自研存储栈上（KVStore 日志+快照），不再依赖浏览器 OPFS API（Node/测试用 SharedMemory 介质）
  • KVStore 新增 APPEND 日志操作类型：aria WAL 分片追加 O(chunk) 高效，恢复按序拼接，checkpoint 快照含最终值
  • writeMany/deleteMany 经 KVStore 单日志记录真原子（此前 OPFS 逐文件写）
  • aria 崩溃恢复 = KVStore 双层恢复 + WAL 重放；二级索引/页面化兼容（kv 后端 SSTable 整 value 存储）
  • 10 个 aria+kv 集成测试（后端单元/CRUD 持久化/WAL 追加恢复/checkpoint 混合/索引/大数据崩溃/高层 API 事务级联）
• 27 个生产异常场景测试（tests/production-abnormal.test.ts）：
  • KVStore 边界：空 value/空 key、1MB 大 value、中文/emoji/冒号/超长 key、未 open、 重复 open/close 幂等、clear 后写、1 万小 key、写失败后继续可用
  • KVStoreEngine：未 open 全操作、重复 close、不存在表、事务嵌套 TX_ACTIVE、 无事务 TX_NONE、commit 失败回滚（磁盘无部分提交）、多表事务原子性、级联环、 深链级联、主键变更+索引一致性、空表操作、5000 行批量删除持久化
  • SharedMemoryBackend 全分支：append 拼接、writeMany/deleteMany、close 后安全、跨实例共享
  • 日志解析损坏分支：onCorrupt false 停止、keyLen 越界记录丢弃
• AriaEngine 级联环/深链回归测试（与 Memory 对齐）

Changed

• 测试 1022 → 1049（65 套件）；行覆盖率 89.15% → 89.33%
• 事务/级联写入路径：逐表 flush → 单条日志记录原子（性能与一致性双提升）

---

[0.6.0] - 2026-08-10

里程碑：完全移除 IndexedDB，自研 KV 事务存储引擎

达成"彻底删除 IndexedDB + 自研类似 IndexedDB 的存储后端"目标： KVStore 引擎在 OPFS 之上实现多 key 原子事务（IndexedDB 的核心能力）， disk 模式全面切换，旧库一键迁移。

Added

• KVStore 自研 KV 事务引擎（src/engine/kvstore/）：
  • 多 key 原子写：putMany/deleteMany = 单条日志记录（单文件 COW 原子追加）→ 崩溃全有或全无
  • 持久化与崩溃恢复：快照（checkpoint）+ 追加日志，两阶段恢复（快照水位跳过）
  • 自愈：快照损坏回退全量日志重放；日志损坏截断至损坏处；repair() 清理
  • 容错时序：checkpoint = 写快照 → 写 meta → 清空日志（meta 先于截断，任何崩溃窗口不丢数据）
  • 写操作与 checkpoint 串行队列（无交错窗口）；标准 CRC-32 全程校验
  • 介质层：OPFS（浏览器）/ SharedMemoryBackend（Node/测试，跨实例共享模拟持久化）
• KVStoreEngine（disk 模式，替代 IndexedDBEngine + OPFSEngine）：
  • 内存热路径 + KVStore 原子持久化；读 O(1)，写增量/整表 diff 分级
  • 事务：内存快照 + commit 原子 flush（受影响表），事务内 DDL 支持（schema 一并持久化）
  • 外键级联（CASCADE/SET NULL/RESTRICT）持久化、主键变更、二级索引跨重启恢复
  • reload() 支持多标签页同步重载（Hybrid 场景）
• 迁移工具 migrateFromIndexedDB()：一次性把旧 IndexedDB 库（schema/索引/行）导入新引擎； 旧库不存在/aria 私有格式（SSTable/WAL）明确报错；目标库已有表跳过不覆盖
• 可靠性强化：
  • 10 万 key 写入+checkpoint+重开全量验证（928ms）
  • 5 万混合操作+崩溃模拟零丢失
  • e2e 新增写入中途崩溃 / checkpoint 前后崩溃注入 / KVStoreEngine 真实环境持久化-索引-事务（12 用例）
• MetonaSqlark 配置：diskEngine 类型收敛为 'opfs' | 'memory'（默认 'opfs'）

Removed

• src/engine/indexeddb.ts（840 行 IndexedDBEngine）—— 版本冲突/blocked 重试/onversionchange/flushToIDB 全部消失
• src/engine/opfs.ts（375 行 OPFSEngine）—— 能力被 KVStoreEngine 覆盖
• IndexedDBBackend（aria 后端）—— aria storageBackend 收敛为 'opfs' | 'memory'
• 26 个测试文件的 fake-indexeddb 依赖改造为 KVStore SharedMemory / OPFS mock

Fixed

• Hybrid 多标签页重载失效（KVStoreEngine 读内存 vs 磁盘引擎读穿透）—— 新增 reload() 从介质重载
• 事务内 DDL schema 不持久化—— commit 时统一 persistSchema（重启后表结构完整）
• repair 缓存掩盖损坏—— 先清 BufferPool 再校验（缓存中"完好页面"不再掩盖磁盘损坏）
• dropInvalidSSTable 孤儿页面—— 先删数据文件再删 meta（页面化删除依赖 pageIds 定位）

Changed

• 测试 1009 → 1022（64 套件；+58 新增 kvstore/kvstore-engine/压力/迁移测试，-46 删除/改造 IDB 测试）
• 行覆盖率 87.25% → 89.13%
• 浏览器支持收敛到 OPFS 矩阵（Chrome/Edge 102+、Firefox 111+、Safari 15.2+）；Node 用内存介质
• fake-indexeddb 保留为 devDependency（仅迁移工具测试用）

---

[0.5.1] - 2026-08-10

深度审查：消除假实现/半成品/死代码

对全部源码做系统性审查，修复"宣称存在但从未接线"的假实现、补齐无入口的半成品、 删除无引用的死代码。

Added（假实现接线）

• CRUD 生命周期钩子真实接线 — 此前 beforeInsert/afterInsert/beforeUpdate/afterUpdate/beforeDelete/afterDelete 六个钩子仅存在于类型与文档宣称（"14 种钩子"），从未被任何路径触发。现已在两条路径真实触发：
  • Table API：table().insert/insertMany/update().execute()/delete().execute()
  • SQL：db.query("INSERT/UPDATE/DELETE ...") 参数与文档一致（beforeInsert: rows[]、afterUpdate: query, updates, count 等）；事务路径不触发（Table 无 hooks 回调，与现状一致）
• EXPLAIN SQL 入口 — 此前 executor 有 EXPLAIN 分支但 parser 无法解析（无 token），只能手工构造 AST 测试。 补齐 EXPLAIN <statement> 语法（tokens/lexer/parser），任意引擎可用
• ANALYZE / REINDEX / VACUUM SQL 入口 — 此前仅有 AriaEngine 方法（(engine as any) 才能调用），README 宣称能力但用户无法触发。 补齐 ANALYZE [TABLE] name / REINDEX [TABLE] name / VACUUM 语法；不支持的引擎抛 NOT_SUPPORTED
• SAVEPOINT SQL 入口 — 补齐 SAVEPOINT name / ROLLBACK TO [SAVEPOINT] name / RELEASE [SAVEPOINT] name； ROLLBACK [TRANSACTION] 保持原语义
• db.backup() 公共方法 — 引擎级 backup（MVCC 一致性视图）此前无公共入口；Aria 走引擎级，其余引擎回退 exportAll

Removed（死代码）

• src/utils.ts 整文件 — generateId/escapeHTML/deepMerge/debounce/throttle/isBrowser 在 src 内零引用 （v0.0.1 遗留，仅测试锁定）；连同 tests/utils.test.ts 删除
• estimateQueryCost（未接线的"查询优化器"） — 实现与测试存在但从未接入查询路径（find 用 tryIndexLookup 硬编码），删除消除"优化器存在但没用"假象
• MVCC 读侧全套 — readVersion/getLatestCommittedVersions/clearTable/getActiveTxnCount/isActive/getActiveWriteKeys： 引擎事务读取走 txnSnapshot（MVCC 仅作 undo log），读侧实现从未执行。删除并改写相关测试为验证版本链清理/GC 行为
• 统计/辅助死方法 — EvictionManager.getAllPages/getSize/popLRU/getCapacity、BufferPool.getCachedPageCount/getDirtyPageCount/getCapacity/newPage、 WAL.isEnabled/getLSN、CheckpointManager.forceCheckpoint/setInterval/getOpCount、LSM.isInitialized/getCacheSize/getCacheLimit、 SSTableReader.getMeta/getIndexBlockCount/getStoredChecksum、BloomFilter.getBitSize/getInsertedCount、MemTable.contains、 FileManager.allocateTableRootPage/createEmptyPage、OPFSEngine.loadTableIntoMemory、QueryExecutor.setMaxRowsPerQuery、 ConnectionManager.getRefCount
• 类型/常量死代码 — STORAGE_MODES/DISK_ENGINES、ColumnEncoding/DEFAULT_BLOCK_SIZE/DataBlock、CallbackEntrySource、StatementType、AggregateExpression、SubqueryExpression
• Crypto 全局兼容层 — initCrypto/encryptPage/decryptPage/closeCrypto/isCryptoEnabled（v0.5.0 后引擎走 EncryptedBackend 实例，全局单例无消费者）；删除过时的"全局加密落盘"测试（aria-encryption.test.ts 已覆盖等价路径）

Changed

• 测试 1022 → 1009（62 套件；删除 13 个死代码测试 + 新增 22 个 hooks/维护语句测试）；行覆盖率 86.68% → 87.25%
• README 补维护语句表（EXPLAIN/ANALYZE/REINDEX/VACUUM/SAVEPOINT SQL 入口）与 db.backup() API
• 14 个生命周期钩子现在全部真实触发（site/docs.html 与 CONTRIBUTING 宣称变为事实）

---

[0.5.0] - 2026-08-10

里程碑：存储后端生产级硬化（自研 OPFS 后端全面落地）

本次版本对 AriaEngine 存储层做全链路生产级改造：修复"宣称有校验和/加密/页面式存储但实际未实现"的失实实现， WAL 重构为分片文件（消除多文件原子性与文件爆炸问题）、SSTable 页面化物理存储（BufferPool/FileManager 真正接入）、 多标签页独占锁、repair 自愈增强，并引入真实 Chromium e2e 验证。

Added

• 全库 AES-256-GCM 加密（真实接线） — AriaEngineConfig.encryption.password：
  • EncryptedBackend 装饰器在 backend 层透明加解密（WAL/SSTable/Schema/元数据全覆盖，每个 value 独立随机 IV + GCM 认证）
  • PBKDF2-SHA256（100000 迭代）派生密钥，salt + verifier 持久化于 __aria_keymeta（密码错误 → ARIA_DECRYPT_ERROR）
  • 加密开关一致性检测：明文旧库 + 加密配置 → ARIA_ENCRYPT_CONFIG_ERROR；加密库 + 无密码 → ARIA_ENCRYPT_REQUIRED
  • clearAll 保留密钥元数据（库身份保留，密码不变）
• WAL 分片存储重构 — SegmentedWALStore（__wal_%06d.bin）：
  • 取代"每条记录一个 key"旧结构：分片阈值 4MB 自动切换，文件数量可控
  • WAL 序号（LSN）内嵌记录字节流，移除 __wal_count 键 → append 单文件原子写（createWritable COW）
  • 空洞检测：分片序号不连续 → 空洞之后保守丢弃（仅可能来自 truncate 部分完成，数据已落盘，无害）
  • 旧格式 __wal_N + __wal_count 兼容：读取迁移重放，checkpoint 统一清空
• OPFS 后端 v2 —
  • append() 真追加：createWritable({ keepExistingData }) + seek，O(chunk) 无需读旧内容
  • 写队列健壮性：单次任务失败不中断队列链（错误返回给调用方），close 等待队列排空
  • open 自动清理崩溃残留临时文件（.crswap/.tmp）
  • 原子性文档化：单文件 createWritable 为 copy-on-write 原子替换
• SSTable 页面化物理存储（BufferPool/FileManager 真正接入） —
  • PageSSTableStore：SSTable 切分为 4KB 页面，经 FileManager 分配 pageId、BufferPool LRU 缓存
  • save 语义 = 已持久化（逐页 flushPage 落盘后才返回，WAL checkpoint 截断安全）
  • 页面 ID 列表经 SSTableMeta.pageIds 持久化；旧 meta（无 pageIds）自动走整 value 读取（兼容）
  • OPFS 后端默认启用（pageStorage 配置可覆盖）；FileManager 批量分配 allocatePageIds（一次 meta 持久化）
  • 读取缺失页面返回 null（此前返回空页会静默掩盖页面丢失，自愈路径依赖 null 触发清理）
• 多标签页独占锁 — Web Locks API（Chrome 69+ / Firefox 96+ / Safari 15.4+）：
  • ifAvailable 模式：第二个标签页打开同一库 → 抛 ARIA_LOCKED（不排队挂起）
  • 打开失败自动释放锁（不泄漏）；close 等待锁真正归还
  • 不支持 Web Locks 的环境降级为无锁 + 告警（如实文档化）
• repair() 自愈增强 — 孤儿页面清理（meta 未引用的 pg_ 文件）、OPFS 残留临时文件清理、WAL 空洞截断落地
• LZ4 格式 v2 — 压缩流前置 4 字节原始大小头：解压不再依赖外部估算（高压缩率数据下 buf.length*2 估算不足会截断），损坏头显式抛错
• SSTable 真实 CRC-32 校验和 — footer checksum 字段从写死 0 升级为整文件标准 CRC32（checksum=0 识别旧版文件跳过校验，兼容旧库）；打开校验/compaction 加载/运行期预加载三处均校验，损坏文件自动清理自愈
• WAL 标准 CRC32 — 记录校验从弱滚动校验升级为标准 CRC32；双算法探测（新算法失败再试旧算法）兼容旧 WAL 记录
• 配置透传 — DatabaseConfig.aria：MetonaSqlark.create() 可配置 walSyncMode/checkpointInterval/encryption/pageStorage/compression 等 AriaEngine 专属参数
• Playwright e2e（真实 Chromium + OPFS） — 7 用例：持久化（刷新保留）、关闭重开、崩溃恢复（WAL 重放）、多标签页锁、加密密码往返、页面化端到端 + 索引查询、repair 自愈；npm run test:e2e

Fixed

• 加密此前从未接线（严重失实） — crypto 模块全局单例从未被引擎调用、salt 不持久化重启无法解密；README 宣称的 AES-GCM 实际不可用。改为 EncryptedBackend 装饰器 + keymeta 持久化 + 密码验证
• SSTable checksum 写死 0（严重失实） — 数据腐坏（bit flip）完全无法检测。升级为真实 CRC-32，损坏文件打开自愈
• OPFS writeMany 无原子性（P0） — WAL 记录 + count 多键写入非原子，记录空洞导致后续记录字节错位解析失败。分片重构后 WAL append 单文件原子写 + 空洞检测截断根治
• OPFS 高频写入文件爆炸（P1） — 每条 WAL 记录一个文件，8 万条记录 = 8 万次 createWritable。分片存储 + 真追加根治
• LZ4 高压缩率解压截断（P1） — buf.length * 2 估算原始大小，压缩率 >50% 时截断（SSTable 魔数在文件末尾被丢 → 整库数据丢失）。格式 v2 头部自描述根治
• OPFS 写队列失败永久中断（P1） — 队列任务抛错后链 rejected，后续所有写挂起。单次失败不中断链
• OPFS close 不等挂起写（P1） — close 立即置空目录句柄，挂起写静默丢失。close 等待队列排空
• Web Locks 方法解构 this 绑定丢失（e2e 发现） — navigator.locks.request 解构后调用抛 Illegal invocation。改用 .bind(lockManager) 保持 this
• 页面化 + 崩溃窗口数据丢失（压力测试发现） — 修复前页面化路径在模拟崩溃测试中丢失已确认写入；根治后 500 随机操作 + 崩溃重放零丢失

Changed

• AriaEngineConfig 新增 encryption / pageStorage；DatabaseConfig 新增 aria 透传
• 页面层精简：删除从未接入主路径的 slot/tuple 模块（假"页面式存储"实现），仅保留生产代码实际使用的 initPageHeader/createPage；架构宣称如实更新（4KB 页面承载 SSTable 字节切片，非行级 Slotted Page）
• LZ4 压缩格式不向后兼容（v0.2.6 已声明 compression 数据需重新导入，本次格式 v2 同理）
• 测试 958 → 1022（62 套件）；行覆盖率 84.2% → 86.68%；新增 6 套件：crc32 / aria-checksum / aria-wal-crc / aria-wal-segment / aria-opfs-backend / aria-page-store / aria-encryption / aria-locks / aria-repair-hardening / aria-page-core
• 新增 Playwright e2e 基建（npm run test:e2e，7 用例真实 Chromium）

---

[0.4.4] - 2026-08-09

Fixed

• SSTable 编码缺陷导致大内容写入崩溃（P0） — AriaEngine 保存大段中文内容（如 300KB 笔记）→ close 构建 SSTable 崩溃 → 半写文件 → 下次打开 ARIA_OPEN_ERROR：
  • 块大小估算用 UTF-16 码元而非 UTF-8 字节 — computeBlockSize 用 json.length（中文 1 字 = 1 码元）估算，实际写入 UTF-8 字节（中文 1 字 = 3 字节）→ 300KB 中文实际 900KB → 缓冲区低估 → Uint8Array.set 越界崩溃。改为 TextEncoder 预编码，全部按字节长度计算（切块、块大小、索引块、总大小）
  • valueLen/keyLen 字段 u16 截断 — 长度字段 u16 上限 64KB，大 value 被截断 → 线性格式整体错乱。格式 v2（magic "SSTC"）升级为 u32 长度字段
  • 大 value 块切分 — 单条 value 超过块大小（4096）时独立成块（基于字节估算正确切分）
  • 格式兼容 — reader 支持 v1（"SSTB"，u16）与 v2（"SSTC"，u32）双格式：旧库 v1 文件仍可读（小 value 场景无缺陷），新写入用 v2，旧库数据不丢失
  • 连带受益：中文主键 key、大内容二级索引列（索引 key 含列值）同样支持 u32 长度字段

Changed

• 测试 950 → 958（52 套件），新增 tests/v045-hardening.test.ts（8 条：300KB 中文 builder/端到端跨重启、>64KB value、大 value 独立成块、中文 key、v1 兼容、v2 魔数）
• 版本号升至 v0.4.4

---

[0.4.3] - 2026-08-09

Fixed

• close 后后台 compaction 吞错并在 backend 关闭后执行（P0） — scheduleCompact 用 setTimeout(0) 调度：close 时未触发的定时器在 backend.close() 后执行，用已关闭的存储写（错误被吞）；close 后立即 reopen 时旧闭包引用新 backend 交叉污染。改为 compaction 直接挂 flushChain 串行执行，close 的 drainChain() 排空全部级联任务后再关闭存储
• 后台 flush/compaction 失败完全静默（P0） — 吞错防死锁的同时记录 lastBackgroundError，显式 flush()/close() 时抛 ARIA_BACKGROUND_ERROR（消费一次），不再永久不可见
• prefetch 与 compaction 竞态丢数据（P0） — 后台任务在链上动态增长，prefetchRange/prefetchKeys 单次 await flushChain 后 compaction 仍可能合并 levels，扫描时新 meta 缓存未命中 → 跳块丢数据（缓存驱逐场景 UPDATE/DELETE 少删行）。改为等待链稳定（drainChain）再预加载
• commitTransaction 提交顺序（P1） — 先合并快照后写 WAL COMMIT：WAL 写失败时内存已提交但持久化缺失，崩溃重启丢失。改为先持久化 WAL COMMIT 再合并快照（WAL 始终领先，崩溃恢复一致）
• OPFS close 不等挂起写（P1） — 写操作整体串行入队（内存写 + 快照 + 文件持久化），close/repair/clearAll 先等队列排空再释放目录句柄，避免 close 后挂起写读旧数据
• IndexedDBEngine close 活跃事务防御 — close 时自动回滚活跃事务（避免对已关闭连接操作报错）

Changed

• 测试 944 → 950（51 套件），新增 tests/v044-hardening.test.ts（6 条：close 后台任务排空、reopen 无污染、后台失败可见、链不卡死、WAL 提交顺序、OPFS close 等待）
• 版本号升至 v0.4.3

---

[0.4.2] - 2026-08-09

Fixed

• AriaEngine 残缺 SSTable 导致打开崩溃（P0） — 异常退出后下次打开抛原生 RangeError: offset is out of bounds，库打不开只能删库重建。三处根治：
  • SSTableReader 读路径防御：块偏移/大小越界时跳过该块（get/rangeScan/scanAll 返回空或继续），索引块/块内条目解析全程边界检查，不再抛 RangeError
  • 打开时完整性校验：LSM.init() 校验 meta 引用的文件存在、长度 ≥ 头、可解析，残缺的忽略并清理 meta/文件（自愈，不阻塞打开）
  • WAL 原子写入：IndexedDBBackend 新增 writeMany/deleteMany（单事务批量写删），WAL 记录与 count 计数同事务提交，中断整体回滚不留半写
• IndexedDB 版本管理缺陷导致重启必报 VersionError（P0） — 建表每张版本号 +1 而 open() 用 config.version，重启后版本过低直接失败。open() 遇 VersionError 自动用无版本参数探测库当前实际版本并以该版本重开
• create({ version: 0 }) 抛原生 TypeError（P0） — 版本 < 1 统一归一化为 1，不再直接炸 indexedDB.open(name, 0)
• WAL 写丢失（P1） — 连续快速写入 200 条 close+重开实测丢 4 条。WAL 恢复不再依赖 count 计数，改为扫描全部 __wal_* 键（数值排序拼接），count 键只作序号分配器；配合原子写入彻底消除 count/记录竞态
• AriaEngine.close() 不 checkpoint，WAL 无限重放（P1） — close 前补 wal.checkpoint() 截断，下次打开不再重放已落盘的历史记录
• 引擎内部错误不包装 DatabaseError（P1） — AriaEngine open() 整体 try/catch 包装为 ARIA_OPEN_ERROR；IndexedDBEngine 打开路径统一 IDB_OPEN_ERROR/IDB_VERSION_ERROR/IDB_BLOCKED，应用层可拿 code 分类处理
• migrateTo 版本门槛与引擎版本脱节（P2） — 迁移版本持久化到库内（IStorageEngine.getMeta/setMeta 可选接口，Aria 存 backend、IndexedDB 复用 __metona_schema store、OPFS 存元数据文件、Hybrid 委托磁盘引擎），重启后从持久化版本继续执行，不重跑不跳跑
• IndexedDB onblocked 直接 reject（P2） — 改为等待后重试（阻塞解除后 success 仍触发，仅超时判失败，并防止连接泄漏），多次重试仍阻塞才抛 IDB_BLOCKED
• 缺少官方崩溃恢复/自愈接口（P2） — 新增 db.repair()（校验清理损坏数据并恢复一致性）与 db.clearAll()（清空全部数据与表结构，保留库），全部引擎（Aria/IndexedDB/OPFS/Memory/Hybrid）实现，无需删库重建
• IndexedDB __metona_schema store 缺失时元数据无法落盘 — open() 时确保 schema/meta store 存在（缺失则一次版本升级创建）

Fixed（深度审计第二轮）

• AriaEngine 二级索引跨重启丢失（严重） — 重开只恢复 schema 不恢复索引 LSM：索引查询静默回退全表、createIndex 因 schema 标记已存在而直接 return → 索引永久缺失；且 WAL 崩溃恢复只回放主 LSM，最后一批写入的索引缺失 → 索引查询丢行。三处根治：open 时按 schema 标记重建索引 LSM（数据已持久化直接加载）、close 时同步落盘全部索引 LSM、WAL 恢复完成后全量重建索引
• AriaEngine Compaction 依赖缓存丢数据（严重） — compactLevelAsync 仅从 LRU 缓存读 SSTable，缓存未命中（单文件超缓存上限被驱逐、频繁 flush）时跳过全部文件并从 levels 移除 → 运行中数据全部不可见（重启才恢复）。改为从存储兜底加载；无有效数据时将文件放回 levels 不删除
• AriaEngine flush/compaction 失败卡死写路径（严重） — flushChain 链上任务抛错后永久 rejected，后续所有 flush/compaction 挂起。链上任务统一吞错恢复（记录告警，链继续）
• ALTER TABLE 在 IndexedDB/Hybrid/OPFS 引擎不持久化 — v0.4.1 只给 Aria 加了引擎级 alterTable，其余引擎走通用路径只改内存 schema 引用：重启后 ADD/DROP 全部回退，DROP 的行数据也残留。为 IndexedDB（持久化 schema + 重写存储行）/ Hybrid（双引擎）/ OPFS / Memory 统一实现引擎级 alterTable
• IndexedDB 事务内 DDL 崩溃（严重） — 事务内建表 commit 时 IDB 无对应 store 报错；事务内删表 IDB store 残留 → 重启幽灵表。flushToIDB 提交时 diff 内存表与 IDB store：缺失的创建（含 schema 持久化）、多余的删除（含 schema 记录清理）；commit 顺序调整为"先刷盘后提交内存快照"，失败可回滚
• Hybrid 内存/磁盘引擎共享 schema 引用污染 — reloadMemoryFromDisk 把磁盘引擎的 schema 对象直接存入内存引擎，任一引擎 ALTER 都改到对方。MemoryEngine.createTable 深拷贝 schema（全引擎受益）
• Hybrid commit 失败路径错误掩盖 — 磁盘已提交后内存提交失败时调 diskEngine.rollbackTransaction() 抛 TX_NONE 掩盖原错误；如实上报磁盘已提交状态
• AriaEngine.close 运行期状态残留 — close 后 MVCC/事务快照/savepoint 残留，重开后 beginTransaction 报 TX_ACTIVE。close 统一清理
• VACUUM 对 2-3 个文件层级不压缩 — compactLevel public 门槛与内部自动调度门槛混用（内部 4 / VACUUM 期望 2）。分离参数化

Fixed（生产就绪审计第三轮）

• Aria 事务进行中 checkpoint 截断 WAL（严重，P0） — checkpoint（tick/forceCheckpoint）在活跃事务中途执行时 truncate WAL，BEGIN/INSERT 记录被截断，事务 COMMIT 后崩溃恢复丢失整个事务数据。CheckpointManager 包装 WAL：事务活跃时跳过截断（close/repair/clearAll 仍正常截断）
• Aria dropTable / DROP_TABLE 恢复不清理二级索引（P1） — 索引 LSM 孤儿残留，重建同名表后旧索引数据污染新表（按旧值索引查询返回不匹配行）。新增 cleanupTableIndexes：dropTable、崩溃恢复、ALTER DROP 索引列统一清理
• Aria ALTER TABLE DROP 索引列残留（P1） — 删列但索引 LSM 保留，后续同名列索引数据脏
• Aria freezeMemtable 阈值逐次衰减（P2） — 新 memtable 用旧表已用大小当阈值，手动 flush 后阈值塌缩 → 频繁小文件。改回配置阈值
• Aria 事务中 DDL 静默不一致（P2） — 事务快照只覆盖行数据，createTable/dropTable/alterTable 无法回滚；与 Memory/IndexedDB 可回滚行为不一致 → 显式抛 NOT_SUPPORTED（不再静默）
• ON UPDATE 外键级联未实现（P2，声称支持但静默忽略） — 实现 ON UPDATE CASCADE/SET NULL/RESTRICT（Memory + Aria 双引擎）：更新主键时级联更新/拒绝，含二级索引与 WAL 记录，先全量 RESTRICT 检查再执行防部分修改；update 同时支持主键变更（旧键删除 + 新键落表）
• MVCC commit/rollback 全库版本遍历（P2 性能） — 大表事务 commit O(全库版本数)。按事务记录写入的 key 精准清理（O(写入数)）
• OPFS 空表重启消失 + schema/索引丢失（P1） — 表 schema 持久化到元数据文件：createTable/dropTable/alterTable/createIndex 同步；重启从 schema 恢复（空表保留、主键/索引标记/约束完整），无 schema 的旧库回退数据推断（兼容）
• OPFS dropTable 不清理 schema 记录（P1） — 重启恢复幽灵表；删表同步清理
• OPFS 并发写验证 — 审计确认内存写同步、持久化快照总是最新（单标签页无丢更新竞态），新增并发写回归测试锁定行为
• VACUUM 返回值语义 — gcVersions 返回活跃事务数改为全局提交序列号

Changed

• 测试 894 → 944（50 套件），新增 tests/v042-fixes.test.ts（23 条问题清单回归）、tests/v042-hardening.test.ts（12 条深度审计回归）与 tests/v043-hardening.test.ts（15 条生产就绪回归：事务×checkpoint、DDL 索引清理、OPFS 持久化、memtable 阈值、红黑树 5000 次随机压力、onUpdate 级联）
• 版本号升至 v0.4.2

---

[0.4.1] - 2026-08-08

Added

• AriaEngine 外键级联删除 — 对齐 Memory 引擎：CASCADE（递归多层）、SET NULL、RESTRICT（抛 FOREIGN_KEY_VIOLATION），含二级索引清理、WAL 记录、事务内可提交/回滚、环路保护
• AriaEngine.clearAll() — 重置数据库（清空后端存储/LSM/WAL/MVCC/二级索引），实例可继续使用；供演示页刷新场景与 API 用户使用
• 演示页引擎切换器 — 右上角 ⚡ Memory / 🌲 Aria 一键切换，Aria 模式每次加载 clearAll() 保证演示确定性；aria 预设文案更新（数据库即 Aria）

Changed

• 版本号升至 v0.4.1
• 测试 880 → 894（46 → 47 套件）
• AriaEngine 级联行为与 MemoryEngine 对齐：SET NULL 不影响删除返回行数

Fixed

• JOIN 主表 WHERE 不下推 — SELECT ... FROM orders o JOIN users u ... WHERE o.user_id = '1' 的 WHERE 只在 JOIN 后过滤，二级索引形同虚设。v0.4.1 将主表前缀等值条件下推到引擎（extractPushableWhere），索引真正生效
• DROP INDEX 不存在的索引静默成功 — Memory/Aria 引擎 dropIndex 对无索引列静默返回，改为抛 INDEX_NOT_FOUND
• Memory 索引查找不支持 $eq 对象形式 — SQL 解析器生成的 { $eq: value } 等值条件不走哈希索引（仅简单值走），补 $eq 分支
• 演示页预设数据被前序预设污染 — 连续点击预设时，cascade（删除 Alice/重建 orders）、truncate、alter 等会修改种子数据，后续预设（如 index）查询返回空。loadPreset 点击预设前自动重置数据库到初始状态，每个预设可预期演示
• Aria ALTER TABLE 不生效（严重） — DROP COLUMN 仅改 schema 引用，find() 返回行副本无法就地删除，存储行残留已删列值（SELECT * 仍显示）；且 ALTER 不持久化 schema，重启后列定义回退。新增引擎级 alterTable（IStorageEngine 可选接口）：Aria 重写主 LSM 移除列值 + persistSchemas + WAL UPDATE 记录，崩溃恢复后 schema 与行一致
• 裸布尔列条件不支持（严重） — WHERE done / CASE WHEN done THEN 解析失败（无比较运算符即抛错），条件被忽略导致 CASE 恒走 ELSE。parser 支持裸列真值判断（{ col: { $eq: true } }）
• Aria $in 返回重复行 — IN 子查询含重复值（如 Alice 两条订单）时 PK/二级索引 $in 逐值查找重复 push，按主键去重

---

[0.4.0] - 2026-08-08

Added

• 流式查询 API — db.queryStream(sql, onRow) / db.table(name).stream(onRow) / IStorageEngine.findStream()：
  • Aria 引擎走 LSM rangeScanLazy 惰性扫描，逐行回调不物化结果数组（大表友好）
  • Memory/Hybrid/OPFS 逐行迭代；IndexedDB 批量读入后逐行回调（保持接口一致）
  • 支持 WHERE/LIMIT/OFFSET/列投影；JOIN/GROUP BY/UNION/聚合/ORDER BY 自动回退物化
  • 用户 async 回调自动回退物化（同步扫描无法 await，避免吞 Promise）
• 多列 ON 哈希连接 — 复合等值条件（ON a.tenant = b.tenant AND a.key = b.key）走哈希连接（含顶层 $and 展开），任一右列为索引/主键即可；不适用自动回退嵌套循环
• FROM 子查询（派生表） — SELECT ... FROM (SELECT ...) AS alias WHERE ...，子查询结果作为行源，支持 WHERE/ORDER BY/LIMIT 与 JOIN 组合
• COUNT(DISTINCT col) — 聚合去重（COUNT/SUM/AVG/MIN/MAX 均支持），任意类型去重
• NULLS FIRST / NULLS LAST — ORDER BY col ASC NULLS FIRST 等，NULL 位置固定不受升降序反转
• 普通列别名 — SELECT name AS n / SELECT name n（此前仅聚合/CASE 支持别名），别名可用于 ORDER BY
• 无表查询与字符串常量列 — SELECT 1 / SELECT 'lit' AS x（无需 FROM），'' 转义与常量列投影

Fixed

• AriaEngine 崩溃恢复后已删除表/数据复活（严重，P0） — WAL 回放忽略 DROP_TABLE 而 CREATE_TABLE 无条件恢复 schema，删表后崩溃重启表+数据全部复活。v0.4.0 新增 applyDropTableRecovery() 回放删除 schema + 清除 LSM 残留
• WAL 恢复后不截断 — 每次重启重复回放 + WAL 无限膨胀。恢复完成将回放数据落盘后 wal.checkpoint() 截断
• MemoryEngine update 不维护索引（P0） — update() 后唯一约束可被绕过、按新值索引查询丢行。removeIndexEntries() 在 update/delete/级联删除/SET NULL 前清理旧值索引
• Aria 事务内读不到自己写入的行 — update/delete/count/clear 的 getAllRows() 不合并 txnSnapshot，事务内先 insert 再 update/delete 失效；统一 mergeTxnSnapshot()
• Aria TRUNCATE 不写 WAL — clear() 崩溃恢复后丢失；事务内清空走快照删除标记，提交生效
• WAL 大小阈值在 full 模式永不触发 — getBufferedBytes() 跟踪真实字节数替代缓冲计数估算
• rollback 后二级索引残留 — 事务内直接写入索引 LSM，回滚后对受影响表全量重建索引
• Savepoint 回滚 MVCC 不一致 — discardVersions() 清理版本链保留事务登记
• PK 范围查询字符串算术 bug — $gt/$gte/$lt/$lte 用 Number(v)+1 构造 key 对字符串 PK 失效；改为主 LSM 前缀扫描 + 条件过滤；主键列不再建冗余二级索引（PK $in 走多次精确查找）
• SQL 字符串 '' 标准转义 — 双引号转义此前从未生效（lexer 条件先于转义分支退出）；重写 readString
• INSERT INTO ... SELECT 位置错位（严重） — 源行 validateRow 跳过 undefined 值导致行键缺失/乱序（如 ALTER 加列后省略列插入的行），Object.values 位置映射把 age 数字填进 email 列报类型错。改为按源表 schema 列顺序/SELECT 列列表对齐，缺列不填
• ORDER BY / GROUP BY 表前缀列 — ORDER BY o.amount / GROUP BY u.name 解析失败（Expected ';' ... got "."），parser 支持 table.column 引用，executor 非 JOIN 路径剥离前缀
• 关联 EXISTS 绑定失效（严重） — SELECT u.name ... WHERE EXISTS (SELECT 1 FROM o WHERE o.user_id = u.id) 返回空：引擎按 SELECT 列投影后外层行缺 id 键，$col 绑定为 null。关联子查询路径强制 plan.columns=['*'] 取完整行；非 JOIN 路径 SELECT 列带表前缀（u.name）统一剥离
• HAVING 标量子查询失效（静默返回空） — HAVING SUM(o.amount) > (SELECT AVG(amount) FROM orders) 的 $subquery 未解析 + 聚合表达式键（SUM(o.amount)）与别名键（spent）不匹配。HAVING 先 resolveSubqueries，GROUP BY 结果维护「表达式键→别名键」映射做归一化

Changed

• 版本号升至 v0.4.0
• 测试 837 → 876（44 → 46 套件），覆盖率 81.1% → 81.5%（Lines 84.7%）

---

[0.3.2] - 2026-08-08

Added

• CASE WHEN 用于 WHERE — WHERE CASE WHEN cond THEN a ELSE b END = 'x' 逐行求值（含 NOT/AND/OR 组合）
• CASE WHEN 用于聚合 — SUM(CASE WHEN age > 18 THEN 1 ELSE 0 END)、COUNT/AVG/MIN/MAX(CASE...)、GROUP BY + CASE 非聚合列
• JOIN 哈希连接 — 等值 ON + 右表主键/索引列时，收集左表连接值 → 一次 $in 查询 → 哈希映射匹配，替代嵌套循环（INNER/LEFT JOIN，O(N+M)）；不适用自动回退
• 多标签页同步 — multiTabSync: true 配置 + BroadcastChannel：
  • SQL 写语句（INSERT/UPDATE/DELETE/DDL）自动广播表变更
  • Table API 写入（insert/insertMany/update/delete/clear/drop）自动广播
  • 其他标签页收到 external 变更事件（订阅者可见）+ Hybrid 内存自动重载
  • db.broadcastChange(table) 手动广播
• IndexedDB schema 持久化 — __metona_schema store 保存完整列定义，reopen（页面刷新/重连）后恢复；旧数据回退为"主键 + 索引 + 样例推断"

Fixed

• IndexedDB reopen 后 schema 丢失（严重） — schema 仅存内存缓存，close 后重开连接表结构即丢失（INSERT 列映射截断、UPDATE 全列失效）。v0.3.2 持久化 + 重建
• where-matcher 顶层 $not 不生效 — NOT (expr) 解析为顶层 { $not } 但被当作字段匹配，始终返回 true
• CASE 剥离后空 $not 恒假 — 引擎层执行 NOT(true) 过滤掉所有行

Changed

• 版本号升至 v0.3.2

---

[0.3.1] - 2026-08-08

Added

• CASE WHEN 表达式（SELECT 列） — CASE WHEN cond THEN value [WHEN ...] [ELSE value] END [AS alias]
  • 多 WHEN 按顺序匹配、ELSE 缺省返回 null
  • THEN/ELSE 值支持字面量（字符串/数字/布尔/null）与列引用
  • 条件支持 AND/OR/比较运算符/IS NULL 等完整 WHERE 语法
  • 引擎层返回原始行供求值（避免投影丢失条件列），与普通列混合投影
• JOIN + 关联子查询 — JOIN 结果的 WHERE 支持 EXISTS (SELECT ... WHERE o2.x = u.y) 与 $col 引用外层行，逐行绑定求值
• WAL 批量组提交 — WAL.appendBatch() 合并多条记录为一次底层写入；引擎 insert/update/delete 批量记录后一次落盘（写放大从 O(N) 降为 O(1)）
• parseWhereCondition() 导出 — 独立条件表达式解析（CASE WHEN 求值内部使用）

Fixed

• LSM pending frozen 可见性 — 异步 flush 链期间，中间冻结的 MemTable 仅存在于闭包中，读取路径不可见导致数据缺失。新增 frozenMemtables 列表，get/rangeScan/getAllEntries 遍历所有 pending frozen（新→旧）
• flush 缓存裁剪与预加载竞争 — flush 完成时的 LRU 裁剪会驱逐 prefetch 刚加载的 SSTable，导致扫描静默丢数据。prefetchRange/prefetchKeys 先等待 flush 链完成再加载
• CASE 值解析顺序 — true/false/null 字面量被误判为列引用

Changed

• 版本号升至 v0.3.1

---

[0.3.0] - 2026-08-08

Added

• SQL 多语句支持 — parseAll() 解析分号分隔的多条语句，db.query() 顺序执行并返回最后一条结果（parse() 保持单语句兼容）
• 事务语句（TCL） — BEGIN / COMMIT / ROLLBACK（支持可选 TRANSACTION 关键字），直接驱动引擎层事务，五引擎可用
• INSERT INTO ... SELECT — 支持 INSERT INTO t (cols) SELECT ...（含 WHERE 过滤、列映射）
• UNION / UNION ALL — 支持去重合并与链式组合（A UNION B UNION C），右侧结果按位置投影到左侧列结构
• CREATE INDEX / DROP INDEX — 动态二级索引：
  • CREATE [UNIQUE] INDEX idx ON table (col) / DROP INDEX idx ON table (col)
  • 五引擎实现：Memory 哈希索引 / IndexedDB 版本升级建 idx_col / OPFS 委托 / Hybrid 双写 / Aria 动态 LSM 索引
  • Aria 主键索引受保护（不可 DROP）；CREATE INDEX 对已有数据立即建索引（回填），后续写入自动同步
• EXISTS / NOT EXISTS — 支持关联子查询（WHERE EXISTS (SELECT 1 FROM o WHERE o.user_id = u.id)），逐行绑定外层上下文求值
• 别名 WHERE 修复 — WHERE u.age > 20（主表别名前缀）此前不工作，v0.3.0 字段名规范化（JOIN 路径不受影响）
• SELECT 1 常量列 — 数字字面量可作为 SELECT 列（EXISTS 子查询常见用法）
• benchmark 页面 — site/benchmark.html 浏览器内实测 Memory / Aria 引擎 × 1K/10K/50K 行的 INSERT/PK 查询/索引查询/UPDATE/DELETE 吞吐（ops/sec）
• parseAll / 新 AST 类型导出 — SelectUnionStatement / CreateIndexStatement / DropIndexStatement / BeginTransactionStatement 等

Changed

• 版本号升至 v0.3.0

Fixed

• NOT EXISTS 解析丢 EXISTS token 导致 parse 失败

---

[0.2.6] - 2026-08-08

Fixed

• AriaEngine 二级索引 SSTable 互相覆盖（严重） — 主 LSM 与二级索引 LSM 此前共享同一 sstableStore（id 空间 + meta 列表），allocateId() 返回 Date.now() 且各 LSM 从同一 meta 恢复 nextSSTableId，高频写入时 id 冲突导致索引数据文件覆盖主数据、meta 与数据错配。v0.2.6 按命名空间隔离（文件前缀 + meta key + 独立 id 序列），索引 LSM 各持独立 store
• LSM 多版本读取顺序错误（严重） — levels[] 数组按 push 追加（新文件在尾部），但 get()/rangeScan 从头遍历（旧文件优先），同一 key 跨多次 flush 更新后读到旧值；MergeIterator 去重只取"先出堆者"，不保证最新来源。v0.2.6 改为"数组头部即最新"（unshift + 按 id 降序加载），MergeIterator 显式取 sourceIndex 最小者
• LZ4 往返不一致 — ① 匹配长度超过 19 字节被截断但 si 跳过全部匹配，解压丢数据；② matchField=0 的组合 token 与纯字面量 token 格式歧义；③ 字面量累积超过 15 字节后组合 token 永远无法输出；④ 输出缓冲区 maxOut 不足导致越界写入；⑤ 压缩失败时返回原样 input，解压端无法区分。v0.2.6 重写压缩器（长匹配分段、纯字面量 token 语义明确、动态上限）
• React/Vue 集成运行时 ReferenceError — useDatabase/useSqlarkDatabase 用 import type 导入 MetonaSqlark 但运行时 new MetonaSqlark()，@ts-nocheck 掩盖此 bug，实际使用必炸。改为 value import
• sstableCache 无限增长 — SSTable 缓存无内存上限且 init() 预加载全部数据，大库 OOM。v0.2.6 引入 LRU 容量上限（bufferPoolPages × pageSize），查询前异步预加载兜底（修复缓存未命中静默返回 null 丢数据的隐患）
• integrations 子路径缺失 — README 宣称 metona-sqlark/react、metona-sqlark/vue 可用但 exports 未声明，现已补齐（react/vue 为 peer dependency，rollup external）

Changed

• Buffer Pool 配置真正生效 — bufferPoolPages 从无效配置变为 SSTable 缓存容量上限（默认 256 页 ≈ 1MB 可控内存）
• LZ4 格式变更 — 旧版本压缩数据与新解压器不兼容，使用 compression: true 的用户需重新导入数据
• SSTable 持久化串行化 — flush/compaction 改为串行链（flushChain），id 分配与持久化顺序一致，消除 fire-and-forget 竞态
• 文档数据修正 — 测试 761（41 套件）、覆盖率 81.1%（此前 91.0% 为排除 Aria 模块的陈旧数据）、体积 ~105KB / gzip ~27KB

Added

• AriaEngine 缓存内存上限测试 — 9 个测试：LRU 上限约束、驱逐后全表/PK/索引查询完整性、UPDATE/DELETE 全量作用、写路径上限、命名空间隔离回归、多版本回归、tombstone 回归
• LZ4 往返一致性测试 — 6 个往返测试（重复/文本/随机/边界长度/15 字节边界/长匹配）
• CryptoManager 加解密测试 — 7 个测试（往返/错误密码/不同 salt/实例隔离/全局兼容层/4KB 页面）
• React/Vue hooks 集成测试 — 16 个测试（jest.mock 零依赖：mount 执行、错误路径、refresh、注入防护、数据库初始化）
• jest.setup.js WebCrypto polyfill — jsdom 环境补齐 crypto.subtle 支持 AES-GCM

---

[0.2.5] - 2026-07-29

Fixed

• 版本号统一 — constants.ts VERSION 从 '0.2.0' 更新为 '0.2.5'，修正 index.ts/utils.ts/CONTRIBUTING.md 中过时的版本注释和数据
• AriaEngine OPFS 后端映射 — core.ts 中 mode: 'aria' + diskEngine: 'opfs' 时实际使用 Memory 后端的 bug 已修复
• _onError 接入执行路径 — query()/defineTable()/dropTable()/transaction()/importTable() 的 catch 路径现在调用 _onError 全局错误回调
• maxRowsPerQuery 生效 — QueryExecutor 构造时接收 maxRowsPerQuery 参数，SELECT 结果在返回前截断
• WAL full 模式真正同步 — WAL.append() 改为 async，full 模式下 await this.store.append() 真正等待写入完成，不再 fire-and-forget
• PluginManager.install 传 db 实例 — register() 增加可选 db 参数，core.ts 初始化时传入 this，插件可获取 db 引用

Changed

• SSTableReader 二分查找统一 — locateBlockGE/locateBlockLE 从线性扫描改为二分查找，rangeScan 性能在大型 SSTable 下不再退化
• crypto 实例化 — 全局状态改为 CryptoManager 类，每个 AriaEngine 实例可拥有独立加密配置，保留全局函数向后兼容
• compactLevelSync 接口公开化 — LSM 新增 public compactLevel() 方法，vacuum() 不再使用 as any 绕过 private 访问
• WAL 大小阈值接入 checkpoint — CheckpointManager 接收 walSizeThreshold 参数，WAL 缓冲超阈值时自动触发 checkpoint

Added

• ALTER TABLE 语法 — 支持 ALTER TABLE ... ADD COLUMN / DROP COLUMN（含可选 COLUMN 关键字）
• TRUNCATE TABLE 语法 — 支持 TRUNCATE TABLE name 快速清空表数据
• MVCC 接入读写路径 — 事务内 insert/update/delete 调用 mvcc.writeVersion/mvcc.deleteVersion，版本链作为 undo log
• IndexedDB 索引利用 — IndexedDBEngine.find 等值查询时优先使用 IDB 索引（idx_col 命名约定），避免全量 getAll
• SQL 注入防护 — React useTable / Vue useSqlarkTable 增加表名合法性校验（/^[a-zA-Z_][a-zA-Z0-9_]*$/）

---

[0.2.4] - 2026-07-27

Added

• 二级索引 — 每列可独立维护 LSM Tree 索引，$eq/$in/$gt/$lt 走索引 O(log n)
• MVCC 接入引擎 — MVCCManager 正式投产，替换 ad-hoc txnSnapshot
• MVCC 自动 GC — 每 10 次 checkpoint 自动回收过旧版本（保留最新 100 个）
• Bloom Filter 序列化 — 写入 SSTable footer + 读取时加载 + 查询时 probe 快速否定
• WAL 大小阈值 — walSizeThreshold 配置（默认 16MB），超阈值强制 checkpoint
• 内存预算 — maxMemoryMB 配置（默认 64MB）

Changed

• WAL 默认同步模式 — walSyncMode 从 'batch' 改为 'full'，消除 crash 丢数据风险
• 查询优化 — tryIndexLookup 扩展支持非 PK 列索引查找

---

[0.2.3] - 2026-07-27

Fixed

• RB-Tree fixDelete 完整实现 — 补全标准红黑树删除修复，保证 O(log n)
• LSM SSTable 缓存预热 — init() 预加载所有 SSTable，消除 cache miss
• OPFS 数据恢复 — open() 自动从 OPFS 文件加载已有表数据到内存
• Aria WAL 事务恢复 — 两阶段恢复：仅回放已提交事务，未提交数据不回放
• LZ4 格式修复 — 重写 token 格式，消除中间字面量 token 歧义

---

[0.2.2] - 2026-07-27

Added

• OPFS 自研存储后端 — AriaEngine 新增 OPFSBackend，纯浏览器文件系统 API，零 IndexedDB 依赖
  • 每个 key 对应一个二进制文件，存储在 navigator.storage.getDirectory() 下
  • 支持 read/write/delete/list/exists/clear 完整接口
  • 页面文件（4KB）、WAL 日志、Schema、SSTable 全部存储为独立文件
  • { dbName }/pg_1, { dbName }/__wal_0, { dbName }/__aria_schemas ...

Changed

• AriaEngineConfig.storageBackend 已支持 'opfs'，AriaEngine.open() 自动选择 OPFSBackend

---

[0.2.1] - 2026-07-27

Fixed

• WAL CRC 校验验证 — 恢复时计算并验证 CRC32，损坏记录自动跳过并告警
• Hybrid 引擎提交顺序 — commit 先写磁盘再写内存，磁盘失败回滚内存，消除数据不一致风险
• RESTRICT 外键行为修正 — 检测到引用行时抛出 FOREIGN_KEY_VIOLATION，不再静默保留孤儿
• SSTable rangeScan 边界保护 — 空索引或 startBlockIdx > endBlockIdx 时安全返回

Added

• ColumnDef 约束激活 — maxLength/min/max 约束在 checkFieldType 中正式生效
• 查询结果上限 — DatabaseConfig.maxRowsPerQuery（默认 0 不限制），防止超大结果集 OOM
• onError 全局回调 — 配置中的 onError 回调实际接入 CRUD 异常路径
• debug 调试模式 — DatabaseConfig.debug: true 输出 [MetonaSqlark:name] 前缀的结构化日志
• 浏览器兼容性声明 — README 增加 Chrome 80+/Firefox 80+/Safari 14+/Edge 80+ 支持矩阵

Changed

• MemoryEngine RESTRICT 外键行为：从"不级联保留孤儿"改为"禁止删除抛异常"
• Hybrid 引擎 commitTransaction 磁盘优先于内存
• DB_DEFAULTS 新增 maxRowsPerQuery: 0 和 debug: false

---

[0.2.0] - 2026-07-27

Added

• AriaEngine 自研存储引擎 — 基于 LSM-Tree 的页面式存储引擎，19 个新模块，~3500 行 TypeScript
  • 页面格式层 (page/): 4KB Slotted Page 编解码、Tuple 二进制序列化、CRC32 校验
  • Buffer Pool (buffer/): LRU 页面缓存 + 驱逐策略，可控内存占用
  • LSM-Tree 索引 (index/): MemTable (红黑树) + 多级 SSTable + Leveled Compaction
  • Bloom Filter (index/bloom.ts): FNV-1a + Murmur 双哈希，快速键否定判定
  • SSTable 构建器/读取器 (index/sstable_builder.ts, sstable.ts): 二分查找 + 范围扫描
  • Merge Iterator (index/merge_iterator.ts): 最小堆多路归并，去重保留最新值
  • WAL (wal/): 二进制日志格式 (LSN/type/txnId/table/key/json/CRC) + Checkpoint 管理
  • MVCC (transaction/mvcc.ts): 版本链 + 快照隔离 + GC
  • 存储后端 (store/): IndexedDB / Memory 双后端抽象
  • LZ4 压缩 (compression/lz4.ts): 简易页面级压缩
• mode: 'aria' — 新增存储模式，可通过 MetonaSqlark.create({ mode: 'aria' }) 激活
• Schema 持久化 — 表结构自动保存到 __aria_schemas，重启自动恢复
• SSTable 元数据管理 — SSTable 索引信息持久化，启动时自动扫描加载
• 事务感知 CRUD — insert/update/delete 在事务中缓冲到 snapshot，commit 批量写入 LSM
• 244 个 AriaEngine 专项测试 — 覆盖生命周期/表管理/CRUD/事务/持久化/SQL 集成/页面格式/LSM/压缩

Changed

• StorageMode 类型新增 'aria'
• STORAGE_MODES 数组新增 'aria'
• createEngine() 支持 mode: 'aria' 分支
• 测试从 318 → 526，套件从 20 → 27
• 新增 7 个模块级测试文件：aria-page、aria-index、aria-sstable、aria-buffer、aria-wal-mvcc、aria-compress、aria
• LRUList 修复 size 追踪 bug
• WAL 存储改为按记录独立 key（避免拼接缓冲区越界）
• CheckpointManager 解耦 BufferPool 依赖

Fixed

• LZ4 压缩无限循环 — 字面量分支在发现匹配后回退导致 litLen=0 死循环，CI 卡死根因
• SSTableReader.get() 自比较 bug — 参数 key 被循环变量遮蔽导致永远返回第一条
• CheckpointManager 测试 null 引用 — 改为 Mock 对象避免 TypeError 导致进程无法退出
• IndexedDB 持久化测试 — 替换为 Memory Backend 验证，消除 fake-indexeddb timer 堆积
• LSM.flush() 不必要 setTimeout — 替换为 Promise.resolve()，消除额外 timer 延迟

---

[0.1.14] - 2026-07-26

Fixed

• IndexedDB 事务原子性: flushToIDB 改为单 IDB 事务包裹 clear+insert，消除崩溃丢数据风险
• 多标签页冲突: open() 添加 onversionchange 监听，其他标签页升级版本时自动关闭过期连接
• Memory 引擎幂等: open() 重复调用安全无副作用
• 关闭时清理 onversionchange 监听器，防止内存泄漏

---

[0.1.13] - 2026-07-26

Added

• 事务回滚机制: IStorageEngine 新增 beginTransaction/commitTransaction/rollbackTransaction 接口
  • MemoryEngine: 快照式回滚（深拷贝 tables/schemas/indexes）
  • IndexedDBEngine: 延迟写入策略（事务中仅写内存，commit 批量刷 IDB）
  • OPFSEngine: 快照式回滚（commit 批量写文件）
  • HybridEngine: 同时代理内存+磁盘引擎事务
• 子查询支持: SQL Parser + Executor 支持 IN (SELECT ...) 和 op (SELECT ...) 子查询
  • AST 新增 SubqueryExpression 类型
  • Parser 在 IN 和比较运算符后检测子查询
  • Executor 新增 resolveSubqueries() 递归解析，自动执行子查询并替换为具体值
• 外键级联操作: ColumnDef 新增 onDelete/onUpdate 选项
  • 支持 CASCADE（递归级联删除）、SET NULL、RESTRICT
  • SQL Parser 解析 REFERENCES table(col) ON DELETE CASCADE ON UPDATE CASCADE
  • MemoryEngine 内置 cascadeDelete() 递归级联逻辑
• 连接池管理: MetonaSqlark.connect() 静态方法
  • 同名数据库复用已打开实例，引用计数管理
  • db.disconnect() 释放连接，归零自动 close
  • MetonaSqlark.disconnectAll() 强制关闭所有连接

Changed

• TransactionManager.execute() 调用引擎层 begin/commit/rollback 实现真正原子性
• IndexedDBEngine CRUD 事务感知：活跃事务中延迟 IDB 写入
• ASTColumnDef / astColumnToColumnDef 支持 references/onDelete/onUpdate 透传

Fixed

• IndexedDBEngine 事务中 find/count 从内存缓存读取（保证读到未提交变更）
• SQL Parser parseColumnDef 循环条件扩展，避免 REFERENCES 语法解析中断

---

[0.1.12] - 2026-07-26

Added

• MeSqlark 别名导出，与 MetonaSqlark 完全等价
• metona-sqlark.cjs.js CommonJS 构建产物
• 完善的 where-matcher.ts 消除 220+ 行重复代码
• $col 列引用支持 JOIN ON 条件
• $and/$or 嵌套支持（字段级 + 顶层）
• $not 逻辑非操作符
• $like 正则缓存加速
• projectColumns 列投影支持 table.column 格式
• DISTINCT 去重支持（O(n) 时间，列值拼接优化）
• 测试覆盖率提升至 93.46%（264 测试/15 套件）

Changed

• where-matcher 统一 MemoryEngine / IndexedDBEngine / Executor 的 WHERE 逻辑
• JOIN ON 匹配支持 $col 语法
• LIKE 正则改为缓存式编译
• Executor DISTINCT 用列值拼接代替 JSON.stringify
• JOIN 嵌套循环连接优化：避免 ON 时对象扩散

Fixed

• IndexedDBEngine update/delete 方法正确同步内存缓存
• OPFSEngine getTableNames 兼容 entries() 返回值
• SQL Parser 正确处理字符串转义字符
• SQL Parser 正确处理表别名（无 AS 关键字）
• SQL Parser 解析 IS NULL / IS NOT NULL / NOT LIKE
• peekTokenIs 方法正确暴露给语法分析
• 多处边界条件空值/假值处理

---

[0.1.11] - 2026-07-25

Added

• React 集成 hooks: useQuery, useTable, useDatabase
• Vue 集成 composables: useSqlarkQuery, useSqlarkTable, useSqlarkDatabase
• 发布订阅系统: subscribe(), emit()
• 数据迁移系统: addMigration(), migrateTo()
• 导入导出: exportTable(), exportAll(), importTable()
• 完整 SQL 解析器: Lexer + Parser（递归下降）
• SQL 支持: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE
• JOIN 支持: INNER, LEFT, RIGHT, CROSS
• GROUP BY + HAVING + 聚合函数 (COUNT, SUM, AVG, MIN, MAX)
• DISTINCT, ORDER BY, LIMIT, OFFSET
• WHERE 条件: AND, OR, NOT, IN, LIKE, IS NULL
• Query Builder 链式 API: select().where().orderBy().limit().execute()
• 插件系统: 14 种生命周期钩子 + PluginManager
• Metadata 系统: ColumnDef 完整约束 (type/primaryKey/required/unique/index/default/references/maxLength/min/max)

Changed

• 架构重构为分层设计：Engine → QueryExecutor → Table/QueryBuilder → SQL Parser → Public API
• AST 作为统一中间表示，SQL 和 QueryBuilder 行为完全一致
• 测试框架完善：core / edge / groupby / join / query-system / sql / table / engine / transaction / plugin / hybrid 全覆盖

---

[0.0.1] - 2026-07-24

Added

• 初始项目骨架
• TypeScript 配置（严格模式）
• Rollup 构建（UMD / ESM / CJS / min / .d.ts）
• Jest + jsdom 测试环境
• ESLint + @typescript-eslint
• Gitea Actions CI 工作流
• 示例站点（index / demo / docs）
• 构建脚本 build.sh