jsql-neo 6.5.13 → 6.5.15

package/README.md

@@ -3,7 +3,7 @@
 > **One engine to rule them all** — a Rust-powered embedded database that speaks your language:
 > MySQL, PostgreSQL, MongoDB, Redis, SQL, TypeScript, **and the browser**.
 
-> **v6.5.13** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
+> **v6.5.15** — stable release · [github.com/vexify-org/JSQL-neo](https://github.com/vexify-org/JSQL-neo) · [jsql.vexify.top](https://jsql.vexify.top)
 
 ![Engines](https://img.shields.io/badge/engines-Native%20%7C%20WASM%20%7C%20Pure%20JS-7ee787)
 ![MySQL](https://img.shields.io/badge/protocol-MySQL%20compatible-1f6feb)

package/index.js

@@ -1,5 +1,5 @@
 /**
- * JSQL-NEO v6.5.13 — Rust-Powered Embedded Database (WASM + HTTP)
+ * JSQL-NEO v6.5.15 — Rust-Powered Embedded Database (WASM + HTTP)
  *
  * @example
  * const jsql = require('jsql-neo');

package/lib/btree.js

@@ -24,8 +24,6 @@ class BTree {
         this._unique = unique;
         this._root = new BTreeNode();
         this._size = 0;
-        this._minKeys = Math.floor(order / 2) - 1;
-        this._minDegree = Math.ceil(order / 2);
     }
 
     get size() { return this._size; }
@@ -273,122 +271,81 @@ class BTree {
 
     remove(key, rowIndex) {
         if (!this._root) return false;
-        const removed = this._removeFromNode(this._root, key, rowIndex);
-        // 删掉整个键（而非仅删某个 rowIndex）后，叶子的键域可能缩小，
-        // 沿途的分隔键副本可能已指向不存在的键 —— 自顶向下重建一次。
-        if (removed) {
-            this._size--;
-            if (!this._root.leaf) this._fixSeparators(this._root);
-        }
-        if (this._root.keys.length === 0 && !this._root.leaf && this._root.children.length > 0) {
-            this._root = this._root.children[0];
-        }
-        return removed;
+        const res = this._removeFromNode(this._root, key, rowIndex);
+        if (!res.found) return false;
+        if (!res.remaining) this._size--;
+        // 只做惰性删除 + 分隔键归一：不再在下降途中借用/合并。
+        // 旧实现先对路由到的子节点做 borrow/merge 再检查键是否存在，
+        // 删除一个不存在的键（或 rowIndex 不匹配）也会重构整棵树，
+        // 合并时丢掉的分隔键副本可能正好是仍然存活的数据键 —— 条目静默丢失。
+        this._normalize();
+        return !res.remaining;
     }
 
     _removeFromNode(node, key, rowIndex) {
         if (node.leaf) {
             const i = this._lowerBound(node.keys, key);
-            if (i >= node.keys.length || node.keys[i] !== key) return false;
-            if (!node.values[i].includes(rowIndex)) return false;
+            if (i >= node.keys.length || node.keys[i] !== key) return { found: false };
+            const pos = node.values[i].indexOf(rowIndex);
+            if (pos === -1) return { found: false };
             const vals = node.values[i].filter(v => v !== rowIndex);
             if (vals.length === 0) {
                 node.keys.splice(i, 1);
                 node.values.splice(i, 1);
-                return true;
+                return { found: true, remaining: false };
             }
             node.values[i] = vals;
-            return false;
+            return { found: true, remaining: true };
         }
 
-        let i = this._route(node, key);
-
-        // 下降前确保子节点有足够键，避免欠满子节点
+        const i = this._route(node, key);
         const child = node.children[i];
-        if (child.keys.length <= this._minKeys) {
-            i = this._rebalanceChild(node, i);
-        }
-        return this._removeFromNode(node.children[i], key, rowIndex);
+        if (!child) return { found: false };
+        return this._removeFromNode(child, key, rowIndex);
     }
 
-    _rebalanceChild(parent, i) {
-        if (i > 0 && parent.children[i - 1].keys.length > this._minKeys) {
-            this._borrowFromLeft(parent, i);
-            return i;
-        }
-        if (i + 1 < parent.children.length && parent.children[i + 1].keys.length > this._minKeys) {
-            this._borrowFromRight(parent, i);
-            return i;
-        }
-        if (i > 0) {
-            this._mergeChildren(parent, i - 1);
-            return i - 1;
-        }
-        this._mergeChildren(parent, i);
-        return i;
+    /**
+     * 惰性回收：删掉节点里空的叶子/空子树，折叠只剩一个孩子的内部节点，
+     * 并按「分隔键 = 左子树最大键」的约定重算所有内部键，最后重建叶子链表。
+     * 节点欠满不影响正确性（插入时仍然按满则分裂），因此无需借用/合并。
+     */
+    _normalize() {
+        const root = this._cleanNode(this._root);
+        this._root = root || new BTreeNode();
+        this._relinkLeaves();
     }
 
-    _borrowFromLeft(parent, i) {
-        const left = parent.children[i - 1];
-        const right = parent.children[i];
-        if (right.leaf) {
-            // 叶子节点：移动左叶最大键到右叶最小位置
-            const k = left.keys.pop();
-            const v = left.values.pop();
-            right.keys.unshift(k);
-            right.values.unshift(v);
-            // 父节点分隔键应为左叶新的最大值（pop 后的最后一个键）
-            parent.keys[i - 1] = left.keys[left.keys.length - 1];
-            parent.values[i - 1] = left.values[left.values.length - 1];
-        } else {
-            right.keys.unshift(parent.keys[i - 1]);
-            right.values.unshift(parent.values[i - 1]);
-            parent.keys[i - 1] = left.keys.pop();
-            parent.values[i - 1] = left.values.pop();
-            right.children.unshift(left.children.pop());
+    _cleanNode(node) {
+        if (node.leaf) return node.keys.length === 0 ? null : node;
+        const kids = [];
+        for (const c of node.children) {
+            const kept = this._cleanNode(c);
+            if (kept) kids.push(kept);
         }
-    }
-
-    _borrowFromRight(parent, i) {
-        const left = parent.children[i];
-        const right = parent.children[i + 1];
-        if (left.leaf) {
-            // 叶子节点：用被移动的键而非旧分隔键，避免重复
-            const k = right.keys.shift();
-            const v = right.values.shift();
-            left.keys.push(k);
-            left.values.push(v);
-            parent.keys[i] = k;
-            parent.values[i] = v;
-        } else {
-            left.keys.push(parent.keys[i]);
-            left.values.push(parent.values[i]);
-            parent.keys[i] = right.keys.shift();
-            parent.values[i] = right.values.shift();
-            left.children.push(right.children.shift());
+        node.children = kids;
+        if (kids.length === 0) return null;
+        if (kids.length === 1) return kids[0];
+        node.keys = [];
+        node.values = [];
+        for (let i = 0; i < kids.length - 1; i++) {
+            const m = this._getMax(kids[i]);
+            node.keys.push(m.key);
+            node.values.push(m.value);
         }
+        return node;
     }
 
-    /**
-     * 修复内部节点的分隔键：keys[i] 必须是一个**确实存在于 child[i] 里**的键。
-     *
-     * 背景：分隔键的约定是「左子树的最大键」（叶子上存真实数据，父节点存副本）。
-     * remove() 删掉叶子上的某个键后，如果那个键正好是父节点的分隔键副本，
-     * 分隔键就会指向一个已经不存在的值 —— 树还能路由对，但内部键不再严格递增，
-     * 下一次 borrow/merge 就会把它复制成重复键，直接破坏结构。
-     *
-     * 最小复现（BTree(4)）：
-     *   +28:1 +24:4 +0:0 +14:2 -24:4 +25:4 +24:2 +28:1 -26:2
-     * 前 8 步都正常，第 9 步把 keys=[24,25] 变成 [24,24]。
-     */
-    _fixSeparators(node) {
-        if (node.leaf) return;
-        for (let i = 0; i < node.keys.length; i++) {
-            const m = this._getMax(node.children[i]);
-            node.keys[i] = m.key;
-            node.values[i] = m.value;
+    _relinkLeaves() {
+        let head = this._root;
+        while (head && !head.leaf) head = head.children[0];
+        let prev = null;
+        let node = head;
+        while (node) {
+            if (prev) prev.next = node;
+            prev = node;
+            node = node.next;
         }
-        for (const c of node.children) this._fixSeparators(c);
+        if (prev) prev.next = null;
     }
 
     _getMax(node) {
@@ -397,27 +354,6 @@ class BTree {
         return { key: node.keys[i], value: node.values[i] };
     }
 
-    _mergeChildren(parent, index) {
-        const left = parent.children[index];
-        const right = parent.children[index + 1];
-        const midKey = parent.keys[index];
-        const midVal = parent.values[index];
-
-        // 叶子节点：分隔键是叶子的副本（已在 left 或 right 中），不能重复压入
-        if (!left.leaf) {
-            left.keys.push(midKey);
-            left.values.push(midVal);
-        }
-        for (const __e of right.keys) left.keys.push(__e);
-        for (const __e of right.values) left.values.push(__e);
-        if (!left.leaf) for (const __e of right.children) left.children.push(__e);
-        if (left.leaf) left.next = right.next;
-
-        parent.keys.splice(index, 1);
-        parent.values.splice(index, 1);
-        parent.children.splice(index + 1, 1);
-    }
-
     // ============================================================
     // 遍历
     // ============================================================

package/lib/database.js

@@ -1344,15 +1344,11 @@ class Database {
             startedAt: Date.now()
         };
 
-        if (level === 'REPEATABLE_READ') {
-            // 快照：保存当前所有数据（深拷贝，保证嵌套对象可回滚）
-            this._transaction.snapshot = this._captureTxSnapshot();
-        } else {
-            // READ_COMMITTED：只保存 autoIncrement
-            for (const [name, table] of Object.entries(this._tables)) {
-                this._transaction.autoIncrements[name] = table._autoIncrement;
-            }
-        }
+        // 无论隔离级别都要保存完整快照：ROLLBACK 必须撤销本事务写入的行。
+        // 此前 READ_COMMITTED 只记 autoIncrement，回滚后行原样残留（静默不撤销）。
+        // 隔离级别只影响「读取时能否看到其他事务的已提交数据」（这里是单连接内嵌库，
+        // 不涉及并发可见性），不应影响回滚能力。
+        this._transaction.snapshot = this._captureTxSnapshot();
 
         this._savepointStack = [];
         this._walWrite({ op: 'begin', level });
@@ -1374,12 +1370,6 @@ class Database {
 
         if (this._transaction.snapshot) {
             this._restoreTxSnapshot(this._transaction.snapshot);
-        } else {
-            // READ_COMMITTED：没有行快照，只能退回自增值
-            for (const [name, table] of Object.entries(this._tables)) {
-                const v = this._transaction.autoIncrements[name];
-                if (v !== undefined) table._autoIncrement = v;
-            }
         }
 
         this._walWrite({ op: 'rollback', at: this._transaction.startedAt });
@@ -1857,8 +1847,8 @@ class Database {
         let rows = table._applyFilterOptimized(table._getVisibleRows(), filter || {});
         if (limit > 0) rows = rows.slice(offset, offset + limit);
         else if (offset > 0) rows = rows.slice(offset);
-        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
-        rows = rows.map(r => ({ ...r }));
+        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
+        rows = rows.map(r => Table.cloneRow(r));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { filter, opts }, rows]);
         return rows;
@@ -1890,8 +1880,8 @@ class Database {
         const row = this._resolveId(table, id);
         // P1-4: 软删除行对普通读取不可见
         if (row && row._deleted) return null;
-        // P1-11: 返回浅拷贝，防止调用方修改影响内部数据
-        const result = row ? { ...row } : null;
+        // P1-11: 返回深拷贝，防止调用方修改（含嵌套对象/数组）影响内部数据
+        const result = row ? Table.cloneRow(row) : null;
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { id }, result]);
         return result;
@@ -1902,7 +1892,7 @@ class Database {
         if (!table) throw createError('ER_NO_SUCH_TABLE', tableName);
         if (!(await this._runHooks('beforeFind', [tableName, { ids }]))) return null;
         // P1-4: 过滤掉软删除行；P1-11: 返回浅拷贝
-        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => ({ ...r }));
+        const rows = ids.map(id => this._resolveId(table, id)).filter(r => r !== null && !r._deleted).map(r => Table.cloneRow(r));
         this._touchTable(tableName);
         await this._runHooks('afterFind', [tableName, { ids }, rows]);
         return rows;
@@ -1948,6 +1938,9 @@ class Database {
             const clash = table._rows.find(r => r !== row && r[field] === nv);
             if (clash) throw createError('ER_DUP_ENTRY', `Duplicate entry '${nv}' for key '${field}'`);
         }
+        // 主键/必填列的 NULL 校验：updateById 此前只做类型校验与重复检查，
+        // `UPDATE t SET id = NULL` 会被静默写入（主键行变成 NULL 主键）。
+        table._validateConstraints({ ...row, ...validated }, table._rows.indexOf(row));
         Object.assign(row, validated);
         if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...validated } });
         this._emit('update', { table: tableName, id, data: validated });
@@ -1966,7 +1959,9 @@ class Database {
         for (const [id, data] of pairs) {
             const row = this._resolveId(table, id);
             if (row) {
-                Object.assign(row, data);
+                const validated = table._validateDataTypes({ ...data }, true);
+                table._validateConstraints({ ...row, ...validated }, table._rows.indexOf(row));
+                Object.assign(row, validated);
                 count++;
                 if (pk) this._walWrite({ op: 'update', table: tableName, pk, id, row: { ...data } });
             }

package/lib/errors.js

@@ -81,11 +81,10 @@ function createError(codeKey, ...args) {
         return new JSQL_Error('UNKNOWN', `Unknown error: ${codeKey}`, { codeKey, args });
     }
 
-    let msg = template.msg;
-    for (let i = 0; i < args.length; i++) {
-        // 使用函数替换避免 $& 等特殊字符被解释
-        msg = msg.replace('%s', () => String(args[i]));
-    }
+    // 单趟替换所有 %s：既避免参数值里本身含有 %s 时被后续替换再次消费造成串位，
+    // 也避免实参不足时消息里残留裸 %s。
+    let idx = 0;
+    const msg = template.msg.replace(/%s/g, () => (idx < args.length ? String(args[idx++]) : ''));
 
     return new JSQL_Error(template.code, msg, { args });
 }

package/lib/migrate.js

@@ -30,8 +30,12 @@ function normalizeSchema(schema) {
     if (d.type === 'varchar' || d.type === 'text' || d.type === 'char') d.type = 'string';
     if (d.type === 'double' || d.type === 'real' || d.type === 'decimal' || d.type === 'numeric') d.type = 'float';
     if (d.type === 'bool') d.type = 'boolean';
-    delete d.length;
-    if (d.maxLength) { d.length = d.maxLength; delete d.maxLength; }
+    // 保留用户显式配置的 length；maxLength 只是别名，仅在 length 未给出时回填。
+    // 此前无条件 delete d.length 再仅从 maxLength 恢复，导致显式 length 丢失。
+    if (d.maxLength !== undefined) {
+      if (d.length === undefined) d.length = d.maxLength;
+      delete d.maxLength;
+    }
     out[name] = d;
   }
   return out;

package/lib/mongo_server.js

@@ -461,7 +461,7 @@ class MongoServer {
           await engine.insert(coll, merged);
           value = doc.new ? { ...merged } : null;
         }
-        return { ok: 1, value, lastErrorObject: { n: found ? 1 : (doc.upsert ? 1 : 0), updatedExisting: !!found && !doc.remove } };
+        return { ok: 1, value: value ? this._publicDoc(value) : value, lastErrorObject: { n: found ? 1 : (doc.upsert ? 1 : 0), updatedExisting: !!found && !doc.remove } };
       }
       case 'distinct': {
         const coll = String(doc.distinct);
@@ -496,7 +496,7 @@ class MongoServer {
         if (skip > 0) rows = rows.slice(skip);
         const limit = typeof doc.limit === 'number' ? doc.limit : 0;
         if (limit > 0) rows = rows.slice(0, limit);
-        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows } };
+        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows.map(r => this._publicDoc(r)) } };
       }
       case 'getMore':
         return { ok: 1, cursor: { id: { $long: 0 }, ns: String(doc.collection || ''), nextBatch: [] } };
@@ -673,7 +673,7 @@ class MongoServer {
             rows = out;
           }
         }
-        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows } };
+        return { ok: 1, cursor: { id: { $long: 0 }, ns: `${this._dbOf(doc)}.${coll}`, firstBatch: rows.map(r => this._publicDoc(r)) } };
       }
       default:
         return { ok: 1, n: 0 };
