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
@@ -214,4 +214,4 @@ export class DatabaseError extends Error {
 //  版本
 // ---------------------------------------------------------------------------

-export const VERSION = '0.6.2';
+export const VERSION = '0.6.3';
@@ -101,12 +101,19 @@ export type EvictionCallback = (page: PageHandle) => Promise<void>;
 export class EvictionManager {
  private lru: LRUList;
  private onEvict: EvictionCallback;
+  private onRemove?: (page: PageHandle) => void;
  private capacity: number;

-  constructor(capacity: number, onEvict: EvictionCallback) {
+  /**
+   * @param onEvict 驱逐脏页时的写回回调
+   * @param onRemove v0.6.3: 页面被驱逐时的回调（BufferPool 用于同步清理 pages Map；
+   *   此前驱逐只清 LRU 链表，pages Map 无限增长 → 1MB 内存预算形同虚设）
+   */
+  constructor(capacity: number, onEvict: EvictionCallback, onRemove?: (page: PageHandle) => void) {
    this.lru = new LRUList();
    this.capacity = capacity;
    this.onEvict = onEvict;
+    this.onRemove = onRemove;
  }

  /** 访问页面，更新 LRU */
@@ -145,6 +152,7 @@ export class EvictionManager {
      }

      this.lru.remove(victim);
+      this.onRemove?.(victim);
      evicted++;
    }

@@ -44,6 +44,10 @@ export 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);
    });
  }

@@ -871,6 +871,19 @@ export class AriaEngine implements IStorageEngine {
    // v0.4.1: 外键级联（环路保护）
    const visited = new Set<string>();

+    // v0.6.3-fix: 级联两阶段 —— 先对全部匹配行做 RESTRICT 预检（沿 CASCADE 链递归），
+    // 否则第 N 行 RESTRICT 抛错时前 N-1 行的级联已执行 → 无事务部分级联（数据不一致）
+    const matchedPks: string[] = [];
+    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<string>();
+    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]}`;
@@ -907,6 +920,39 @@ export class AriaEngine implements IStorageEngine {
    return count;
  }

+  /**
+   * v0.6.3: RESTRICT 预检（delete 级联两阶段之一，与 MemoryEngine 对齐）。
+   * 递归沿 CASCADE 链检查引用表：RESTRICT 引用存在依赖行则抛 FOREIGN_KEY_VIOLATION。
+   */
+  private async checkCascadeRestrict(tableName: string, pkValue: string, visited: Set<string>): Promise<void> {
+    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 的行前，检查引用它的所有表：
@@ -1328,6 +1374,15 @@ export class AriaEngine implements IStorageEngine {
  async rollbackToSavepoint(name: string): Promise<void> {
    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<string>();
+    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 版本链中的全部记录（快照已含正确数据，
@@ -1339,6 +1394,12 @@ export class AriaEngine implements IStorageEngine {
      if (k === name) { found = true; continue; }
      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: string): Promise<void> {
@@ -615,20 +615,28 @@ export 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(): Promise<void> {
@@ -57,16 +57,19 @@ export class MVCCManager {
    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);
        }
      }
    }
@@ -75,13 +75,10 @@ export 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);
      this.bufferedBytes += bytes.byteLength;
@@ -101,13 +98,9 @@ export 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);
      this.bufferedBytes += combined.byteLength;
@@ -223,6 +223,19 @@ export class KVStore {
    });
  }

+  /**
+   * v0.6.3: 多 key 混合原子写（put + delete 编码进同一条日志记录）。
+   * 此前 KVStoreEngine 的 delete/update 主键变更等路径 putMany 与 deleteMany
+   * 分两次调用 = 两条记录：崩溃在两条记录之间 → 新旧行并存（重复行/脏数据），
+   * 与"一条日志记录 = 真原子"宣称不符。此方法保证混合操作全有或全无。
+   */
+  async writeBatch(puts: Record<string, ArrayBuffer>, deletes: string[]): Promise<void> {
+    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 顺序拼接，
@@ -8,7 +8,7 @@
 * - 读：始终走内存（写路径同步落盘，重启从 KVStore 恢复）
 * - 写：内存先行 + KVStore 增量持久化（insert 增量 putMany；update/delete 受影响行重写；
 *   主键变更/级联场景整表 diff；全部原子）
- * - 事务：内存快照 + commit 时受影响表原子 flush（putMany 单记录 = 真原子，
+ * - 事务：内存快照 + commit 时受影响表原子 flush（writeBatch 单记录 = 真原子，
 *   此前 IndexedDBEngine 依赖 IDB 事务，现在完全自研）
 *
 * 数据布局（KVStore keys）:
@@ -194,8 +194,7 @@ export class KVStoreEngine implements IStorageEngine {
    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: string): Promise<boolean> {
@@ -229,8 +228,7 @@ export class KVStoreEngine implements IStorageEngine {
    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);
    }
  }

@@ -319,8 +317,7 @@ export class KVStoreEngine implements IStorageEngine {
      }
    }
    // 单次原子写（一条日志记录 = 真原子，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;
  }

@@ -342,8 +339,7 @@ export class KVStoreEngine implements IStorageEngine {
      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;
  }

@@ -360,8 +356,7 @@ export class KVStoreEngine implements IStorageEngine {
      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);
  }

  // ---- 动态索引 ----
@@ -419,8 +414,7 @@ export class KVStoreEngine implements IStorageEngine {
        }
      }
    }
-    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();
@@ -502,7 +496,7 @@ export class KVStoreEngine implements IStorageEngine {

  /**
   * v0.6.1: 整表 diff 收集（不落盘）：内存行全部 put + KV 残留行删除。
-   * 调用方合并到单次原子 putMany/deleteMany（多表操作真原子）。
+   * 调用方合并到单次原子 writeBatch（put+delete 同一条日志记录，多表操作真原子）。
   */
  private async collectTableDiff(tableName: string): Promise<{ puts: Record<string, ArrayBuffer>; deletes: string[] }> {
    const prefix = this.rowPrefix(tableName);
@@ -270,7 +270,15 @@ export class MemoryEngine implements IStorageEngine {
        toDelete.push(pk);
      }
    }
-    // 级联删除：检查引用此表的其他表
+    // v0.6.3-fix: 级联两阶段 —— 先对全部待删行做 RESTRICT 预检（沿 CASCADE 链递归），
+    // 任何一行违规则整体拒绝。此前逐行执行：第 N 行 RESTRICT 抛错时，前 N-1 行的
+    // 级联子行已被删除、父行未删 → 无事务下部分级联（数据不一致）
+    const restrictVisited = new Set<string>();
+    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);
@@ -280,6 +288,42 @@ export class MemoryEngine implements IStorageEngine {
    return toDelete.length + cascadeCount;
  }

+  /**
+   * v0.6.3: RESTRICT 预检（delete 级联两阶段之一）。
+   * 递归沿 CASCADE 链检查引用表：RESTRICT 引用存在依赖行则抛 FOREIGN_KEY_VIOLATION。
+   */
+  private checkCascadeRestrict(tableName: string, pkValue: string, visited: Set<string>): void {
+    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: string[] = [];
+        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: string, query?: QueryPlan): Promise<number> {
    this.ensureTable(tableName);
    const table = this.tables.get(tableName)!;
@@ -554,14 +598,12 @@ export class MemoryEngine implements IStorageEngine {
          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);
            }
          }
        }