feat(B-3): 单管线 —— QueryBuilder 只产出 AST，执行一律经 Executor

背景（PLAN-v0.7.5.md 根因 2/4）：
三个 builder 的 execute() 各自执行写入/查询，与 SQL 路径构成**两条管线**：
  - SelectQueryBuilder：无 JOIN 时直接调 engine.find（只有 JOIN 才走 executor）
  - UpdateQueryBuilder / DeleteQueryBuilder：直接调 engine.update/delete

于是同一条语义在两条路径上规则各写一份，实测差异：
  - `db.table('t').select(['t.n'])` 行键保留 `t.n`，SQL 路径归一化为 `n`
  - `select(['nope'])` 静默产出 `[{},{},{}]`（引擎不校验列存在性）
  - 不受 maxRowsPerQuery 约束
  - UPDATE/DELETE 的 `$subquery`/`$col`/`$exists` 无人解析 → 引擎判 UNKNOWN
    → **静默影响 0 行**（引擎层此前为此加了"检测到未解析标记就抛 NOT_SUPPORTED"
    的防御 —— 那是把"管线缺失"暴露成用户错误，方向错了）

改动：
1. SelectQueryBuilder / UpdateQueryBuilder / DeleteQueryBuilder 的 execute()
   统一为 `executor.execute(toAST())`；构造函数不再接收 engine。
   删掉 `if (joins.length > 0 && executor)` 的分支 —— executor 自己会在安全时
   下推到引擎，不需要 builder 代劳。
2. 生命周期钩子（beforeUpdate/afterUpdate/beforeDelete/afterDelete + onWrite
   广播）改由 Table 以回调形式注入 builder，顺序与修复前一致
   （before → executor → onWrite → after）。回调接收**实际语句**，
   因此 beforeUpdate 的 `query.where` 不再是空对象 —— 修复前 builder 路径的
   钩子能拿到 where，现在仍然能（新增测试锁定）。
3. Table 新增 requireExecutor()：拿不到执行器时**明确报错**，不再静默退化为
   "直接调引擎"。Transaction.table() 相应构造绑定同一引擎的 QueryExecutor
   （事务原子性仍由引擎的 begin/commit/rollback 提供）。
4. 删除引擎层 4 处 `containsUnresolvedSubqueries → NOT_SUPPORTED` 防御：
   写路径已不可能出现未解析标记（builder 与 SQL 都经 Executor），
   留着它会让后来者误以为"这里需要防御"。

验证：新增 tests/v080-single-pipeline.test.ts（TABLE API 与 SQL API 逐值等价，
4 引擎 × 12 项 + 跨引擎 1 项，共 57 断言）；全量 84 套件 / 1646 测试通过；
typecheck(src+tests) 与 lint 零错误。

src/engine/aria/index.ts

@@ -9,7 +9,7 @@ import { cloneRow } from '../interface';
 import type { IStorageEngine } from '../interface';
 import type { QueryPlan, TableSchema, ColumnDef, WhereCondition } from '../../constants';
 import { DatabaseError } from '../../constants';
-import { matchWhere, applyOrderBy, projectColumns, containsUnresolvedSubqueries } from '../../query/where-matcher';
+import { matchWhere, applyOrderBy, projectColumns } from '../../query/where-matcher';
 import { stripUndefinedUpdates } from '../../table/schema';
 import { compileValidator } from '../../table/validation';
 
