fix(P2): v0.6.3 原子性/一致性/资源治理 — 8 项修复 + 12 回归

- KVStore 混合写单记录原子：新增 writeBatch（put+delete 同一条日志记录）， KVStoreEngine 全部混合写路径统一（兑现真原子宣称，崩溃无新旧行并存） - WAL full 模式写入失败抛错（此前 console.warn 吞错 → 崩溃即丢且无感知） - MemoryEngine SET NULL 级联索引残留：复用 removeIndexEntries（消除虚假 UNIQUE_VIOLATION） - delete 级联两阶段：先全量 RESTRICT 预检（沿 CASCADE 链递归）再执行，无部分级联（Memory/Aria 对齐） - BufferPool 驱逐同步清理 pages Map（EvictionManager onRemove 回调，内存预算真实生效） - MVCC commit 清理已提交版本（版本链仅作事务内 undo，消除行数据双份常驻） - LSM.flush 重复入链修复（入链即置空 immutable）+ frozenMemtables 可见性时序 - rollbackToSavepoint 重建受影响表二级索引（消除过期索引条目）测试 1114 → 1126（71 套件）；行覆盖率 89.7%；版本 0.6.3
2026-08-13 10:30:39 +08:00
parent ef1934a38c
commit f97c5a6001
26 changed files with 1075 additions and 250 deletions
@@ -30,7 +30,7 @@ class DatabaseError extends Error {
 // ---------------------------------------------------------------------------
 //  版本
 // ---------------------------------------------------------------------------
-const VERSION = '0.6.2';
+const VERSION = '0.6.3';

 /**
 * metona-sqlark Shared WHERE Matcher — 统一的条件匹配逻辑
@@ -473,7 +473,16 @@ class MemoryEngine {
                toDelete.push(pk);
            }
        }
-        // 级联删除：检查引用此表的其他表
+        // v0.6.3-fix: 级联两阶段 —— 先对全部待删行做 RESTRICT 预检（沿 CASCADE 链递归），
+        // 任何一行违规则整体拒绝。此前逐行执行：第 N 行 RESTRICT 抛错时，前 N-1 行的
+        // 级联子行已被删除、父行未删 → 无事务下部分级联（数据不一致）
+        const restrictVisited = new Set();
+        for (const pk of toDelete) {
+            const row = table.get(pk);
+            if (row)
+                this.checkCascadeRestrict(tableName, pk, restrictVisited);
+        }
+        // 级联删除：检查引用此表的其他表（RESTRICT 已预检通过，此阶段不再抛错）
        let cascadeCount = 0;
        for (const pk of toDelete) {
            const row = table.get(pk);
@@ -484,6 +493,43 @@ class MemoryEngine {
            table.delete(pk);
        return toDelete.length + cascadeCount;
    }
+    /**
+     * v0.6.3: RESTRICT 预检（delete 级联两阶段之一）。
+     * 递归沿 CASCADE 链检查引用表：RESTRICT 引用存在依赖行则抛 FOREIGN_KEY_VIOLATION。
+     */
+    checkCascadeRestrict(tableName, pkValue, visited) {
+        const visitKey = `${tableName}:${pkValue}`;
+        if (visited.has(visitKey))
+            return;
+        visited.add(visitKey);
+        for (const [refTableName, refSchema] of this.schemas) {
+            if (refTableName === tableName)
+                continue;
+            for (const [colName, colDef] of Object.entries(refSchema.columns)) {
+                if (!colDef.references || !colDef.onDelete)
+                    continue;
+                const [refTable] = colDef.references.split('.');
+                if (refTable !== tableName)
+                    continue;
+                const refTableData = this.tables.get(refTableName);
+                if (!refTableData)
+                    continue;
+                const refPks = [];
+                for (const [refPk, refRow] of refTableData) {
+                    if (String(refRow[colName]) === pkValue)
+                        refPks.push(refPk);
+                }
+                if (colDef.onDelete === 'RESTRICT' && refPks.length > 0) {
+                    throw new DatabaseError(`Cannot delete from "${tableName}": foreign key "${colName}" in "${refTableName}" has dependent rows`, 'FOREIGN_KEY_VIOLATION');
+                }
+                if (colDef.onDelete === 'CASCADE') {
+                    for (const refPk of refPks) {
+                        this.checkCascadeRestrict(refTableName, refPk, visited);
+                    }
+                }
+            }
+        }
+    }
    async count(tableName, query) {
        this.ensureTable(tableName);
        const table = this.tables.get(tableName);
@@ -778,14 +824,12 @@ class MemoryEngine {
                    for (const refPk of toDelete) {
                        const refRow = refTableData.get(refPk);
                        if (refRow) {
-                            // v0.3.3: 外键列置空后同步更新索引
-                            if (refRow[colName] !== undefined && refRow[colName] !== null) {
-                                const pks = this.indexes.get(refTableName)?.get(colName);
-                                if (pks) {
-                                    pks.get(refRow[colName])?.delete(refPk);
-                                }
-                            }
+                            // v0.6.3-fix: 复用 removeIndexEntries 清理旧值索引 —— 此前手动
+                            // `pks.get(v)?.delete(pk)` 后遗留空 Set → checkUniqueness 对旧值
+                            // 永久误报 UNIQUE_VIOLATION（外键列带 unique 约束时）
+                            this.removeIndexEntries(refTableName, refRow, refPk);
                            refRow[colName] = null;
+                            this.updateIndexes(refTableName, refRow, refPk);
                        }
                    }
                }
@@ -1573,6 +1617,19 @@ class KVStore {
            await this.appendRecord({}, keys);
        });
    }