@@ -684,6 +684,23 @@ class MongoServer {
     return row._id != null ? row._id : row.id;
   }
 
+  /**
+   * 剥离 JSQL 内部字段后再返回给 Mongo 客户端。
+   *
+   * _deleted（软删除标记）、_rid（内部行号）、_score（全文检索得分）
+   * 都只属于引擎内部实现，泄漏到文档里会污染用户数据、影响后续 $set/$unset
+   * 以及客户端 schema 推断。
+   */
+  _publicDoc(row) {
+    if (!row || typeof row !== 'object') return row;
+    if (row._deleted === undefined && row._rid === undefined && row._score === undefined) return row;
+    const out = { ...row };
+    delete out._deleted;
+    delete out._rid;
+    delete out._score;
+    return out;
+  }
+
   async _matching(engine, coll, filter) {
     const rows = await engine.find(coll, {});
     return rows.filter((r) => this._match(r, filter || {}));

package/lib/mysql_server.js

@@ -578,8 +578,9 @@ class MysqlConnection {
         case 0x19: this._handleStmtClose(body); break; // COM_STMT_CLOSE
         case 0x1a: this._send(okPacket()); break; // COM_STMT_RESET
         case 0x0a: { // COM_PROCESS_INFO
-          const seq = this.sequence;
-          this.sequence = (this.sequence + 1) & 0xff;
+          // _handlePacket 已把 this.sequence 设为 cmdSeq+1，_send 会在写入后自增。
+          // 此前这里额外自增一次，导致首个响应包序列号比请求大 2（跳号），
+          // 严格校验序列号的客户端会判定协议错误并断开。
           this._send(encodeLenenc(1));
           this._send(columnDefinition({ name: 'Id', type: MYSQL_TYPE_LONG }));
           this._send(eofPacket());

package/lib/nedb_compat.js

@@ -77,8 +77,21 @@ function matchOperator(value, op, expected) {
     case '$in': return Array.isArray(expected) && expected.some(e => looseEqual(value, e));
     case '$nin': return Array.isArray(expected) && !expected.some(e => looseEqual(value, e));
     case '$exists': return expected ? value !== undefined : value === undefined;
-    case '$regex':
-      return typeof value === 'string' && new RegExp(expected.source, expected.flags || 'i').test(value);
+    case '$regex': {
+      if (typeof value !== 'string') return false;
+      // expected 允许两种写法：/re/flags（RegExp），或 MySQL 风格的字符串模式。
+      // 此前直接读 expected.source：字符串没有 source → new RegExp(undefined)
+      // 等价于 /(?:)/，静默匹配所有文档。
+      let re;
+      if (expected instanceof RegExp) {
+        re = expected;
+      } else if (typeof expected === 'string') {
+        try { re = new RegExp(expected); } catch { return false; }
+      } else {
+        return false;
+      }
+      return re.test(value);
+    }
     case '$size': return Array.isArray(value) && value.length === expected;
     default: return false;
   }

package/lib/pg_server.js

@@ -792,7 +792,10 @@ class PgServer {
       if (user !== this.options.user) return undefined;
       return this.options.password || '';
     }
-    return '';
+    // 未配置任何认证信息：默认拒绝连接（返回 undefined → 认证失败）。
+    // 此前返回 '' 会被 _startAuth 当成 trust，导致任意用户名 + 空密码即可连入，
+    // 与 MysqlServer 的默认拒绝策略保持一致。仅显式 noAuth: true 才放行。
+    return undefined;
   }
 
   _canAccessDb(user, dbName) {

package/lib/plugin.js

@@ -104,10 +104,16 @@ function definePlugin(name, def = {}) {
 }
 
 /** 登记单个钩子；未知钩子名会自动创建，便于插件自定义扩展点 */
-function registerHook(engine, hook, fn) {
+function registerHook(engine, hook, fn, priority = 0) {
   if (typeof fn !== 'function') return engine;
   if (!engine._hooks) engine._hooks = createHookRegistry();
   if (!engine._hooks[hook]) engine._hooks[hook] = [];
+  // 记录优先级：即使插件是后加载的，也应按 priority 决定执行顺序，
+  // 而不是简单追加在已有钩子之后（此前 sort(_plugins) 只排插件列表，
+  // 钩子链仍按注册顺序执行，导致 priority 实际无效）。
+  try {
+    Object.defineProperty(fn, '__jsqlHookPriority', { value: priority, configurable: true, writable: true });
+  } catch (e) { /* 冻结函数等无法打标，按 0 处理 */ }
   engine._hooks[hook].push(fn);
   return engine;
 }
@@ -115,9 +121,10 @@ function registerHook(engine, hook, fn) {
 /** 把一个插件声明的所有钩子登记到引擎上 */
 function registerHooks(engine, plugin) {
   if (!plugin || !plugin.hooks) return engine;
+  const priority = plugin.priority || 0;
   for (const [hook, val] of Object.entries(plugin.hooks)) {
     const fns = Array.isArray(val) ? val : [val];
-    for (const fn of fns) registerHook(engine, hook, fn);
+    for (const fn of fns) registerHook(engine, hook, fn, priority);
   }
   return engine;
 }
@@ -253,7 +260,11 @@ function runHooks(engine, hookName, args) {
 
   return (async () => {
     try {
-      for (const fn of hooks) {
+      // priority 大的先执行；同 priority 保持注册顺序（sort 在现代引擎是稳定的）
+      const ordered = hooks.length > 1
+        ? hooks.slice().sort((a, b) => (b.__jsqlHookPriority || 0) - (a.__jsqlHookPriority || 0))
+        : hooks;
+      for (const fn of ordered) {
         const result = await fn(...args);
         if (result === false) return false;
       }

package/lib/sql.js

@@ -2811,8 +2811,15 @@ class Parser {
     // MySQL 中 RLIKE 是 REGEXP 的同义词
     if (t2.type === 'keyword' && (t2.value === 'REGEXP' || t2.value === 'RLIKE')) {
       this.next();
-      const pattern = this.parseValue();
-      return { type: 'regexp', operand: left, pattern, not };
+      let pattern = this.parseValue();
+      // `expr REGEXP BINARY 'pat'`：BINARY 前缀表示大小写敏感匹配。
+      // 解析出的 pattern 会包一层 { type:'binary', operand }，这里解包并标记 ci=false。
+      let binary = false;
+      if (pattern && typeof pattern === 'object' && pattern.type === 'binary') {
+        binary = true;
+        pattern = pattern.operand;
+      }
+      return { type: 'regexp', operand: left, pattern, not, ci: !binary };
     }
 
     // PG JSON 包含操作符
@@ -2982,7 +2989,16 @@ function resolveOperand(operand, row, ctx) {
         if (!rowHasPrefixedKeys(row) && row[col] !== undefined) return row[col];
       }
       // 相关子查询：回退到外层行（ctx.__outer 由 _evalExists 临时注入）
-      if (ctx && ctx.__outer && ctx.__outer[n] !== undefined) return ctx.__outer[n];
+      if (ctx && ctx.__outer) {
+        if (ctx.__outer[n] !== undefined) return ctx.__outer[n];
+        // 外层行通常是未加前缀的裸列（{id:1}），而引用可能带表层限定符（a.id）。
+        // 内层行已套前缀时，row[col] 的回退已被禁止，这里必须再按裸列名查一次，
+        // 否则 `WHERE b.id = a.id` 在 UPDATE/SELECT 的相关子查询里恒为 NULL。
+        if (n.indexOf('.') !== -1) {
+          const col = n.slice(n.lastIndexOf('.') + 1);
+          if (ctx.__outer[col] !== undefined) return ctx.__outer[col];
+        }
+      }
       return undefined;
     }
     case 'arith': {
@@ -4476,7 +4492,14 @@ function evaluateExpr(expr, row, ctx) {
   switch (expr.type) {
     case 'and': return evaluateExpr(expr.left, row, ctx) && evaluateExpr(expr.right, row, ctx);
     case 'or': return evaluateExpr(expr.left, row, ctx) || evaluateExpr(expr.right, row, ctx);
-    case 'xor': return Boolean(evaluateExpr(expr.left, row, ctx)) !== Boolean(evaluateExpr(expr.right, row, ctx));
+    case 'xor': {
+      // 三值逻辑：任一操作数为 UNKNOWN 时结果也是 UNKNOWN。
+      // 旧实现用 Boolean() 归一，Boolean(null)=false 会把 NULL XOR TRUE 误判为 TRUE。
+      const l = evaluateExpr(expr.left, row, ctx);
+      const r = evaluateExpr(expr.right, row, ctx);
+      return sqlXor(l === null || l === undefined ? null : Boolean(l),
+        r === null || r === undefined ? null : Boolean(r));
+    }
     case 'not': {
       // 三值逻辑：NOT UNKNOWN = UNKNOWN（返回 null，在 WHERE/ON/HAVING 中视为不选中）
       // 必须用 resolveOperand 取值：evaluateExpr 只认布尔类节点，
@@ -4569,8 +4592,18 @@ function evaluateExpr(expr, row, ctx) {
     case 'regexp': {
       const v = resolveOperand(expr.operand, row, ctx);
       if (v === null || v === undefined) return false;
-      // REGEXP / RLIKE 历史上就是大小写不敏感的；`~` 敏感、`~*` 不敏感
-      const re = new RegExp(String(expr.pattern), expr.ci === false ? '' : 'i');
+      // pattern 可能是字面量、列引用或表达式：统一用 resolveOperand 取值。
+      // 过去 String(expr.pattern) 对 { type:'binary'|'column' } 对象只会得到
+      // "[object Object]"，BINARY 前缀的大小写敏感语义也因此完全失效。
+      // pattern 可能是字面量、列引用或表达式：字面量（primitive）直接使用，
+      // 只有 AST 节点才走 resolveOperand —— 否则字符串会被当成列名。
+      const pat = (expr.pattern && typeof expr.pattern === 'object')
+        ? resolveOperand(expr.pattern, row, ctx)
+        : expr.pattern;
+      if (pat === null || pat === undefined) return false;
+      let re;
+      try { re = new RegExp(String(pat), expr.ci === false ? '' : 'i'); } catch { return false; }
+      // REGEXP / RLIKE 默认大小写不敏感；`~` 敏感、`~*` 不敏感；REGEXP BINARY 敏感
       const r = re.test(String(v));
       return expr.not ? !r : r;
     }
@@ -4590,8 +4623,11 @@ function evaluateExpr(expr, row, ctx) {
       // 三值逻辑：任一操作数为 NULL 时结果是 UNKNOWN（用 null 表示），
       // 与普通比较运算符一致；不能返回 false，否则 NOT BETWEEN 会被误判为真。
       if (v === null || v === undefined || lo === null || lo === undefined || hi === null || hi === undefined) return null;
-      const inRange = typeof v === 'number' && typeof lo === 'number' && typeof hi === 'number'
-        ? v >= lo && v <= hi
+      // 数值（含数字字符串）必须按数值比较，否则 '10' BETWEEN 2 AND 9 会退化成
+      // 字典序 ('10' >= '2' 为 false)，与 MySQL 不一致。
+      const nv = numericIfNumeric(v), nlo = numericIfNumeric(lo), nhi = numericIfNumeric(hi);
+      const inRange = nv !== null && nlo !== null && nhi !== null
+        ? nv >= nlo && nv <= nhi
         : String(v) >= String(lo) && String(v) <= String(hi);
       return expr.not ? !inRange : inRange;
     }
@@ -5447,11 +5483,21 @@ class SQLExecutor {
         }
         if (typeof statement.limit === 'number') candidates = candidates.slice(0, statement.limit);
         let count = 0;
+        // UPDATE 的赋值表达式同样可能含标量子查询，SELECT 路径在 _materialize
+        // 里统一物化，但 UPDATE 从未调用它 —— 子查询节点 _value 一直是 undefined，
+        // resolveOperand 直接返回 NULL，`SET x = (SELECT ...)` 静默写成 NULL。
+        for (const [, val] of statement.assignments) {
+          if (val && typeof val === 'object') await this._materialize(val);
+        }
         for (const row of candidates) {
           const id = this._rowPkId(row, pkCols);
           if (id !== undefined) {
             const data = {};
             for (const [col, val] of statement.assignments) {
+              if (val && typeof val === 'object' && val.type) {
+                // 相关子查询：按当前行重算（非相关时重算是幂等的，结果一致）
+                for (const sub of this._collectSubqueries(val)) await this._evalCorrelated(sub, row);
+              }
               data[col] = typeof val === 'object' && val !== null && val.type ? resolveOperand(val, row, this.ctx) : val;
             }
             // 必须 await：wasm / native client 的 updateById 是异步的，

package/lib/star-nag.js

@@ -156,22 +156,33 @@ function checkStarred() {
   // 用同步 API：CLI 启动阶段还没有 event loop 可用
   try {
     const { execFileSync } = require('child_process');
-    const out = execFileSync('curl', [
+    // 用 -w 追加 HTTP 状态码，按状态码判定，而不是靠 body 长度猜。
+    // 该端点语义：已 star → 204（空 body）；未 star → 404。
+    // 此前把「空 body」一律当已 star：遇到 302/500 等空 body 响应或代理异常时
+    // 会误判为 star 过，从此永久闭嘴。
+    const raw = execFileSync('curl', [
       '-sS', '-m', '4',
+      '-w', '\n%{http_code}',
       '-H', `Authorization: Bearer ${token}`,
       '-H', 'Accept: application/vnd.github+json',
       '-H', 'X-GitHub-Api-Version: 2022-11-28',
       `https://api.github.com/user/starred/${REPO}`,
     ], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString();
-    if (out.trim() === '') return true;     // 200 + 空数组 = 列了但没有这个仓库
-    const j = JSON.parse(out);
-    // GitHub 出错时返回的是 {"message":"Bad credentials"} 之类，不是数组。
-    // 那说明 token 无效/过期 —— 属于「无法确认」，不能当成「没 star」，
-    // 否则会永远提示下去。
-    if (j && !Array.isArray(j) && typeof j.message === 'string') return null;
-    return Array.isArray(j) && j.length > 0;
+    const nl = raw.lastIndexOf('\n');
+    const status = Number(raw.slice(nl + 1).trim());
+    const body = raw.slice(0, nl).trim();
+    if (status === 204) return true;
+    if (status === 404) return false;
+    if (status === 200 && body) {
+      // 兼容返回数组的旧行为：数组里有该仓库才算 star
+      try {
+        const j = JSON.parse(body);
+        if (Array.isArray(j)) return j.length > 0;
+      } catch (e) { /* 非 JSON，无法确认 */ }
+    }
+    return null;                  // 401/403/3xx/5xx → 无法确认
   } catch (e) {
-    return null;                  // 网络不通 / 401 / 没装 curl → 不确定
+    return null;                  // 网络不通 / 没装 curl → 不确定
   }
 }
 

package/lib/table.js

@@ -118,6 +118,24 @@ function isSafeRegex(pattern) {
     return groups.length === 0;
 }
 
+/**
+ * 深拷贝一行数据（普通对象/数组/Date），用于隔离内部存储与调用方。
+ *
+ * 过去 insert/find 只做 `{ ...row }` 浅拷贝：行里的嵌套对象/数组与内部存储
+ * 共享引用，调用方修改返回值（或插入后继续改传入对象）会静默污染数据库内容。
+ * 非普通对象（Map/Set/类实例等）保持原引用，避免破坏无法安全克隆的类型。
+ */
+function cloneRow(value) {
+    if (value === null || typeof value !== 'object') return value;
+    if (value instanceof Date) return new Date(value.getTime());
+    if (Array.isArray(value)) return value.map(cloneRow);
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) return value;
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = cloneRow(value[k]);
+    return out;
+}
+
 class Table {
     constructor(name, schema, db) {
         this._name = name;
@@ -245,7 +263,7 @@ class Table {
         }
 
         const rowIndex = this._rows.length;
-        this._rows.push({ ...data });
+        this._rows.push(cloneRow(data));
         this._addToIndexes(rowIndex, data);
         this._dirty = true;
         this._db._markDirty(this._name);
@@ -299,7 +317,7 @@ class Table {
         const result = new Array(N);
         for (let i = 0; i < N; i++) {
             // 在副本上做默认值/计算列/类型归一，避免污染调用方传入的原始对象
-            let data = { ...items[i] };
+            let data = cloneRow(items[i]);
             for (const [f, dv] of Object.entries(defaults)) {
                 if (data[f] === undefined) data[f] = typeof dv === 'function' ? dv() : dv === 'CURRENT_TIMESTAMP' ? now() : dv;
             }
@@ -308,7 +326,8 @@ class Table {
             data = this._validateDataTypes(data);
             for (const field of this._cachedSchemaFields) {
                 const def = schema[field];
-                if (def.required && (data[field] === undefined || data[field] === null)
+                const isPk = def.primaryKey || def.primary === true;
+                if ((def.required || isPk) && (data[field] === undefined || data[field] === null)
                     && !(def.autoIncrement && data[field] === undefined)) throw createError('ER_BAD_NULL_ERROR', field);
                 if (def.unique && data[field] !== undefined) {
                     if (uniqueTracker[field].has(data[field])) throw createError('ER_DUP_ENTRY', String(data[field]), field);
@@ -346,7 +365,7 @@ class Table {
                 this._autoIncrement = data[autoIncField];
             }
             const rowIdx = this._rows.length;
-            this._rows.push(Object.assign({}, data));
+            this._rows.push(cloneRow(data));
             if (this._pkIndex && this._primaryKey) {
                 const pkVal = data[this._primaryKey];
                 if (pkVal !== undefined && pkVal !== null) {
@@ -391,7 +410,7 @@ class Table {
         if (Object.keys(query).length > 0) {
             rows = this._applyFilterOptimized(rows, query);
         }
-        return rows.map(r => ({ ...r }));
+        return rows.map(r => cloneRow(r));
     }
 
     findOne(query = {}) {
@@ -399,7 +418,7 @@ class Table {
         if (Object.keys(query).length > 0) {
             rows = this._applyFilterOptimized(rows, query);
         }
-        return rows.length > 0 ? { ...rows[0] } : null;
+        return rows.length > 0 ? cloneRow(rows[0]) : null;
     }
 
     exists(query = {}) {
@@ -415,7 +434,7 @@ class Table {
             const rowIndex = this._pkIndex.get(id);
             if (rowIndex !== undefined) {
                 const row = this._rows[rowIndex];
-                if (row && !row._deleted) return { ...row };
+                if (row && !row._deleted) return cloneRow(row);
             }
             return null;
         }
@@ -423,7 +442,7 @@ class Table {
             const indices = this._btrees[this._primaryKey].search(id);
             if (indices.length > 0) {
                 const row = this._rows[indices[0]];
-                if (row && !row._deleted) return { ...row };
+                if (row && !row._deleted) return cloneRow(row);
             }
             return null;
         }
@@ -431,7 +450,7 @@ class Table {
     }
 
     findAll() {
-        return this._getVisibleRows().map(r => ({ ...r }));
+        return this._getVisibleRows().map(r => cloneRow(r));
     }
 
     count(query = {}) {
@@ -995,18 +1014,22 @@ class Table {
         for (const [field, condition] of Object.entries(query)) {
             if (field === '$or' || field === '$and' || field === '$not') continue;
             if (typeof condition !== 'object' || condition === null || Array.isArray(condition) || condition instanceof RegExp) {
-                if (this._btrees[field]) {
+                // 索引只收非 NULL 值：condition 为 null/undefined 时必须全表扫描，
+                // 否则 search(null) 命中空数组直接返回 0 行（索引列 IS NULL 漏行）。
+                const nullish = condition === null || condition === undefined;
+                if (!nullish && this._btrees[field]) {
                     const indices = this._btrees[field].search(condition);
                     if (indices.length === 0) return [];
                     return this._applyFilter(this._rowsFromIndices(indices), query);
                 }
-                if (this._indexes[field] && this._indexes[field].has(condition)) {
+                if (!nullish && this._indexes[field] && this._indexes[field].has(condition)) {
                     return this._applyFilter(this._rowsFromIndices(this._indexes[field].get(condition)), query);
                 }
-                if (this._indexes[field]) return [];
+                if (!nullish && this._indexes[field]) return [];
             }
             if (condition && typeof condition === 'object') {
-                if (this._btrees[field] && Array.isArray(condition.$in) && condition.$in.length > 0) {
+                if (this._btrees[field] && Array.isArray(condition.$in) && condition.$in.length > 0
+                    && !condition.$in.some(v => v === null || v === undefined)) {
                     const indices = this._btrees[field].searchMany(condition.$in);
                     if (indices.length === 0) return [];
                     return this._applyFilter(this._rowsFromIndices(indices), query);
@@ -1355,8 +1378,9 @@ class Table {
         for (const [field, def] of Object.entries(this._schema)) {
             if (field === '_softDelete') continue;
 
-            // NOT NULL
-            if (def.required && (data[field] === undefined || data[field] === null)
+            // NOT NULL（主键隐式 NOT NULL，否则唯一约束检查会因 NULL 短路而被绕过）
+            const isPk = def.primaryKey || def.primary === true;
+            if ((def.required || isPk) && (data[field] === undefined || data[field] === null)
                 && !(def.autoIncrement && data[field] === undefined)) {
                 throw createError('ER_BAD_NULL_ERROR', field);
             }
@@ -1664,4 +1688,5 @@ class Table {
     }
 }
 
-module.exports = Table;
+module.exports = Table;
+Table.cloneRow = cloneRow;

package/lib/web_ui.js

@@ -69,19 +69,22 @@ tr:nth-child(even) td { background: #0d1117; }
 <script>
 let dbs = [], cur = null;
 const q = async (u, o) => { const r = await fetch(u, o); return r.json(); };
-function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;'); }
 async function load() {
   dbs = await q('/api/databases');
   const el = document.getElementById('dbs');
-  el.innerHTML = dbs.map(d => '<div class="db" onclick="openDb(' + esc(d.name) + ')">' + esc(d.name) + ' <span class="rows">(' + d.tables + ' tbl)</span></div>').join('');
+  el.innerHTML = dbs.map(d => '<div class="db" data-name="' + esc(d.name) + '">' + esc(d.name) + ' <span class="rows">(' + d.tables + ' tbl)</span></div>').join('');
+  el.querySelectorAll('.db').forEach(e => e.addEventListener('click', () => openDb(e.dataset.name)));
   if (!cur && dbs.length) openDb(dbs[0].name);
 }
 async function openDb(n) {
   cur = n;
-  document.querySelectorAll('.db').forEach(e => e.classList.toggle('active', e.textContent.indexOf(n) === 0));
+  document.querySelectorAll('.db').forEach(e => e.classList.toggle('active', e.dataset.name === n));
   const r = await q('/api/tables?db=' + encodeURIComponent(n));
-  document.getElementById('tbls').innerHTML = r.tables.map(t =>
-    '<div class="tbl" onclick="sel(' + esc(t.name) + ')">' + esc(t.name) + ' (' + t.count + ')</div>').join('');
+  const tl = document.getElementById('tbls');
+  tl.innerHTML = r.tables.map(t =>
+    '<div class="tbl" data-name="' + esc(t.name) + '">' + esc(t.name) + ' (' + t.count + ')</div>').join('');
+  tl.querySelectorAll('.tbl').forEach(e => e.addEventListener('click', () => sel(e.dataset.name)));
 }
 function sel(n) { document.getElementById('sql').value = 'SELECT * FROM ' + n + ' LIMIT 100'; run(); }
 async function run() {

package/lib/xql/src/compiler.js

@@ -136,7 +136,7 @@ class Emitter {
         const lo = this.emit(node.lo);
         const hi = this.emit(node.hi);
         const t = this.tmp();
-        this.push(`let ${t} = (${v} == null ? null : (${v} >= ${lo} && ${v} <= ${hi}));`);
+        this.push(`let ${t} = (${v} == null || ${lo} == null || ${hi} == null ? null : (${v} >= ${lo} && ${v} <= ${hi}));`);
         return t;
       }
       case 'like': {
@@ -183,8 +183,8 @@ class Emitter {
       case '*': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} * ${r});`); break;
       case '/': this.push(`let ${t} = (${l} == null || ${r} == null || Number(${r}) === 0 ? null : ${l} / ${r});`); break;
       case '%': this.push(`let ${t} = (${l} == null || ${r} == null || Number(${r}) === 0 ? null : ${l} % ${r});`); break;
-      case '=': this.push(`let ${t} = (${l} == null ? null : ${l} === ${r});`); break;
-      case '!=': this.push(`let ${t} = (${l} == null ? null : ${l} !== ${r});`); break;
+      case '=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} === ${r});`); break;
+      case '!=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} !== ${r});`); break;
       case '<': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} < ${r});`); break;
       case '>': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} > ${r});`); break;
       case '<=': this.push(`let ${t} = (${l} == null || ${r} == null ? null : ${l} <= ${r});`); break;
@@ -197,15 +197,25 @@ class Emitter {
   emitIn(node) {
     const v = this.emit(node.e);
     const t = this.tmp();
-    const not = node.neg ? '!' : '';
-    const join = node.neg ? ' && ' : ' || ';
     if (node.list.every(n => n.k === 'lit')) {
       const name = '_set' + this.sets.length;
       this.sets.push({ name, set: new Set(node.list.map(n => n.v)) });
-      this.push(`let ${t} = (${v} == null ? null : ${not}${name}.has(${v}));`);
+      // 完整三值逻辑：被查找值为 NULL → UNKNOWN；列表含 NULL 且未匹配 → UNKNOWN。
+      const hasNull = node.list.some(n => n.v === null);
+      if (node.neg) {
+        this.push(`let ${t} = (${v} == null ? null : (${name}.has(${v}) ? false : (${hasNull} ? null : true)));`);
+      } else {
+        this.push(`let ${t} = (${v} == null ? null : (${name}.has(${v}) ? true : (${hasNull} ? null : false)));`);
+      }
     } else {
-      const parts = node.list.map(n => `(${v} != null && ${v} === ${this.emit(n)})`);
-      this.push(`let ${t} = (${v} == null ? null : ${not}(${parts.join(join)}));`);
+      const elems = node.list.map(n => this.emit(n));
+      const anyMatch = elems.map(e => `(${v} === ${e})`).join(' || ');
+      const anyNull = elems.map(e => `${e} == null`).join(' || ');
+      if (node.neg) {
+        this.push(`let ${t} = (${v} == null ? null : (${anyMatch} ? false : (${anyNull} ? null : true)));`);
+      } else {
+        this.push(`let ${t} = (${v} == null ? null : (${anyMatch} ? true : (${anyNull} ? null : false)));`);
+      }
     }
     return t;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsql-neo",
-  "version": "6.5.13",
+  "version": "6.5.15",
   "description": "JSQL-NEO \u2014 Rust-powered embedded database with WASM, REST API, B-Tree indexes, WAL, crash recovery",
   "main": "index.js",
   "types": "index.d.ts",
@@ -52,7 +52,7 @@
     "test:btree": "node test/btree.test.js",
     "test:native": "node test/native.test.js",
     "test:regress": "node test/regress-5.1.0.js",
-    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/sql-semantics.test.js && node test/extra-coverage.test.js && node test/filter-compile.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js && node test/mongo-group.test.js && node test/multiprotocol.test.js",
+    "test:all": "node test/smoke.js && node test/sql-parser.test.js && node test/readme-audit.test.js && node test/native.test.js && node test/native-multi-instance.test.js && node test/wal-recovery.test.js && node test/mysql-compat-hijack.test.js && node test/wasm.test.js && node test/coverage.js && node test/regress-5.1.0.js && node test/join.test.js && node test/btree.test.js && node test/v6.5.14-regression.test.js && node test/dml-constraints.test.js && node test/savepoint.test.js && node test/alter-table.test.js && node test/null-semantics.test.js && node test/identifier-keywords.test.js && node test/sql-semantics.test.js && node test/extra-coverage.test.js && node test/filter-compile.test.js && node test/recursive-cte.test.js && node test/index-ddl.test.js && node test/mongo-group.test.js && node test/multiprotocol.test.js",
     "test:coverage": "c8 --all --include='lib/**' --exclude='lib/web_ui.js' --reporter=text --reporter=lcov node test/coverage.js",
     "test:orms": "node examples/orms/run-all.js",
     "test:dml": "node test/dml-constraints.test.js",

package/test/v6.5.14-regression.test.js

@@ -0,0 +1,295 @@
+/*
+ * v6.5.14 回归测试：把本版修掉的高危 / 中危缺陷逐条固化。
+ *
+ *   C1  B-Tree 混合插入/删除丢失索引条目
+ *   H1  PostgreSQL 未配置认证时的 trust 绕过
+ *   H2  NeDB $regex 字符串模式匹配一切
+ *   H3  UPDATE 标量子查询写成 NULL（含限定符相关子查询）
+ *   H4  BETWEEN 按字典序而非数值比较
+ *   H5  主键允许 NULL
+ *   H6  索引列 = null 漏行
+ *   M1  错误消息 %s 串位
+ *   M2  返回行浅拷贝导致内部数据被调用方污染
+ *   M3  migrate.normalizeSchema 丢失显式 length
+ *   M4  READ_COMMITTED 下 ROLLBACK 不撤销行
+ *   M5  XOR 破坏三值逻辑
+ *   M6  REGEXP BINARY 失效
+ *   M9  插件钩子未按 priority 排序
+ *   M10 XQL 编译器 NULL 传播
+ *   M11 Mongo 结果泄漏内部字段
+ *
+ *   node test/v6.5.14-regression.test.js
+ */
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const { Database } = require(path.join(ROOT, 'index.js'));
+const { executeSQL } = require(path.join(ROOT, 'lib/sql.js'));
+const BTree = require(path.join(ROOT, 'lib/btree'));
+const { PgServer } = require(path.join(ROOT, 'lib/pg_server'));
+const { Datastore } = require(path.join(ROOT, 'lib/nedb_compat'));
+const { MongoServer } = require(path.join(ROOT, 'lib/mongo_server'));
+const { createError } = require(path.join(ROOT, 'lib/errors'));
+const { normalizeSchema } = require(path.join(ROOT, 'lib/migrate'));
+const { registerHook, runHooks, createHookRegistry } = require(path.join(ROOT, 'lib/plugin'));
+const { parse: xqlParse } = require(path.join(ROOT, 'lib/xql/src/parser'));
+const { compileQuery } = require(path.join(ROOT, 'lib/xql/src/compiler'));
+
+const OPTS = { safety: false };
+let pass = 0, fail = 0;
+
+function ok(name, cond, extra) {
+  if (cond) { pass++; console.log('[OK]  ', name); }
+  else { fail++; console.log('[FAIL]', name, extra !== undefined ? '-> ' + JSON.stringify(extra).slice(0, 160) : ''); }
+}
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function makeDb() { return new Database(':memory:'); }
+
+(async () => {
+  // ── C1. B-Tree 混合插入/删除 ────────────────────────────────
+  console.log('\n--- C1. B-Tree 混合插入/删除 ---');
+  {
+    const t = new BTree(4, false);
+    for (let i = 1; i <= 64; i++) t.insert(i, i);
+    ok('插入 64 条后 size=64', t.size === 64, t.size);
+    for (let i = 2; i <= 64; i += 2) t.remove(i, i);
+    ok('删除 32 条后 size=32', t.size === 32, t.size);
+    const missing = [];
+    for (let i = 1; i <= 64; i += 2) if (!t.search(i).includes(i)) missing.push(i);
+    ok('剩余奇数键全部可搜到', missing.length === 0, missing);
+    for (let i = 2; i <= 64; i += 2) t.insert(i, i);
+    ok('重新插入后 size=64', t.size === 64, t.size);
+    const missing2 = [];
+    for (let i = 1; i <= 64; i++) if (!t.search(i).includes(i)) missing2.push(i);
+    ok('全部键可搜到（无条目丢失）', missing2.length === 0, missing2);
+    // 重复键 + 多行号：删其中一行不应误删整键
+    const m = new BTree(4, false);
+    m.insert(7, 1); m.insert(7, 2); m.insert(7, 3);
+    m.remove(7, 2);
+    ok('同键多行只删指定行', eq(m.search(7).slice().sort(), [1, 3]), m.search(7));
+    ok('同键多行 size 仍为 1（size 记不同键数）', m.size === 1, m.size);
+  }
+
+  const db = makeDb();
+  await db.start();
+  const q = (sql) => executeSQL(db, sql, OPTS);
+  const one = async (sql) => (await q(sql)).rows[0][0];
+  const fails = async (sql) => { try { await q(sql); return null; } catch (e) { return e.message; } };
+
+  // ── H1. PG 认证默认拒绝 ─────────────────────────────────────
+  console.log('\n--- H1. PostgreSQL 认证 ---');
+  {
+    const srvDefault = new PgServer({});
+    ok('未配置认证时返回 undefined（拒绝连接）', srvDefault._userPassword('anyone') === undefined);
+    const srvNoAuth = new PgServer({ noAuth: true });
+    ok('显式 noAuth 才返回空密码（trust）', srvNoAuth._userPassword('anyone') === '');
+    const srvAuth = new PgServer({ auth: { alice: { password: 'pw' } } });
+    ok('配置的用户返回真实密码', srvAuth._userPassword('alice') === 'pw');
+    ok('未配置的用户返回 undefined', srvAuth._userPassword('bob') === undefined);
+    const srvOpt = new PgServer({ user: 'root', password: 'secret' });
+    ok('options.user 匹配返回密码', srvOpt._userPassword('root') === 'secret');
+    ok('options.user 不匹配拒绝', srvOpt._userPassword('other') === undefined);
+  }
+
+  // ── H2. NeDB $regex ─────────────────────────────────────────
+  console.log('\n--- H2. NeDB $regex ---');
+  {
+    const ndb = new Database(':memory:');
+    await ndb.start();
+    const ds = new Datastore({ database: ndb });
+    await ds.loadDatabase();
+    await ds.insert([{ n: 'abc' }, { n: 'abcd' }, { n: 'zzz' }, { n: 42 }]);
+    const hit = await ds.find({ n: { $regex: 'abc' } }).exec();
+    ok('字符串模式只匹配命中文档', hit.length === 2 && hit.every(d => /abc/.test(String(d.n))), hit);
+    const exact = await ds.find({ n: { $regex: '^abc$' } }).exec();
+    ok('锚定模式精确匹配', exact.length === 1 && exact[0].n === 'abc', exact);
+    const invalid = await ds.find({ n: { $regex: '(' } }).exec();
+    ok('非法模式返回空而不是全匹配', invalid.length === 0, invalid);
+    const re = await ds.find({ n: { $regex: /^abc/ } }).exec();
+    ok('RegExp 对象仍可用', re.length === 2, re.map(d => d.n));
+    await ndb.stop();
+  }
+
+  // ── H3. UPDATE 标量子查询 ───────────────────────────────────
+  console.log('\n--- H3. UPDATE 标量子查询 ---');
+  await q('CREATE TABLE a3(id INT PRIMARY KEY, v INT)');
+  await q('CREATE TABLE b3(id INT PRIMARY KEY, w INT)');
+  await q('INSERT INTO a3 VALUES (1,0),(2,0),(3,0)');
+  await q('INSERT INTO b3 VALUES (1,10),(2,20)');
+  await q('UPDATE a3 SET v = (SELECT w FROM b3 WHERE b3.id = a3.id)');
+  ok('相关标量子查询按行写入（限定符）',
+    eq((await q('SELECT id, v FROM a3')).rows, [[1, 10], [2, 20], [3, null]]),
+    (await q('SELECT id, v FROM a3')).rows);
+  ok('非相关标量子查询可用',
+    (await q('UPDATE a3 SET v = (SELECT MAX(w) FROM b3)'), (await q('SELECT id, v FROM a3')).rows.every(r => r[1] === 20)));
+  ok('SELECT 投影里的相关子查询一致',
+    eq((await q('SELECT a3.id, (SELECT w FROM b3 WHERE b3.id = a3.id) AS w FROM a3')).rows,
+      [[1, 10], [2, 20], [3, null]]));
+  ok('EXISTS 相关子查询仍正确',
+    eq((await q('SELECT a3.id FROM a3 WHERE EXISTS (SELECT 1 FROM b3 WHERE b3.id = a3.id)')).rows, [[1], [2]]));
+
+  // ── H4. BETWEEN 数值比较 ────────────────────────────────────
+  console.log('\n--- H4. BETWEEN ---');
+  ok('10 BETWEEN 2 AND 20 = 1', (await one('SELECT 10 BETWEEN 2 AND 20')) === 1);
+  ok('5 BETWEEN 10 AND 20 = 0', (await one('SELECT 5 BETWEEN 10 AND 20')) === 0);
+  ok('"10" BETWEEN 2 AND 20 仍按数值', (await one("SELECT '10' BETWEEN 2 AND 20")) === 1);
+  ok('字符串 BETWEEN 保持字典序', (await one("SELECT 'b' BETWEEN 'a' AND 'c'")) === 1);
+
+  // ── H5. 主键 NOT NULL ───────────────────────────────────────
+  console.log('\n--- H5. 主键 NULL ---');
+  await db.createTable('pk5', {
+    k: { type: 'integer', primaryKey: true },
+    v: { type: 'integer' },
+  });
+  {
+    const msg = await (async () => { try { await db.insert('pk5', { k: null, v: 1 }); return null; } catch (e) { return e.message; } })();
+    ok('非自增主键插入 NULL 报错', /cannot be null/i.test(msg || ''), msg);
+    await db.insert('pk5', { k: 1, v: 1 });
+    const upd = await (async () => { try { await db.updateById('pk5', 1, { k: null }); return null; } catch (e) { return e.message; } })();
+    ok('更新主键为 NULL 报错', /cannot be null/i.test(upd || ''), upd);
+  }
+  {
+    let accepted = false;
+    try { await q('CREATE TABLE pk5b(k INT PRIMARY KEY, v INT)'); await q('INSERT INTO pk5b VALUES (NULL, 1)'); accepted = true; } catch (_) { /* 预期抛错 */ }
+    ok('INT PRIMARY KEY 自增语义仍允许 NULL（自动取号）', accepted);
+  }
+
+  // ── H6. 索引列 = null ──────────────────────────────────────
+  console.log('\n--- H6. 索引列 null ---');
+  await q('CREATE TABLE n6(id INT PRIMARY KEY, c INT)');
+  await q('INSERT INTO n6 VALUES (1,NULL),(2,5),(3,NULL)');
+  await q('CREATE INDEX ixc ON n6(c)');
+  ok('索引列 find({c:null}) 不漏行', eq((await db.find('n6', { c: null })).map(r => r.id), [1, 3]),
+    await db.find('n6', { c: null }));
+  ok('索引列 find({c:5}) 正常', eq((await db.find('n6', { c: 5 })).map(r => r.id), [2]));
+  ok('$in 含 null 时回退全表', eq((await db.find('n6', { c: { $in: [5, null] } })).map(r => r.id), [1, 2, 3]),
+    await db.find('n6', { c: { $in: [5, null] } }));
+
+  // ── M1. 错误消息 %s ────────────────────────────────────────
+  console.log('\n--- M1. 错误消息 %s ---');
+  {
+    const e1 = createError('ER_DUP_ENTRY', 'x%s', 'k');
+    ok('参数里的 %s 不被二次替换', e1.message === "Duplicate entry 'x%s' for key 'k'", e1.message);
+    const e2 = createError('ER_DUP_ENTRY', 'only-one');
+    ok('参数不足时裸 %s 被清空', e2.message === "Duplicate entry 'only-one' for key ''", e2.message);
+  }
+
+  // ── M2. 深拷贝 ────────────────────────────────────────────
+  console.log('\n--- M2. 行深拷贝 ---');
+  await db.createTable('m2', {
+    id: { type: 'integer', primaryKey: true, autoIncrement: true },
+    meta: { type: 'json' },
+  });
+  await db.insert('m2', { meta: { a: [1, 2] } });
+  {
+    const r1 = await db.findById('m2', 1);
+    r1.meta.a.push(99);
+    const r2 = await db.findById('m2', 1);
+    ok('修改返回值不污染内部行', eq(r2.meta, { a: [1, 2] }), r2.meta);
+    const list = await db.find('m2', {});
+    list[0].meta.a.push(100);
+    const again = await db.find('m2', {});
+    ok('find() 同样返回深拷贝', eq(again[0].meta, { a: [1, 2] }), again[0].meta);
+  }
+
+  // ── M3. migrate 保留 length ────────────────────────────────
+  console.log('\n--- M3. migrate length ---');
+  {
+    const s1 = normalizeSchema({ name: { type: 'string', length: 32 } });
+    ok('显式 length 保留', s1.name.length === 32, s1.name);
+    const s2 = normalizeSchema({ name: { type: 'string', maxLength: 64 } });
+    ok('maxLength 回填为 length', s2.name.length === 64 && s2.name.maxLength === undefined, s2.name);
+    const s3 = normalizeSchema({ name: { type: 'string', length: 16, maxLength: 99 } });
+    ok('显式 length 优先于 maxLength', s3.name.length === 16, s3.name);
+    const s4 = normalizeSchema({ n: 'int' });
+    ok('字符串简写仍归一化', s4.n.type === 'integer', s4.n);
+  }
+
+  // ── M4. READ_COMMITTED 回滚 ─────────────────────────────────
+  console.log('\n--- M4. READ_COMMITTED 回滚 ---');
+  {
+    const tx = makeDb();
+    await tx.start();
+    await tx.createTable('m4', {
+      id: { type: 'integer', primaryKey: true, autoIncrement: true },
+      v: { type: 'integer' },
+    });
+    await tx.insert('m4', { v: 1 });
+    tx.begin('READ_COMMITTED');
+    await tx.insert('m4', { v: 2 });
+    tx.rollback();
+    ok('ROLLBACK 撤销已插入行', eq((await tx.find('m4', {})).map(r => r.v), [1]), await tx.find('m4', {}));
+    tx.begin('READ_COMMITTED');
+    await tx.insert('m4', { v: 3 });
+    tx.commit();
+    ok('COMMIT 保留行', eq((await tx.find('m4', {})).map(r => r.v).sort(), [1, 3]));
+    await tx.stop();
+  }
+
+  // ── M5. XOR 三值逻辑 ───────────────────────────────────────
+  console.log('\n--- M5. XOR ---');
+  ok('TRUE XOR FALSE = 1', (await one('SELECT TRUE XOR FALSE')) === 1);
+  ok('TRUE XOR TRUE = 0', (await one('SELECT TRUE XOR TRUE')) === 0);
+  ok('NULL XOR TRUE = NULL', (await one('SELECT NULL XOR TRUE')) === null);
+  ok('NULL XOR FALSE = NULL', (await one('SELECT NULL XOR FALSE')) === null);
+  ok('NULL XOR NULL = NULL', (await one('SELECT NULL XOR NULL')) === null);
+
+  // ── M6. REGEXP BINARY ──────────────────────────────────────
+  console.log('\n--- M6. REGEXP BINARY ---');
+  await q('CREATE TABLE r6(id INT PRIMARY KEY, s TEXT)');
+  await q("INSERT INTO r6 VALUES (1,'abc'),(2,'ABC')");
+  ok('默认 REGEXP 大小写不敏感', eq((await q("SELECT id FROM r6 WHERE s REGEXP 'abc'")).rows.map(r => r[0]).sort(), [1, 2]));
+  ok('REGEXP BINARY 大小写敏感', eq((await q("SELECT id FROM r6 WHERE s REGEXP BINARY 'abc'")).rows, [[1]]));
+  ok('RLIKE BINARY 同样生效', eq((await q("SELECT id FROM r6 WHERE s RLIKE BINARY 'abc'")).rows, [[1]]));
+  ok('非法正则安全返回不匹配', eq((await q("SELECT id FROM r6 WHERE s REGEXP BINARY '('")).rows, []));
+
+  // ── M9. 插件钩子优先级 ─────────────────────────────────────
+  console.log('\n--- M9. 钩子优先级 ---');
+  {
+    const engine = { _hooks: createHookRegistry() };
+    const order = [];
+    registerHook(engine, 'beforeQuery', () => { order.push('low'); return true; }, 0);
+    registerHook(engine, 'beforeQuery', () => { order.push('high'); return true; }, 10);
+    registerHook(engine, 'beforeQuery', () => { order.push('mid'); return true; }, 5);
+    await runHooks(engine, 'beforeQuery', []);
+    ok('按 priority 降序执行', eq(order, ['high', 'mid', 'low']), order);
+
+    const order2 = [];
+    const e2 = { _hooks: createHookRegistry() };
+    registerHook(e2, 'beforeQuery', () => { order2.push('a'); return true; }, 3);
+    registerHook(e2, 'beforeQuery', () => { order2.push('b'); return true; }, 3);
+    await runHooks(e2, 'beforeQuery', []);
+    ok('同 priority 保持注册顺序', eq(order2, ['a', 'b']), order2);
+  }
+
+  // ── M10. XQL NULL 传播 ────────────────────────────────────
+  console.log('\n--- M10. XQL NULL ---');
+  {
+    const rows = [{ id: 1, a: null }, { id: 2, a: 5 }, { id: 3, a: 3 }];
+    const run = (sql) => compileQuery(xqlParse(sql), {})(rows);
+    ok('a = 5 命中', eq(run('SELECT id FROM t WHERE a = 5'), [{ id: 2 }]));
+    ok('a = NULL 不命中任何行', eq(run('SELECT id FROM t WHERE a = NULL'), []));
+    ok('a != NULL 不命中任何行', eq(run('SELECT id FROM t WHERE a != NULL'), []));
+    ok('BETWEEN 正常', eq(run('SELECT id FROM t WHERE a BETWEEN 2 AND 4'), [{ id: 3 }]));
+    ok('IN (5, NULL) 只命中 5', eq(run('SELECT id FROM t WHERE a IN (5, NULL)'), [{ id: 2 }]));
+    ok('NOT IN 含 NULL 不命中（三值逻辑）', eq(run('SELECT id FROM t WHERE a NOT IN (5, NULL)'), []));
+  }
+
+  // ── M11. Mongo 内部字段 ───────────────────────────────────
+  console.log('\n--- M11. Mongo _publicDoc ---');
+  {
+    const ms = new MongoServer({});
+    ok('剥离 _deleted/_rid/_score', eq(ms._publicDoc({ _id: 1, x: 2, _rid: 9, _deleted: false, _score: 3 }), { _id: 1, x: 2 }),
+      ms._publicDoc({ _id: 1, x: 2, _rid: 9, _deleted: false, _score: 3 }));
+    ok('干净文档原样返回', eq(ms._publicDoc({ _id: 2, y: 3 }), { _id: 2, y: 3 }));
+  }
+
+  await db.stop();
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  if (fail > 0) process.exitCode = 1;
+})().catch((e) => {
+  console.error('FATAL', e);
+  process.exitCode = 1;
+});