@@ -778,12 +778,16 @@ export class AriaEngine implements IStorageEngine {
     this.ensureTable(tableName);
     // v0.7.4: 防御 —— QueryBuilder 直通引擎不经 Executor 子查询解析，
     // 未解析的 $subquery/$col/$exists 在 matchWhere 中恒 false → 静默 0 行
-    if (containsUnresolvedSubqueries(query.where)) {
-      throw new DatabaseError(
-        'Unresolved subqueries/column references in UPDATE WHERE (use db.query() to execute subqueries)',
-        'NOT_SUPPORTED',
-      );
-    }
+    // v0.8.0（B-3）：**不再需要**"检测到未解析标记就抛 NOT_SUPPORTED"的防御。
+    //
+    // 那段防御存在的原因是 QueryBuilder 直通引擎、绕过了 Executor 的子查询解析，
+    // 于是 `$subquery`/`$col`/`$exists` 在引擎层判 UNKNOWN → 静默影响 0 行。
+    // B-3 把 builder 改为"只产出 AST、执行一律经 Executor"之后，写路径上不可能
+    // 再出现未解析标记 —— 把"管线缺失"暴露成用户错误（NOT_SUPPORTED）是错误的
+    // 补救方向：用户没有做错任何事。
+    //
+    // 保留 `containsUnresolvedSubqueries` 的导入会给后来者"这里需要防御"的错觉，
+    // 因此一并移除（见 where-matcher 中该函数仍被 Executor 用于写路径预检）。
     const schema = this.schemas.get(tableName)!;
     const rows = await this.getAllRows(tableName);
     let count = 0;
@@ -1051,12 +1055,16 @@ export class AriaEngine implements IStorageEngine {
     this.ensureTable(tableName);
     // v0.7.4: 防御 —— QueryBuilder 直通引擎不经 Executor 子查询解析，
     // 未解析的 $subquery/$col/$exists 在 matchWhere 中恒 false → 静默 0 行
-    if (containsUnresolvedSubqueries(query.where)) {
-      throw new DatabaseError(
-        'Unresolved subqueries/column references in DELETE WHERE (use db.query() to execute subqueries)',
-        'NOT_SUPPORTED',
-      );
-    }
+    // v0.8.0（B-3）：**不再需要**"检测到未解析标记就抛 NOT_SUPPORTED"的防御。
+    //
+    // 那段防御存在的原因是 QueryBuilder 直通引擎、绕过了 Executor 的子查询解析，
+    // 于是 `$subquery`/`$col`/`$exists` 在引擎层判 UNKNOWN → 静默影响 0 行。
+    // B-3 把 builder 改为"只产出 AST、执行一律经 Executor"之后，写路径上不可能
+    // 再出现未解析标记 —— 把"管线缺失"暴露成用户错误（NOT_SUPPORTED）是错误的
+    // 补救方向：用户没有做错任何事。
+    //
+    // 保留 `containsUnresolvedSubqueries` 的导入会给后来者"这里需要防御"的错觉，
+    // 因此一并移除（见 where-matcher 中该函数仍被 Executor 用于写路径预检）。
 
     const rows = await this.getAllRows(tableName);
     let count = 0;

src/engine/memory.ts

@@ -7,7 +7,7 @@ import type { IStorageEngine } from './interface';
 import type { QueryPlan, TableSchema, WhereCondition } from '../constants';
 import { DatabaseError } from '../constants';
 import { cloneRow } from './interface';
-import { matchWhere, applyOrderBy, projectColumns, containsUnresolvedSubqueries } from '../query/where-matcher';
+import { matchWhere, applyOrderBy, projectColumns } from '../query/where-matcher';
 import { stripUndefinedUpdates } from '../table/schema';
 import { compileValidator, type RowValidator } from '../table/validation';
 
@@ -289,14 +289,16 @@ export class MemoryEngine implements IStorageEngine {
     // v0.7.2: undefined 值视为"不更新该列"（保留旧值），null 显式置空
     const cleanUpdates = stripUndefinedUpdates(updates);
 
-    // v0.7.4: 防御 —— QueryBuilder 直通引擎不经 Executor 子查询解析，
-    // 未解析的 $subquery/$col/$exists 在 matchWhere 中恒 false → 静默 0 行
-    if (containsUnresolvedSubqueries(query.where)) {
-      throw new DatabaseError(
-        'Unresolved subqueries/column references in UPDATE WHERE (use db.query() to execute subqueries)',
-        'NOT_SUPPORTED',
-      );
-    }
+    // v0.8.0（B-3）：**不再需要**"检测到未解析标记就抛 NOT_SUPPORTED"的防御。
+    //
+    // 那段防御存在的原因是 QueryBuilder 直通引擎、绕过了 Executor 的子查询解析，
+    // 于是 `$subquery`/`$col`/`$exists` 在引擎层判 UNKNOWN → 静默影响 0 行。
+    // B-3 把 builder 改为"只产出 AST、执行一律经 Executor"之后，写路径上不可能
+    // 再出现未解析标记 —— 把"管线缺失"暴露成用户错误（NOT_SUPPORTED）是错误的
+    // 补救方向：用户没有做错任何事。
+    //
+    // 保留 `containsUnresolvedSubqueries` 的导入会给后来者"这里需要防御"的错觉，
+    // 因此一并移除（见 where-matcher 中该函数仍被 Executor 用于写路径预检）。
 
     // v0.7.4: 未知列显式报错 —— 此前 SET nonexistent = ... 被静默写入存储行
     // （validateRow 只遍历 schema 列，脏列残留在行内并随持久化落盘）
@@ -532,14 +534,16 @@ export class MemoryEngine implements IStorageEngine {
 
   async delete(tableName: string, query: QueryPlan): Promise<number> {
     this.ensureTable(tableName);
-    // v0.7.4: 防御 —— QueryBuilder 直通引擎不经 Executor 子查询解析，
-    // 未解析的 $subquery/$col/$exists 在 matchWhere 中恒 false → 静默 0 行
-    if (containsUnresolvedSubqueries(query.where)) {
-      throw new DatabaseError(
-        'Unresolved subqueries/column references in DELETE WHERE (use db.query() to execute subqueries)',
-        'NOT_SUPPORTED',
-      );
-    }
+    // v0.8.0（B-3）：**不再需要**"检测到未解析标记就抛 NOT_SUPPORTED"的防御。
+    //
+    // 那段防御存在的原因是 QueryBuilder 直通引擎、绕过了 Executor 的子查询解析，
+    // 于是 `$subquery`/`$col`/`$exists` 在引擎层判 UNKNOWN → 静默影响 0 行。
+    // B-3 把 builder 改为"只产出 AST、执行一律经 Executor"之后，写路径上不可能
+    // 再出现未解析标记 —— 把"管线缺失"暴露成用户错误（NOT_SUPPORTED）是错误的
+    // 补救方向：用户没有做错任何事。
+    //
+    // 保留 `containsUnresolvedSubqueries` 的导入会给后来者"这里需要防御"的错觉，
+    // 因此一并移除（见 where-matcher 中该函数仍被 Executor 用于写路径预检）。
     const table = this.tables.get(tableName)!;
     const toDelete: { pk: string; row: Record<string, unknown> }[] = [];
     for (const [pk, row] of table) {

src/query/builder.ts

@@ -2,11 +2,26 @@
  * metona-sqlark Query Builder — 链式查询构建器
  * @module query/builder
  *
- * 链式调用 → 构建 AST → 执行引擎操作。
- * 支持 JOIN（需要 Executor）。
+ * ============================================================================
+ * v0.8.0（B-3）：**只产出 AST，执行一律交给 Executor**
+ * ============================================================================
+ * 修复前每个 builder 的 `execute()` 都有自己的执行动作：
+ *   - `SelectQueryBuilder`：**无 JOIN 时直接调 `engine.find`**，只有 JOIN 才走
+ *     executor；
+ *   - `UpdateQueryBuilder` / `DeleteQueryBuilder`：直接调 `engine.update/delete`。
+ *
+ * 于是"同一条语义"在 builder 路径与 SQL 路径上走两条管线，规则各写一份：
+ *   - SELECT 的常量列/别名/CASE 投影在 builder 路径不存在
+ *     （`db.table('t').select(['t.n'])` 的输出键、`SELECT 1` 之类行为不同）；
+ *   - `maxRowsPerQuery`、`distinct`、`groupBy`/`having`、`fromSubquery` 等阶段
+ *     在直通路径上完全不经过；
+ *   - 未解析的 `$subquery`/`$col` 在直通路径上无人解析 → 引擎判 UNKNOWN →
+ *     **静默 0 行**（这正是 v0.7.4 要为此加"显式拒绝"防御的原因）。
+ *
+ * 现在 builder 只负责"拼 AST"，执行统一走 `executor.execute(ast)`；
+ * 需要直通时由 executor 内部判断（它本来就是唯一知道"能不能下推"的地方）。
  */
 
-import type { IStorageEngine } from '../engine/interface';
 import type { WhereCondition, OrderBy, SortDirection } from '../constants';
 import type { SelectStatement, UpdateStatement, DeleteStatement, JoinType, JoinClause } from './ast';
 import { QueryExecutor } from './executor';
@@ -22,13 +37,12 @@ export class SelectQueryBuilder {
   private _offset?: number;
   private _joins: JoinClause[] = [];
   private _alias?: string;
-  private _executor?: QueryExecutor;
+  private _executor: QueryExecutor;
 
   constructor(
-    private engine: IStorageEngine,
     private tableName: string,
+    executor: QueryExecutor,
     private _columns: string[] = ['*'],
-    executor?: QueryExecutor,
   ) {
     this._executor = executor;
   }
@@ -93,23 +107,15 @@ export class SelectQueryBuilder {
     return this;
   }
 
-  /** 执行查询 */
+  /**
+   * 执行查询 —— 拼出 AST 后交给 Executor（**唯一**执行管线）。
+   *
+   * 注意不要再为"无 JOIN"加一条 `engine.find` 快路：那条路会绕过
+   * 投影/列校验/LIMIT 下推判定/maxRowsPerQuery，从而与 `db.query()` 给出不同结果
+   * （B-3 修复前的实际状态）。executor 自己会在安全时下推到引擎，不需要 builder 代劳。
+   */
   async execute(): Promise<Record<string, unknown>[]> {
-    // 有 JOIN → 通过 Executor 执行
-    if (this._joins.length > 0 && this._executor) {
-      const ast = this.toAST();
-      return this._executor.execute(ast) as Promise<Record<string, unknown>[]>;
-    }
-
-    // 无 JOIN → 直接调用引擎
-    return this.engine.find(this.tableName, {
-      table: this.tableName,
-      columns: this._columns,
-      where: this._where,
-      orderBy: this._orderBy.length > 0 ? this._orderBy : undefined,
-      limit: this._limit,
-      offset: this._offset,
-    });
+    return this._executor.execute(this.toAST()) as Promise<Record<string, unknown>[]>;
   }
 
   /** 获取 AST */
@@ -134,32 +140,47 @@ export class SelectQueryBuilder {
 
 export class UpdateQueryBuilder {
   private _where: WhereCondition = {};
-  private onWrite?: (table: string) => void;
-  /** v0.5.1: CRUD hooks 触发回调 */
-  private onHooks?: (hook: import('../constants').HookName, args: unknown[]) => Promise<void>;
 
   constructor(
-    private engine: IStorageEngine,
     private tableName: string,
     private _updates: Record<string, unknown>,
-    onWrite?: (table: string) => void,
-    onHooks?: (hook: import('../constants').HookName, args: unknown[]) => Promise<void>,
-  ) {
-    this.onWrite = onWrite;
-    this.onHooks = onHooks;
-  }
+    private executor: QueryExecutor,
+    /**
+     * TABLE API 的生命周期回调（`beforeUpdate` / `afterUpdate` / onWrite 广播）。
+     *
+     * 为什么由 `Table` 注入而不是 builder 自己触发：builder 的职责是**产出 AST**，
+     * 它不该知道钩子/广播的存在（否则又会像修复前那样"builder 顺带把写入也做了"，
+     * 从而绕过 Executor）。钩子被包裹在**唯一管线**之外，
+     * 顺序与修复前完全一致：before → executor → onWrite → after。
+     *
+     * 回调接收**实际执行的语句**（含 builder 上累积的 where），
+     * 而不是构造 builder 时的空 where —— 后者会让 `beforeUpdate` 的
+     * `query.where` 永远是 `{}`（钩子拿不到过滤条件，等于信息缺失）。
+     */
+    private hooks?: {
+      before?: (stmt: UpdateStatement) => Promise<void>;
+      after?: (count: number, stmt: UpdateStatement) => Promise<void>;
+    },
+  ) {}
 
   where(condition: WhereCondition): this {
     this._where = { ...this._where, ...condition };
     return this;
   }
 
+  /**
+   * 执行更新 —— 走 Executor（唯一的写管线）。
+   *
+   * 修复前这里直接调 `engine.update`：`$subquery` / `$col` / `$exists` 无人解析，
+   * 引擎层 matchWhere 判 UNKNOWN → **静默影响 0 行**（返回 0 且无报错）。
+   * 引擎层为此加过"检测未解析标记就抛 NOT_SUPPORTED"的防御 —— 那是把
+   * "管线缺失"暴露成用户错误；正确做法是把请求送进唯一管线。
+   */
   async execute(): Promise<number> {
-    const query = { table: this.tableName, where: this._where };
-    await this.onHooks?.('beforeUpdate', [query, this._updates]);
-    const count = await this.engine.update(this.tableName, query, this._updates);
-    this.onWrite?.(this.tableName);
-    await this.onHooks?.('afterUpdate', [query, this._updates, count]);
+    const stmt = this.toAST();
+    await this.hooks?.before?.(stmt);
+    const count = await this.executor.execute(stmt) as number;
+    await this.hooks?.after?.(count, stmt);
     return count;
   }
 
@@ -174,31 +195,28 @@ export class UpdateQueryBuilder {
 
 export class DeleteQueryBuilder {
   private _where: WhereCondition = {};
-  private onWrite?: (table: string) => void;
-  /** v0.5.1: CRUD hooks 触发回调 */
-  private onHooks?: (hook: import('../constants').HookName, args: unknown[]) => Promise<void>;
 
   constructor(
-    private engine: IStorageEngine,
     private tableName: string,
-    onWrite?: (table: string) => void,
-    onHooks?: (hook: import('../constants').HookName, args: unknown[]) => Promise<void>,
-  ) {
-    this.onWrite = onWrite;
-    this.onHooks = onHooks;
-  }
+    private executor: QueryExecutor,
+    /** TABLE API 生命周期回调，语义见 `UpdateQueryBuilder` 的说明 */
+    private hooks?: {
+      before?: (stmt: DeleteStatement) => Promise<void>;
+      after?: (count: number, stmt: DeleteStatement) => Promise<void>;
+    },
+  ) {}
 
   where(condition: WhereCondition): this {
     this._where = { ...this._where, ...condition };
     return this;
   }
 
+  /** 执行删除 —— 走 Executor（同 UpdateQueryBuilder.execute 的理由） */
   async execute(): Promise<number> {
-    const query = { table: this.tableName, where: this._where };
-    await this.onHooks?.('beforeDelete', [query]);
-    const count = await this.engine.delete(this.tableName, query);
-    this.onWrite?.(this.tableName);
-    await this.onHooks?.('afterDelete', [query, count]);
+    const stmt = this.toAST();
+    await this.hooks?.before?.(stmt);
+    const count = await this.executor.execute(stmt) as number;
+    await this.hooks?.after?.(count, stmt);
     return count;
   }
 

src/table/table.ts

@@ -70,7 +70,25 @@ export class Table<T = Record<string, unknown>> {
   // ---- 查询 ----
 
   select(columns: string[] = ['*']): SelectQueryBuilder {
-    return new SelectQueryBuilder(this.engine, this.name, columns, this.executor);
+    return new SelectQueryBuilder(this.name, this.requireExecutor('select'), columns);
+  }
+
+  /**
+   * v0.8.0（B-3）：取执行器；缺失即**明确失败**。
+   *
+   * 修复前 builder 在拿不到 executor 时会退化为"直接调引擎" —— 于是
+   * `db.table('t')` 与 `db.query()` 两条路径的语义不同（投影/列校验/LIMIT 下推/
+   * maxRowsPerQuery 在直通路径上全部缺失）。现在只保留一条管线：
+   * 没有 executor 就没有可用的查询 API，显式报错而不是悄悄降级。
+   */
+  private requireExecutor(operation: string): QueryExecutor {
+    if (!this.executor) {
+      throw new DatabaseError(
+        `Table.${operation}() requires a query executor (obtain the table via db.table())`,
+        'NOT_SUPPORTED',
+      );
+    }
+    return this.executor;
   }
 
   /** v0.4.0: 流式查询 — 逐行回调，不物化全部结果 */
@@ -100,14 +118,39 @@ export class Table<T = Record<string, unknown>> {
 
   // ---- 更新 ----
 
+  /**
+   * v0.8.0（B-3）：写操作也走**唯一管线**（Executor），生命周期钩子由本方法注入。
+   *
+   * 修复前 `UpdateQueryBuilder` 直接调 `engine.update`：`$subquery`/`$col` 无人解析
+   * → 引擎判 UNKNOWN → 静默影响 0 行；`beforeUpdate`/`afterUpdate` 的触发点也因此
+   * 与 SQL 路径不同（一条在 builder 里、一条在 core 里）。
+   */
   update(updates: Partial<T> & Record<string, unknown>): UpdateQueryBuilder {
-    return new UpdateQueryBuilder(this.engine, this.name, updates, this.onWrite, this.onHooks);
+    return new UpdateQueryBuilder(this.name, updates, this.requireExecutor('update'), {
+      // 钩子接收实际语句（含 builder 累积的 where），与 SQL 路径的
+      // `triggerStatementHooks` 传参形状一致：{ table, where }
+      before: async (stmt) => {
+        await this.onHooks?.('beforeUpdate', [{ table: stmt.table, where: stmt.where }, updates]);
+      },
+      after: async (count, stmt) => {
+        this.onWrite?.(this.name);
+        await this.onHooks?.('afterUpdate', [{ table: stmt.table, where: stmt.where }, updates, count]);
+      },
+    });
   }
 
   // ---- 删除 ----
 
   delete(): DeleteQueryBuilder {
-    return new DeleteQueryBuilder(this.engine, this.name, this.onWrite, this.onHooks);
+    return new DeleteQueryBuilder(this.name, this.requireExecutor('delete'), {
+      before: async (stmt) => {
+        await this.onHooks?.('beforeDelete', [{ table: stmt.from, where: stmt.where }]);
+      },
+      after: async (count, stmt) => {
+        this.onWrite?.(this.name);
+        await this.onHooks?.('afterDelete', [{ table: stmt.from, where: stmt.where }, count]);
+      },
+    });
   }
 
   // ---- 聚合 ----

src/transaction/index.ts

@@ -8,6 +8,7 @@
 import type { IStorageEngine } from '../engine/interface';
 import { Table } from '../table/table';
 import { DatabaseError } from '../constants';
+import { QueryExecutor } from '../query/executor';
 
 // ---------------------------------------------------------------------------
 //  Transaction
@@ -17,16 +18,26 @@ export class Transaction {
   private engine: IStorageEngine;
   private tables: Map<string, Table> = new Map();
   private completed = false;
+  /**
+   * v0.8.0（B-3）：事务内的表操作同样走**唯一执行管线**。
+   *
+   * `Table` 的 select/update/delete 现在必须拿到 executor（builder 只产出 AST），
+   * 因此这里构造一个绑定到同一引擎的执行器 —— 事务的原子性由**引擎**提供
+   * （begin/commit/rollback 作用在引擎上），执行器只是把 AST 翻译成引擎调用，
+   * 两者组合即可保持"事务内写入可回滚"这一语义不变。
+   */
+  private executor: QueryExecutor;
 
   constructor(engine: IStorageEngine) {
     this.engine = engine;
+    this.executor = new QueryExecutor(engine);
   }
 
   /** 获取表操作对象 */
   table(tableName: string): Table {
     let t = this.tables.get(tableName);
     if (!t) {
-      t = new Table(this.engine, tableName);
+      t = new Table(this.engine, tableName, this.executor);
       this.tables.set(tableName, t);
     }
     return t;