+    /**
+     * v0.6.3: 多 key 混合原子写（put + delete 编码进同一条日志记录）。
+     * 此前 KVStoreEngine 的 delete/update 主键变更等路径 putMany 与 deleteMany
+     * 分两次调用 = 两条记录：崩溃在两条记录之间 → 新旧行并存（重复行/脏数据），
+     * 与"一条日志记录 = 真原子"宣称不符。此方法保证混合操作全有或全无。
+     */
+    async writeBatch(puts, deletes) {
+        if (Object.keys(puts).length === 0 && deletes.length === 0)
+            return;
+        await this.enqueue(async () => {
+            await this.appendRecord(puts, deletes);
+        });
+    }
    /**
     * v0.6.1: 追加写入（value 拼接语义）— aria WAL 分片等追加型数据用。
     * 日志记录 APPEND 类型（O(chunk) 高效），恢复时按 seq 顺序拼接，
@@ -1772,7 +1829,7 @@ class KVStore {
 * - 读：始终走内存（写路径同步落盘，重启从 KVStore 恢复）
 * - 写：内存先行 + KVStore 增量持久化（insert 增量 putMany；update/delete 受影响行重写；
 *   主键变更/级联场景整表 diff；全部原子）
- * - 事务：内存快照 + commit 时受影响表原子 flush（putMany 单记录 = 真原子，
+ * - 事务：内存快照 + commit 时受影响表原子 flush（writeBatch 单记录 = 真原子，
 *   此前 IndexedDBEngine 依赖 IDB 事务，现在完全自研）
 *
 * 数据布局（KVStore keys）:
@@ -1937,10 +1994,7 @@ class KVStoreEngine {
        await this.persistSchema();
        // 删除该表全部行（KV 中残留清理）
        const diff = await this.collectTableDiff(tableName);
-        if (Object.keys(diff.puts).length > 0)
-            await this.kv.putMany(diff.puts);
-        if (diff.deletes.length > 0)
-            await this.kv.deleteMany(diff.deletes);
+        await this.kv.writeBatch(diff.puts, diff.deletes);
    }
    async hasTable(tableName) {
        this.ensureOpen();
@@ -1966,10 +2020,7 @@ class KVStoreEngine {
        if (action === 'DROP') {
            // 重写存储行（移除该列）
            const diff = await this.collectTableDiff(tableName);
-            if (Object.keys(diff.puts).length > 0)
-                await this.kv.putMany(diff.puts);
-            if (diff.deletes.length > 0)
-                await this.kv.deleteMany(diff.deletes);
+            await this.kv.writeBatch(diff.puts, diff.deletes);
        }
    }
    // ---- CRUD ----
@@ -2051,10 +2102,7 @@ class KVStoreEngine {
            }
        }
        // 单次原子写（一条日志记录 = 真原子，v0.6.1）
-        if (Object.keys(puts).length > 0)
-            await this.kv.putMany(puts);
-        if (deletes.length > 0)
-            await this.kv.deleteMany(deletes);
+        await this.kv.writeBatch(puts, deletes);
        return count;
    }
    async delete(tableName, query) {
@@ -2076,10 +2124,7 @@ class KVStoreEngine {
            Object.assign(puts, diff.puts);
            deletes.push(...diff.deletes);
        }
-        if (Object.keys(puts).length > 0)
-            await this.kv.putMany(puts);
-        if (deletes.length > 0)
-            await this.kv.deleteMany(deletes);
+        await this.kv.writeBatch(puts, deletes);
        return count;
    }
    async count(tableName, query) {
@@ -2094,10 +2139,7 @@ class KVStoreEngine {
            return;
        }
        const diff = await this.collectTableDiff(tableName);
-        if (Object.keys(diff.puts).length > 0)
-            await this.kv.putMany(diff.puts);
-        if (diff.deletes.length > 0)
-            await this.kv.deleteMany(diff.deletes);
+        await this.kv.writeBatch(diff.puts, diff.deletes);
    }
    // ---- 动态索引 ----
    async createIndex(tableName, column, unique) {
@@ -2152,10 +2194,7 @@ class KVStoreEngine {
                }
            }
        }
-        if (Object.keys(puts).length > 0)
-            await this.kv.putMany(puts);
-        if (deletes.length > 0)
-            await this.kv.deleteMany(deletes);
+        await this.kv.writeBatch(puts, deletes);
        // 事务内 DDL 的 schema 一并持久化
        if (this.txSchemaChanged) {
            await this.persistSchema();
@@ -2236,7 +2275,7 @@ class KVStoreEngine {
    }
    /**
     * v0.6.1: 整表 diff 收集（不落盘）：内存行全部 put + KV 残留行删除。
-     * 调用方合并到单次原子 putMany/deleteMany（多表操作真原子）。
+     * 调用方合并到单次原子 writeBatch（put+delete 同一条日志记录，多表操作真原子）。
     */
    async collectTableDiff(tableName) {
        const prefix = this.rowPrefix(tableName);
@@ -4161,20 +4200,28 @@ class LSM {
        // memtable flush 的 saveMeta 读到中间态列表（含 compaction 产物）→ 覆盖产物
        // 引用 → compaction 产物变孤儿 → 索引/主表数据静默丢失（优雅关闭后重开丢 75%）。
        // 挂链后按序执行（memtable flush 在 compaction 之后），meta 无竞态。
+        //
+        // v0.6.3-fix: ① 入链后立即置空 immutable —— 此前 freezeMemtable 会把同一张
+        // immutable 再次入链 → 重复 SSTable（2 行 flush 出 3 个文件）；② frozenMemtables
+        // 保持到链排空后再清理 —— 此前入链后立即清空，链执行期间并发读看不到冻结数据
+        // （短暂数据不可见窗口）。
        if (this.immutableMemtable) {
            const frozen = this.immutableMemtable;
            this.flushChain = this.enqueueOnChain(() => this.flushImmutableAsync(frozen));
+            this.immutableMemtable = null;
        }
        if (this.memtable.getEntryCount() > 0) {
            this.freezeMemtable();
            const frozen = this.immutableMemtable;
            if (frozen) {
                this.flushChain = this.enqueueOnChain(() => this.flushImmutableAsync(frozen));
+                this.immutableMemtable = null;
            }
        }
-        this.frozenMemtables = [];
        // 刷盘完成后级联调度可能触发 compaction → 排空到稳定
        await this.drainChain();
+        // 清理空残留冻结表（flushImmutableAsync 完成时已自行移除已落盘的）
+        this.frozenMemtables = this.frozenMemtables.filter((f) => f.getEntryCount() > 0);
    }
    async clear() {
        // v0.4.3-fix: 清空前排空后台任务（避免 compaction 在清空后写回残留 meta/数据）
@@ -4401,14 +4448,10 @@ class WAL {
        };
        const bytes = this.encodeRecord(fullRecord);
        if (this.syncMode === 'full') {
-            try {
-                await this.store.append(bytes);
-                this.bufferedBytes += bytes.byteLength;
-            }
-            catch {
-                // eslint-disable-next-line no-console
-                console.warn('[AriaEngine WAL] Failed to append record');
-            }
+            // v0.6.3-fix: 写入失败必须抛给调用方 —— 此前仅 console.warn 吞错：
+            // 内存已提交而 WAL 缺失，崩溃即丢且调用方无感知。
+            await this.store.append(bytes);
+            this.bufferedBytes += bytes.byteLength;
        }
        else if (this.syncMode === 'batch') {
            this.buffer.push(bytes);
@@ -4427,14 +4470,9 @@ class WAL {
        }
        const combined = this.mergeChunks(chunks);
        if (this.syncMode === 'full') {
-            try {
-                await this.store.append(combined);
-                this.bufferedBytes += combined.byteLength;
-            }
-            catch {
-                // eslint-disable-next-line no-console
-                console.warn('[AriaEngine WAL] Failed to append batch record');
-            }
+            // v0.6.3-fix: 同 append —— 批量写入失败抛给调用方（不再吞错）
+            await this.store.append(combined);
+            this.bufferedBytes += combined.byteLength;
        }
        else if (this.syncMode === 'batch') {
            this.buffer.push(combined);
@@ -5495,17 +5533,21 @@ class MVCCManager {
            throw new Error(`Transaction ${txnId} not found`);
        txn.state = TransactionState.COMMITTED;
        this.globalCommitLsn++;
-        // v0.4.2-fix: 仅标记本事务写入的版本（此前遍历全库 versionStore）
+        // v0.6.3-fix: 已提交版本直接清理 —— 快照读取已移除（v0.5.1），版本链仅作
+        // 事务内 undo 记录（rollback/savepoint 用），提交后 LSM 持有权威数据。
+        // 此前 commit 仅标记 committed → versionStore 随写入量无限增长（行数据双份常驻）。
        const writeKeys = this.txnWriteKeys.get(txnId);
        if (writeKeys) {
            for (const tableKey of writeKeys) {
                const versions = this.versionStore.get(tableKey);
                if (!versions)
                    continue;
-                for (const version of versions) {
-                    if (version.txnId === txnId) {
-                        version.committed = true;
-                    }
+                const filtered = versions.filter((v) => v.txnId !== txnId);
+                if (filtered.length === 0) {
+                    this.versionStore.delete(tableKey);
+                }
+                else {
+                    this.versionStore.set(tableKey, filtered);
                }
            }
        }
@@ -5747,10 +5789,16 @@ class LRUList {
 * 驱逐管理器 — 当 Buffer Pool 满时驱逐页面。
 */
 class EvictionManager {
-    constructor(capacity, onEvict) {
+    /**
+     * @param onEvict 驱逐脏页时的写回回调
+     * @param onRemove v0.6.3: 页面被驱逐时的回调（BufferPool 用于同步清理 pages Map；
+     *   此前驱逐只清 LRU 链表，pages Map 无限增长 → 1MB 内存预算形同虚设）
+     */
+    constructor(capacity, onEvict, onRemove) {
        this.lru = new LRUList();
        this.capacity = capacity;
        this.onEvict = onEvict;
+        this.onRemove = onRemove;
    }
    /** 访问页面，更新 LRU */
    access(page) {
@@ -5783,6 +5831,7 @@ class EvictionManager {
                victim.dirty = false;
            }
            this.lru.remove(victim);
+            this.onRemove?.(victim);
            evicted++;
        }
        return evicted;
@@ -5830,6 +5879,10 @@ class BufferPool {
                await this.pageIO.writePage(page.pageId, page.data);
                page.dirty = false;
            }
+        }, (page) => {
+            // v0.6.3-fix: 驱逐时同步从 pages Map 移除 —— 此前仅清 LRU 链表，
+            // pages Map 保留全部历史页面 → 内存无限增长（1MB 预算失效）
+            this.pages.delete(page.pageId);
        });
    }
    // -----------------------------------------------------------------------
@@ -6822,6 +6875,18 @@ class AriaEngine {
        const walRecords = [];
        // v0.4.1: 外键级联（环路保护）
        const visited = new Set();
+        // v0.6.3-fix: 级联两阶段 —— 先对全部匹配行做 RESTRICT 预检（沿 CASCADE 链递归），
+        // 否则第 N 行 RESTRICT 抛错时前 N-1 行的级联已执行 → 无事务部分级联（数据不一致）
+        const matchedPks = [];
+        for (const row of rows) {
+            if (!query.where || Object.keys(query.where).length === 0 || matchWhere(row, query.where)) {
+                matchedPks.push(String(row[this.tablePKs.get(tableName)]));
+            }
+        }
+        const restrictVisited = new Set();
+        for (const pkValue of matchedPks) {
+            await this.checkCascadeRestrict(tableName, pkValue, restrictVisited);
+        }
        for (const row of rows) {
            const pkCol = this.tablePKs.get(tableName);
            const key = `${tableName}:${row[pkCol]}`;
@@ -6853,6 +6918,38 @@ class AriaEngine {
        this.trimAllCaches();
        return count;
    }
+    /**
+     * v0.6.3: RESTRICT 预检（delete 级联两阶段之一，与 MemoryEngine 对齐）。
+     * 递归沿 CASCADE 链检查引用表：RESTRICT 引用存在依赖行则抛 FOREIGN_KEY_VIOLATION。
+     */
+    async checkCascadeRestrict(tableName, pkValue, visited) {
+        const visitKey = `${tableName}:${pkValue}`;
+        if (visited.has(visitKey))
+            return;
+        visited.add(visitKey);
+        for (const [refTableName, refSchema] of this.schemas) {
+            if (refTableName === tableName)
+                continue;
+            for (const [colName, colDef] of Object.entries(refSchema.columns)) {
+                if (!colDef.references || !colDef.onDelete)
+                    continue;
+                const [refTable] = colDef.references.split('.');
+                if (refTable !== tableName)
+                    continue;
+                const refRows = await this.getAllRows(refTableName);
+                const matched = refRows.filter((r) => String(r[colName]) === pkValue);
+                if (colDef.onDelete === 'RESTRICT' && matched.length > 0) {
+                    throw new DatabaseError(`Cannot delete from "${tableName}": foreign key "${colName}" in "${refTableName}" has dependent rows`, 'FOREIGN_KEY_VIOLATION');
+                }
+                if (colDef.onDelete === 'CASCADE') {
+                    const refPkCol = this.tablePKs.get(refTableName);
+                    for (const refRow of matched) {
+                        await this.checkCascadeRestrict(refTableName, String(refRow[refPkCol]), visited);
+                    }
+                }
+            }
+        }
+    }
    /**
     * v0.4.1: 外键级联规则 — 对齐 MemoryEngine.cascadeDelete 行为。
     * 删除 tableName 主键为 pkValue 的行前，检查引用它的所有表：
@@ -7245,6 +7342,16 @@ class AriaEngine {
        const sp = this.savepoints.get(name);
        if (!sp)
            throw new DatabaseError(`Savepoint "${name}" not found`, 'SAVEPOINT_NOT_FOUND');
+        // v0.6.3-fix: 记录当前快照涉及的表（回滚后重建索引）—— 此前事务内直写
+        // 索引 LSM，savepoint 回滚只还原快照 → savepoint 之后的索引条目残留
+        const affectedTables = new Set();
+        if (this.txnSnapshot) {
+            for (const key of this.txnSnapshot.keys()) {
+                const idx = key.indexOf(':');
+                if (idx > 0)
+                    affectedTables.add(key.slice(0, idx));
+            }
+        }
        // 恢复到 savepoint 时的快照
        this.txnSnapshot = sp.snapshot ? new Map(sp.snapshot) : null;
        // v0.3.3: 清理该事务在 MVCC 版本链中的全部记录（快照已含正确数据，
@@ -7260,6 +7367,12 @@ class AriaEngine {
            if (found)
                this.savepoints.delete(k);
        }
+        // v0.6.3-fix: 重建受影响表二级索引（消除 savepoint 之后的过期索引条目）
+        for (const tableName of affectedTables) {
+            if (this.schemas.has(tableName)) {
+                await this.reindexTable(tableName);
+            }
+        }
    }
    async releaseSavepoint(name) {
        if (!this.savepoints.has(name))