@sema-agent/server 7.131.0 → 7.133.0

package/dist/plugins/sql-driver.d.ts

@@ -111,6 +111,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import type { Logger } from "../observability/logger.js";
 export type SqlDialect = "tidb" | "pg";
 export type SqlRow = Record<string, unknown>;
 /** Normalized statement result: `rows` for SELECTs, `affected` for INSERT/UPDATE/DELETE. */
@@ -157,7 +158,168 @@ export interface SqlEngineFacts {
     readonly isolation: string;
     /** TiDB's session `tidb_txn_mode`; `null` = this engine has no such indicator (NOT "optimistic"). */
     readonly txnMode: "pessimistic" | null;
+    /**
+     * The largest single row this engine stores, in bytes — the **one** source of that number in this repo. Every
+     * row this service writes from a submitted request (the user message in `session_event`, the resume inputs in
+     * `checkpoint_ctx`) has to fit it, so the submit admission reads it (`http/request-guards.ts`
+     * `refuseSubmitBody`) instead of carrying a copy of the number.
+     *  · **TiDB** — the effective `txn-entry-size-limit`, read at initialization: the session variable
+     *    `@@tidb_txn_entry_size_limit` when it is non-zero (TiDB 7.6+; 0 there means "use the config item"), else
+     *    `performance.txn-entry-size-limit` from `SHOW CONFIG` (the smallest value across TiDB instances: a request
+     *    may land on any of them). Neither readable (the config read needs the `CONFIG` privilege; older TiDB has no
+     *    session variable) ⇒ TiDB's own default {@link TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT}, recorded through
+     *    `recordFailOpen("server.sql.tidb-row-cap-unread")` (a per-hit count and one warn line naming both reads).
+     *  · **`null`** — this engine has **no single-row wall** below the request cap: PostgreSQL (`jsonb` holds 255 MiB)
+     *    and InnoDB (it has no row-size wall of this kind; its wall is the statement-level one, a different fact:
+     *    {@link maxPacketBytes}). `null` is the ONLY spelling of "no wall" — an unreadable value is never folded into it.
+     *    Only two writes translate a row-size refusal into the coded
+     *    `StoreRowTooLargeError` (`sql-errors.ts`): the checkpoint store's `putCtx` (resume inputs) and `put` (the INSERT of
+     *    a pending row). Every other write — the checkpoint store's updates (`resolve` / `reopen` / …), the session log —
+     *    keeps its existing driver error.
+     * **Level**: the TiDB config item is per TiDB instance, read as the minimum across instances (so the reading does not depend
+     * on which instance a connection landed on); the 7.6+ variable is read as this connection sees it at initialization. Its
+     * readers: the submit admission reads it off {@link SqlDriver.facts} (it has no connection in hand); the SQL snapshot-blob cap
+     * reads it off the connection that writes the blob ({@link sqlConnectionFacts}). This version does not change how it is read.
+     */
+    readonly maxRowBytes: number | null;
+    /**
+     * The largest single statement the server accepts on **this connection**, in bytes — its session `@@max_allowed_packet`.
+     * A second wall, so a second fact (one fact per wall; `null` always and only means "this engine has no such wall").
+     * **Level: one physical connection.** The server copies the session value from the global one when the connection is
+     * established and never changes it afterwards: after a DBA changes the global value, connections opened later carry the
+     * new value and the ones already pooled keep theirs until the pool replaces them. So the reading lives with the connection
+     * that took it: read once at that connection's initialization, kept with it, and judged on it.
+     *  · **MySQL protocol — InnoDB and TiDB alike**: read at connection initialization, in the same place and with the
+     *    same unreadable disposition as {@link maxRowBytes} on TiDB: the variable unknown / the query failing / a value that
+     *    is not a positive integer ⇒ the documented default of that server family
+     *    ({@link PACKET_CAP_UNREAD_LANDING_BYTES}), recorded through `recordFailOpen("server.sql.packet-cap-unread")` (a per-hit
+     *    count and one warn line naming the reason). Never `null`: on these engines the wall exists, only its size may be unread.
+     *  · **`null`** — PostgreSQL: the extended protocol has no statement-size wall.
+     * Its final judge: the SQL snapshot-blob cap (`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`), which borrows the connection
+     * it will write on through {@link connectJudged}, reads this off it ({@link sqlConnectionFacts}), judges, and writes on that
+     * same connection — and when it refuses on a connection opened before the DBA raised the wall, that stale connection is
+     * replaced and the write judged once more ({@link connectJudged}). On {@link SqlDriver.facts} the value is the most recently
+     * initialized connection's reading (the operator read face `GET /v1/diagnostics/wiring` → `sqlEngine.maxPacketBytes`, and
+     * the submit admission's early run of the same rule — `http/request-guards.ts` `refuseSubmitBody`: it has no connection in
+     * hand, so it pre-judges against the newest reading the pool has — a cached value that moves only when a connection is
+     * initialized, so right after a DBA changes the global value it can lag in either direction; the database on the writing
+     * connection stays the final judge of a submitted body). Both readers (the blob cap on the borrowed connection's own facts, the admission on the pool's) read the walls
+     * — this one and {@link maxRowBytes} — through the one judge {@link sqlWallsOf}, which also says what holds when the facts themselves are absent.
+     */
+    readonly maxPacketBytes: number | null;
+    /**
+     * Where each wall's number came from — the **one** record of "read, or fell back to a documented default", parallel to {@link maxRowBytes} and
+     * {@link maxPacketBytes} (see {@link SqlWallSource}). `"reported"` = the database answered at connection initialization (or, for a `null` wall,
+     * the engine has no such wall by construction); `"assumed"` = the reading failed and the documented default of the server family stands in for the
+     * number (the same two reads that go through `recordFailOpen`). The submit admission and the SQL snapshot-blob cap report it as `wallSource`, so a
+     * refusal never presents a default as the database's own limit.
+     */
+    readonly wallSources: SqlWallSources;
 }
+/** TiDB's documented default for `performance.txn-entry-size-limit` (6 MiB): the cap a single row (key + value)
+ *  may reach. Used only when the engine's own reading cannot be had ({@link SqlEngineFacts.maxRowBytes}). */
+export declare const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6291456;
+/**
+ * 一份载荷落进库行时,行里**载荷之外**的那部分的余量(字节)—— **按行的形各一只**:行墙只有一堵(`SqlEngineFacts.maxRowBytes`),余量是落进它的那种行的物理,
+ * 两种行的余量差两个数量级,借用就会让一个读者的门限偏离它自己那种行能装下的量。
+ *  · `json` —— 提交体落进的两种行:会话日志里的用户消息(`session_event.payload`:条目把内联图 / 附件 / objective 包上 id 与时间戳)与 durable 审批部署上的续跑输入
+ *    (`checkpoint_ctx.ctx`:体 + 写者版本 / memoryScope / 两枚读法记号)。余量盖住其余全部:
+ *     - 包装键与行上的其余列:几百字节(TiDB 7.5.1 实测:体里带一只 6 815 544 字符串的续跑输入行,库报 6 815 845 字节 —— 比那只串多 301 字节,其中约 105 字节是串外面的 JSON 文本);
+ *     - TiDB 以二进制形存 JSON,每个数组元素 / 对象成员比文本多约 5–11 字节;一份提交体的结构(三只规则桶各 ≤ 1000 条、agents、skills…)在几千个元素以内 ⇒ 几十 KiB。
+ *    64 KiB 盖住这两件还有富余;结构超出它的体照样会被库在写的那一刻拒 —— 提交时写续跑输入的那一笔(durable 审批部署)答同一个 413(店的带码拒,`submit-ctx.ts`),
+ *    开跑后的写(会话日志的用户消息)按各自的既有失败面。
+ *  · `blob` —— SQL 快照 blob 的行(`snapshot_blob` / `file_history_blob`:`blob_hash CHAR(64)` 主键 + `byte_len BIGINT` + `created_at DATETIME(3)` + `bytes LONGBLOB`)。
+ *    TiDB 的单行上限量的是这一行的键值对。键 ≈ 表前缀 `t` + 8 字节表 id + `_r` + 行句柄(非聚簇 8 字节;聚簇时是 CHAR(64) 主键的可比较编码,每 8 字节加 1 字节组标 = 72 字节)
+ *    ⇒ 至多约 83 字节;值 = 行格式 v2:头 6 字节 + 4 列的列 id 与偏移(大行形各 4 字节 = 32 字节)+ 三列定长数据(哈希 64 + 长度 8 + 时间 8 = 80 字节)+ 可选行校验 5 字节
+ *    ⇒ 约 123 字节。合计约 206 字节;字节列按原字节存,没有 JSON 的逐元素开销。取 1 KiB = 实需的近 5 倍(与包墙那只语句余量 {@link STATEMENT_ALLOWANCE_BYTES} 同一量级),
+ *    真库读数由 db 组 `sql-txn-semantics-integration` ①c 钉(恰在帽上的 blob 真写得进)。
+ *
+ * 余量是**墙的物理**:每堵墙、每种行一只余量,各只在这里定义一次;两个读者(提交体受理口读 `json`、blob 缺省帽读 `blob`)经 {@link rowWallPayloadBytes} 按行的形取。
+ */
+export declare const ROW_WALL_ALLOWANCE_BYTES: {
+    readonly json: number;
+    readonly blob: 1024;
+};
+/** 落进行墙的两种行(见 {@link ROW_WALL_ALLOWANCE_BYTES})。 */
+export type RowWallRowShape = keyof typeof ROW_WALL_ALLOWANCE_BYTES;
+/**
+ * 一条语句里**载荷之外**的字节余量 —— 固定语句文本 + 表名 + 64 字符哈希 + 长度 + 时间戳 + 行包装(mysql2 真格式化量过:最长表名
+ * `file_history_blob` 的 blob INSERT 在 blob 之外 240 字节)。1 KiB 盖住它的 4 倍还多,又不松到压低可用量(16 MiB 包墙下少 1 KiB)。
+ * 不扣的话恰在包墙上的载荷整条语句会超出包墙几百字节:放行、库在写那一刻拒。经 {@link packetWallStatementBytes} 被两个读者共读(同一只规则:blob 帽的终判、提交体受理口的提前一跑)。
+ */
+export declare const STATEMENT_ALLOWANCE_BYTES = 1024;
+/** 行墙下一份载荷最多多少字节:`max(0, 行墙 − 这种行的余量)`({@link ROW_WALL_ALLOWANCE_BYTES})。受理口的提交体门限读 `json`、blob 缺省帽的行墙腿读 `blob`。 */
+export declare function rowWallPayloadBytes(maxRowBytes: number, row: RowWallRowShape): number;
+/**
+ * 包墙下一条语句里的载荷最多多少字节:`max(0, 包墙 − {@link STATEMENT_ALLOWANCE_BYTES})` —— 包墙这一只规则的**唯一**算式,两个读者:
+ *  · blob 缺省帽的包墙腿(再按膨胀律折半),包墙取自将要执行写入的那条连接 —— **终判**;
+ *  · 提交体受理口(量的是转义后的语句字节,{@link escapedStatementBytes}),包墙取自池里最近初始化的那条连接 —— 同一只规则的**提前一跑**
+ *    (受理时手里没有将要写入的连接;拒 ⇒ 413 在任何副作用之前,收 ⇒ 写入那条连接上的库仍是终判)。
+ */
+export declare function packetWallStatementBytes(maxPacketBytes: number): number;
+/**
+ * 一段文本作为**一只字符串字面**进 MySQL 协议语句时占的字节数(不含外层两只引号)—— 店真正发出去的字节,不是文本自己的字节数。
+ * 店用 `query(sql, [text])`,mysql2 在客户端把参数格式化进语句(`sql-escaper` 的 `escapeString`):`\0 \b \t \n \r \x1a " ' \` 九个字符各变成两个字符
+ * (多一个反斜杠字节),其余字符原样 —— 多字节 UTF-8 不受影响。所以一份 JSON 里引号 / 反斜杠越多,语句越比文本长(上界 2×:每个字符至多多一字节)。
+ *
+ * 受理口的包墙腿量它(`http/request-guards.ts` `refuseSubmitBody`):门承诺「按池见过的最新包墙读数写不进去的体在任何副作用之前 413」,量的就必须是语句字节。
+ * 这是 mysql2 转义表的**镜像**,不是第二份读法:`test/store-row-cap.test.ts` 把它逐字钉在 mysql2 自己的 `escape` 上(`escapedStatementBytes(s) ===
+ * Buffer.byteLength(mysql.escape(s)) − 2`,含全码点表扫),mysql2 升级改转义表时那格先红。不直接调 `escape` 取长度,是因为那会为一份 8 MiB 的体再造一份 8–16 MiB 的字符串。
+ */
+export declare function escapedStatementBytes(text: string): number;
+/**
+ * The documented default `max_allowed_packet`, per MySQL-protocol engine family — the landing when the live reading cannot be
+ * had ({@link SqlEngineFacts.maxPacketBytes}). Closed over the MySQL-protocol engines (an engine added to {@link SqlEngine} is a
+ * compile error here until its row is written).
+ *  · **tidb** — 64 MiB (67 108 864): TiDB's system-variable reference, `max_allowed_packet`, default `67108864`.
+ *  · **innodb** — 16 MiB (16 777 216): the smaller of the two documented defaults among the servers behind this word — MariaDB
+ *    16 MiB (its server-system-variables reference, `max_allowed_packet`, default `16777216`) and MySQL 8.0 64 MiB (its
+ *    server-system-variables reference, default `67108864`; 5.7 and before shipped 4 MiB, outside the supported set). A landing above
+ *    the true wall lets through a write the server refuses; below it only refuses early, so the smaller one is the landing.
+ */
+export declare const PACKET_CAP_UNREAD_LANDING_BYTES: {
+    readonly tidb: 67108864;
+    readonly innodb: 16777216;
+};
+/** 一份写入要装进的两堵墙 —— {@link SqlEngineFacts} 里的那两位(`null` 恒且只表示「这堵墙不存在」)。 */
+export type SqlWalls = Pick<SqlEngineFacts, "maxRowBytes" | "maxPacketBytes">;
+/**
+ * 一个墙数字从哪来(上 wire:413 拒体的 `wallSource`)—— **只看「这个数是不是库自己报的」**:
+ *  · `reported` = 库报的:引擎在连接初始化时读到的(或按构造没有这堵墙:没有 SQL 后端、PostgreSQL、InnoDB 的行墙);
+ *  · `assumed` = 不是库报的、是受支持引擎里最保守的缺省顶上的:引擎事实还没建立(连是哪个引擎都不知道,{@link SQL_FACTS_ABSENT_WALLS}),
+ *    或事实在场但这一堵墙读失败、退回了文档缺省({@link SqlEngineFacts.wallSources} 逐墙记着,登记过的 fail-open)。
+ */
+export type SqlWallSource = "reported" | "assumed";
+/** 两堵墙各自的出处(与 {@link SqlWalls} 同键):事实里一处记录,判官 {@link sqlWallsOf} 原样带出。 */
+export type SqlWallSources = {
+    readonly [K in keyof SqlWalls]: SqlWallSource;
+};
+/** {@link sqlWallsOf} 的读数:两堵墙 + 它们各自从哪来(逐墙:一堵读到、另一堵退缺省时,拒哪一堵就报哪一堵的出处)。 */
+export interface SqlWallsReading extends SqlWalls {
+    readonly sources: SqlWallSources;
+}
+/**
+ * 一只 SQL 池的**引擎读口**:方言(SQL 文本轴,装配事实,恒在)+ 此刻的引擎事实(`null` = 没建立)。墙的方言只从这里来 —— 与事实同出一只驱动
+ * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobBackend`)各读本池的这一只。
+ */
+export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
+/**
+ * MySQL 协议方言上**事实缺席**时的墙(池上还没建立过,或最近一次连接初始化被拒:`SqlDriver.facts === null`)。这时连引擎是哪一个都不知道,
+ * 每堵墙各取受支持引擎里最矮的一格:行墙 = TiDB 自己的缺省(InnoDB 没有行墙,保守取有墙的那一个),包墙 = 各引擎族文档缺省里最小的那个
+ * ({@link PACKET_CAP_UNREAD_LANDING_BYTES})—— 没读到事实时的墙不会比读到任何一个缺省事实时的墙更松。它们是**假定**的墙(两堵的出处都是 `assumed`),
+ * 拒句不能把它们说成库报的墙。
+ */
+export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
+/**
+ * 🔴 **此刻一份写入要装进的墙 —— 唯一判官**。两个读者同调它、不各读 `facts`:提交受理口(`http/request-guards.ts` `refuseSubmitBody`)与 SQL 快照 blob 的缺省帽
+ * (`plugins/blob-backend.ts` `sqlBlobCapOf`:店的写前判,读的是**将要执行写入的那条连接**的读口 —— 方言 + 它自己那次初始化的事实;受理口读本池驱动的读口)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出),一种读法:
+ *  · 读口缺席 = 没有 SQL 后端 ⇒ 没有墙(「忘了给」读不成这一臂:后端交出了 SQL 池而没给读口 ⇒ `createHttpServer` 起服拒,见 `ServiceDeps.sqlEngine`);
+ *  · 事实在场 ⇒ 事实里的两位,出处逐墙取事实里记的那一份({@link SqlEngineFacts.wallSources}:读到的 `reported`,读失败退文档缺省的 `assumed`);
+ *  · 事实缺席(`null`)⇒ 按读口的方言:PG 没有墙(扩展协议没有这两堵墙 —— 方言事实,不随引擎事实缺席);MySQL 协议 ⇒ {@link SQL_FACTS_ABSENT_WALLS}(两堵都 `assumed`;
+ *    fail-closed:按最保守的墙,不是「没有墙」)。池拒绝初始化本身已在 {@link establishSession} 里响亮报过。
+ * 「没有 SQL 后端」与「事实还没建立」是两个可区分的值:前者是读口缺席,后者是 `facts === null`。
+ */
+export declare function sqlWallsOf(engine: SqlEngineReading | undefined): SqlWallsReading;
 /**
  * **数据库自己的钟**(毫秒),两方言各一句 —— 本仓这口钟在 SQL 面的**唯一**铸点([ref] A7 / [ref] /
  * 合并复审 R2 把 S-280 的 nonce 店并进来)。
@@ -189,7 +351,10 @@ export declare function sqlDbNowMs(db: Pick<SqlDriver, "dialect" | "query">, sub
 export interface SqlDriver extends SqlExec {
     readonly dialect: SqlDialect;
     /**
-     * 本池上**最近一次连接初始化的结果**(状态按池存,所以共享一条池的二十多只店 driver 报同一份事实)。
+     * 本池上**最近一次连接初始化的结果**(状态按池存,所以共享一条池的二十多只店 driver 报同一份事实)—— 运维读面的料。
+     * 连接级的事实(包墙 `maxPacketBytes`:会话值,随连接不同)在这里是「最近一次初始化的那条连接的读数」—— 池见过的最新读数,只在有连接初始化时才更新(DBA 调了全局值、
+     * 还没有连接重新初始化时它仍是旧值):
+     * 提交受理口拿它跑同一只规则的**提前一跑**(手里没有将要写入的连接);终判读的是**将要执行那条语句的连接**的事实({@link sqlConnectionFacts})。
      * 三种读数,含义各不相同:
      *  · `null`(还没借出过连接)—— 没有可报的东西,**不猜**;
      *  · 事实 —— 最近一次初始化**回读复核**过的值。每条池连接首次借出都重跑一次初始化(记忆化按连接身份),
@@ -201,6 +366,45 @@ export interface SqlDriver extends SqlExec {
     readonly facts: SqlEngineFacts | null;
     connect(): Promise<SqlTxConn>;
 }
+/**
+ * 一条**借出的**连接自己的引擎事实 —— 它的初始化回读到的那一份(包墙 `maxPacketBytes` 是这条连接的会话值)。判一条语句装不装得下的地方
+ * 只读这里:借出连接 → 读它的墙 → 判 → 在同一条连接上执行(`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`)。
+ * 只认本模块的 `mysqlDriver` / `pgDriver` 的 `connect()` 借出的连接;别的连接(测试替身、包装体)没有经过初始化,墙没人读过 ⇒ **响亮抛**,不猜一个数。
+ */
+export declare function sqlConnectionFacts(conn: SqlTxConn): SqlEngineFacts;
+/** 旧连接被换掉时的运维日志事件名。 */
+export declare const STALE_PACKET_WALL_EVENT = "sql_connection_packet_wall_stale";
+/**
+ * 判官的**唯一借出口**:借出将要执行写入的那条连接,按它自己的事实判(`judge` 交回 `undefined` = 装得下,否则交回拒绝)。装得下 ⇒ 交回这条连接
+ * (调用方在它上面写、负责 `release()`)。拒绝 ⇒ 这条连接已归还,交回拒绝。
+ *
+ * **旧连接首次撞墙即自换**:包墙是会话值,连接建立时从全局拷一份、此后不变 —— DBA 调大包墙之后,池里已有的连接仍带旧值,而本仓的 MySQL 协议池
+ * 不按空闲回收连接(`tidb-pool.ts` `maxIdle` = 连接上限)。所以一次拒绝若由这条连接的**包墙**定(`byPacketWall(拒绝)`),先在**同一条连接**上读一次
+ * `@@global.max_allowed_packet`:
+ *  · 全局值大于这条连接的读数 ⇒ 它是调墙之前建立的旧连接,这一拒不是判决:**销毁**它(池补新连接)、记一行 {@link STALE_PACKET_WALL_EVENT}(连接标识 / 旧值 / 新值),
+ *    再借一条**不过时**的连接**重判一次**;仍拒 ⇒ 交回拒绝。重借时,读全局值之前就已初始化、包墙又小于那个全局值的连接同样销毁记一行(不再问库)——
+ *    池里这样的旧连接是有限的(都在读全局值之前建立),一条条换完,下一条就是之后才初始化的连接,它带的是那之后的全局值,直接在它上面判(没有固定的跳过上限);
+ *  · 全局值不大于(或读不出 —— 证明不了过时,拒是关闭方向)⇒ 这一拒就是判决。读不出分两种:变量不认识 / 不是正整数是库的答案,不记;
+ *    **查询本身失败**是故障,记一行 {@link GLOBAL_PACKET_WALL_UNREAD_EVENT}(连接标识 / 这条连接的墙 / 错误类)再按拒收 —— 方向不变,只是原因不再蒸发。
+ * 只在拒的那一刻多一次往返,装得下的写零额外语句;读与判在同一条连接上。运维日志写不出(logger 抛)不改判决、不漏连接:先销毁、再记,
+ * 记的失败交给 {@link recordFailOpen}(`server.sql.packet-wall-log-unwritten`,计数 + 契约行 + 探针,不依赖那只坏掉的 logger)。
+ */
+export declare function connectJudged<R>(db: SqlDriver, judge: (facts: SqlEngineFacts) => R | undefined, byPacketWall: (refusal: R) => boolean, log: Pick<Logger, "warn">): Promise<{
+    readonly conn: SqlTxConn;
+    readonly refusal?: undefined;
+} | {
+    readonly conn?: undefined;
+    readonly refusal: R;
+}>;
+/**
+ * 守卫租约的**池**:交出去的每一条连接 —— 池上裸语句(`pool.query`)和直接 `pool.getConnection()` 的店 —— 都是 {@link leaseOf} 的守卫租约。
+ * mysql2 的 `pool.query` 在内部借连接、跑、归还,本仓够不着那条连接,所以库关掉的连接(上面的 1153 一类)只能照常回池;这里换成**每条语句租一条连接**
+ * (`getConnection` → 守卫租约上执行 → 归还,被守卫销毁的不归还)。语句契约不变:参数原样到连接,结果是 mysql2 的 `[rows, fields]` 元组,`{ sql, timeout }` 对象形
+ * 一并支持(原样交给连接);池的其余成员(`end` / `execute` / `on` …)原样转给底池,返回底池自身的方法(`on` 之类)返回本包装体 —— 链式调用不会逃出守卫。
+ * 生产池(`createTidbPool`)恒是它;mysql2 自己的 `pool.query` 对只读类错误(1290 / 1792 / 1836)的销毁收在同一张表里({@link isConnectionUnusableError}),不丢。
+ * 不覆盖 `pool.execute`(预备语句:今天只有任务附件店一处,语句是小定长行,碰不到语句墙)。
+ */
+export declare function createCloseAwarePool(pool: MySqlPool): MySqlPool;
 /** MySQL-protocol driver (TiDB / MySQL / MariaDB — `dialect` is the SQL TEXT axis, `facts.engine` the
  *  runtime one). Transaction control uses mysql2's NATIVE methods — the historical call shape the
  *  fake-pool unit suites script around. */

package/dist/plugins/sql-driver.js

@@ -1,4 +1,61 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { errorKindOf } from "../observability/err-text.js";
+import { isConnectionUnusableError } from "./sql-errors.js";
+export const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6_291_456;
+export const ROW_WALL_ALLOWANCE_BYTES = { json: 64 * 1024, blob: 1024 };
+export const STATEMENT_ALLOWANCE_BYTES = 1024;
+export function rowWallPayloadBytes(maxRowBytes, row) {
+    return Math.max(0, maxRowBytes - ROW_WALL_ALLOWANCE_BYTES[row]);
+}
+export function packetWallStatementBytes(maxPacketBytes) {
+    return Math.max(0, maxPacketBytes - STATEMENT_ALLOWANCE_BYTES);
+}
+export function escapedStatementBytes(text) {
+    let escaped = 0;
+    for (let i = 0; i < text.length; i++) {
+        switch (text.charCodeAt(i)) {
+            case 0:
+            case 8:
+            case 9:
+            case 10:
+            case 13:
+            case 26:
+            case 34:
+            case 39:
+            case 92:
+                escaped++;
+        }
+    }
+    return Buffer.byteLength(text, "utf8") + escaped;
+}
+export const PACKET_CAP_UNREAD_LANDING_BYTES = {
+    tidb: 67_108_864,
+    innodb: 16_777_216,
+};
+const NO_WALLS = Object.freeze({ maxRowBytes: null, maxPacketBytes: null, sources: Object.freeze({ maxRowBytes: "reported", maxPacketBytes: "reported" }) });
+export const SQL_FACTS_ABSENT_WALLS = Object.freeze({
+    maxRowBytes: TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT,
+    maxPacketBytes: Math.min(...Object.values(PACKET_CAP_UNREAD_LANDING_BYTES)),
+    sources: Object.freeze({ maxRowBytes: "assumed", maxPacketBytes: "assumed" }),
+});
+export function sqlWallsOf(engine) {
+    if (engine === undefined)
+        return NO_WALLS;
+    const facts = engine.facts;
+    if (facts !== null)
+        return { maxRowBytes: facts.maxRowBytes, maxPacketBytes: facts.maxPacketBytes, sources: facts.wallSources };
+    switch (engine.dialect) {
+        case "pg":
+            return NO_WALLS;
+        case "tidb":
+            return SQL_FACTS_ABSENT_WALLS;
+        default: {
+            const unhandled = engine.dialect;
+            throw new Error(`sql walls: unknown dialect ${String(unhandled)}`);
+        }
+    }
+}
 export const SQL_DB_NOW_MS = {
     tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
     pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
@@ -29,9 +86,92 @@ const POOL_SESSIONS = new WeakMap();
 function poolSession(pool) {
     let st = POOL_SESSIONS.get(pool);
     if (st === undefined)
-        POOL_SESSIONS.set(pool, (st = { initialized: new WeakSet(), facts: null }));
+        POOL_SESSIONS.set(pool, (st = { connections: new WeakMap(), facts: null }));
     return st;
 }
+const LENT = new WeakMap();
+export function sqlConnectionFacts(conn) {
+    return lentRecord(conn).facts;
+}
+function lentRecord(conn) {
+    const lent = LENT.get(conn);
+    if (lent === undefined) {
+        throw new Error("sql-driver: this connection was not lent by mysqlDriver()/pgDriver().connect(), so no connection initialization read its walls — " +
+            "borrow the connection a statement will run on from the driver before judging that statement's size");
+    }
+    return lent;
+}
+let INIT_ORDINAL = 0;
+export const STALE_PACKET_WALL_EVENT = "sql_connection_packet_wall_stale";
+const GLOBAL_PACKET_WALL_UNREAD_EVENT = "sql_connection_packet_wall_global_unread";
+export async function connectJudged(db, judge, byPacketWall, log) {
+    let conn = await db.connect();
+    try {
+        let refusal = judge(sqlConnectionFacts(conn));
+        if (refusal === undefined)
+            return { conn };
+        if (byPacketWall(refusal)) {
+            const lent = lentRecord(conn);
+            const wall = lent.facts.maxPacketBytes;
+            const global = wall === null ? null : await readGlobalPacketWallLogged(lent, log);
+            if (wall !== null && global !== null && global > wall) {
+                const initializedBefore = INIT_ORDINAL;
+                retireStale(lent, global, log);
+                conn = await borrowNotStale(db, global, initializedBefore, log);
+                refusal = judge(sqlConnectionFacts(conn));
+                if (refusal === undefined)
+                    return { conn };
+            }
+        }
+        conn.release();
+        return { refusal };
+    }
+    catch (err) {
+        conn.release();
+        throw err;
+    }
+}
+function retireStale(lent, globalWallBytes, log) {
+    lent.destroy();
+    warnPacketWall(log, STALE_PACKET_WALL_EVENT, { connection: lent.id, sessionWallBytes: lent.facts.maxPacketBytes, globalWallBytes });
+}
+async function readGlobalPacketWallLogged(lent, log) {
+    try {
+        return await lent.readGlobalPacketWall();
+    }
+    catch (err) {
+        warnPacketWall(log, GLOBAL_PACKET_WALL_UNREAD_EVENT, { connection: lent.id, sessionWallBytes: lent.facts.maxPacketBytes, errKind: errorKindOf(err) });
+        return null;
+    }
+}
+function warnPacketWall(log, event, fields) {
+    try {
+        log.warn(event, fields);
+    }
+    catch (err) {
+        recordFailOpen("server.sql.packet-wall-log-unwritten", `event=${event} err=${errorKindOf(err)}`);
+    }
+}
+async function borrowNotStale(db, globalWallBytes, initializedBefore, log) {
+    for (;;) {
+        const conn = await db.connect();
+        let lent;
+        try {
+            lent = lentRecord(conn);
+        }
+        catch (err) {
+            conn.release();
+            throw err;
+        }
+        const wall = lent.facts.maxPacketBytes;
+        if (wall === null || wall >= globalWallBytes || lent.initOrdinal > initializedBefore)
+            return conn;
+        retireStale(lent, globalWallBytes, log);
+    }
+}
+async function readGlobalMaxAllowedPacket(c) {
+    return positiveIntOf(await mysqlVar(c, "SELECT @@global.max_allowed_packet AS v")) ?? null;
+}
 async function mysqlVar(c, sql) {
     try {
         const r = await mysqlQuery(c, sql);
@@ -50,16 +190,20 @@ function refuseSession(what) {
         `Neither is optional: every "SELECT … FOR UPDATE" decision point in this service is a CURRENT read only under them.`);
 }
 async function establishSession(session, pooled, c, init) {
-    if (session.initialized.has(pooled))
-        return;
+    const known = session.connections.get(pooled);
+    if (known !== undefined)
+        return known;
     try {
-        session.facts = await init(c);
-        session.initialized.add(pooled);
+        const facts = await init(c);
+        const initialized = { facts, initOrdinal: ++INIT_ORDINAL };
+        session.facts = facts;
+        session.connections.set(pooled, initialized);
+        return initialized;
     }
     catch (err) {
         const stale = session.facts;
         session.facts = null;
-        session.initialized = new WeakSet();
+        session.connections = new WeakMap();
         if (stale !== null)
             console.warn(`[sql-driver] connection initialization REFUSED — SQL engine facts invalidated (was: ${stale ? `${stale.engine} ${stale.version} ${stale.isolation} txnMode=${stale.txnMode ?? "-"}` : "<absent>"}). GET /v1/diagnostics/wiring -> sqlEngine and GET /v1/capabilities -> sql now report ABSENT, which is the honest ` +
                 `reading: this pool cannot currently establish the read semantics every "SELECT … FOR UPDATE" in this repo assumes. Cause: ${err.message}`);
@@ -90,7 +234,143 @@ async function initMySqlSession(c) {
     if (isolation !== "REPEATABLE-READ") {
         throw refuseSession(`this session reports isolation "${isolation}" after SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ`);
     }
-    return { engine, version: (await mysqlVar(c, "SELECT VERSION() AS v")) ?? "", isolation, txnMode: engine === "tidb" ? "pessimistic" : null };
+    const version = (await mysqlVar(c, "SELECT VERSION() AS v")) ?? "";
+    const rowWall = engine === "tidb" ? await readTidbEntrySizeLimit(c) : null;
+    const packetWall = await readMaxAllowedPacket(c, engine);
+    return {
+        engine,
+        version,
+        isolation,
+        txnMode: engine === "tidb" ? "pessimistic" : null,
+        maxRowBytes: rowWall === null ? null : rowWall.bytes,
+        maxPacketBytes: packetWall.bytes,
+        wallSources: { maxRowBytes: rowWall === null ? "reported" : rowWall.source, maxPacketBytes: packetWall.source },
+    };
+}
+function positiveIntOf(v) {
+    const n = typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v.trim()) : Number.NaN;
+    return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+async function readTidbEntrySizeLimit(c) {
+    const unread = [];
+    try {
+        const v = await mysqlVar(c, "SELECT @@tidb_txn_entry_size_limit AS v");
+        const n = positiveIntOf(v);
+        if (n !== undefined)
+            return { bytes: n, source: "reported" };
+        unread.push(v === null ? "@@tidb_txn_entry_size_limit is unknown (TiDB before 7.6)" : `@@tidb_txn_entry_size_limit=${JSON.stringify(v)} (0 = use the config item)`);
+    }
+    catch (err) {
+        unread.push(`@@tidb_txn_entry_size_limit: ${err.message}`);
+    }
+    try {
+        const r = await mysqlQuery(c, "SHOW CONFIG WHERE type = 'tidb' AND name = 'performance.txn-entry-size-limit'");
+        const values = r.rows.map((row) => positiveIntOf(row.Value ?? row.value)).filter((n) => n !== undefined);
+        if (values.length > 0)
+            return { bytes: Math.min(...values), source: "reported" };
+        unread.push(`SHOW CONFIG returned no readable performance.txn-entry-size-limit (${r.rows.length} row(s))`);
+    }
+    catch (err) {
+        unread.push(`SHOW CONFIG: ${err.message}`);
+    }
+    recordFailOpen("server.sql.tidb-row-cap-unread", `assumed=${TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT} ${unread.join("; ")}`);
+    return { bytes: TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT, source: "assumed" };
+}
+async function readMaxAllowedPacket(c, engine) {
+    const landing = PACKET_CAP_UNREAD_LANDING_BYTES[engine];
+    let unread;
+    try {
+        const v = await mysqlVar(c, "SELECT @@max_allowed_packet AS v");
+        const n = positiveIntOf(v);
+        if (n !== undefined)
+            return { bytes: n, source: "reported" };
+        unread = v === null ? "@@max_allowed_packet is unknown" : `@@max_allowed_packet=${JSON.stringify(v)} (not a positive integer)`;
+    }
+    catch (err) {
+        unread = `@@max_allowed_packet: ${err.message}`;
+    }
+    recordFailOpen("server.sql.packet-cap-unread", `assumed=${landing} engine=${engine} ${unread}`);
+    return { bytes: landing, source: "assumed" };
+}
+const LEASE_STATEMENT_METHODS = new Set(["query", "execute", "beginTransaction", "commit", "rollback"]);
+const GUARDED_LEASES = new WeakSet();
+const BROKEN_LEASES = new WeakMap();
+function leaseOf(raw) {
+    if (GUARDED_LEASES.has(raw))
+        return raw;
+    let destroyed = false;
+    const destroy = () => {
+        if (destroyed)
+            return;
+        destroyed = true;
+        raw.destroy();
+    };
+    let turn = Promise.resolve();
+    const guard = (run) => {
+        const result = turn.then(async () => {
+            try {
+                return await run();
+            }
+            catch (err) {
+                if (isConnectionUnusableError(err)) {
+                    destroy();
+                    BROKEN_LEASES.set(lease, { error: err });
+                }
+                throw err;
+            }
+        });
+        turn = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const lease = new Proxy(raw, {
+        get(target, prop) {
+            const member = Reflect.get(target, prop, target);
+            if (typeof member !== "function")
+                return member;
+            if (prop === "release")
+                return () => (destroyed ? undefined : raw.release());
+            if (prop === "destroy")
+                return destroy;
+            if (prop === "rollback")
+                return (...args) => guard(async () => (destroyed ? undefined : member.apply(target, args)));
+            if (LEASE_STATEMENT_METHODS.has(prop))
+                return (...args) => guard(() => member.apply(target, args));
+            return (...args) => {
+                const result = member.apply(target, args);
+                return result === target ? lease : result;
+            };
+        },
+    });
+    GUARDED_LEASES.add(lease);
+    return lease;
+}
+export function createCloseAwarePool(pool) {
+    const lend = async () => leaseOf(await pool.getConnection());
+    const query = async (...args) => {
+        const c = await lend();
+        try {
+            return await c.query(...args);
+        }
+        finally {
+            c.release();
+        }
+    };
+    const wrapper = new Proxy(pool, {
+        get(target, prop) {
+            if (prop === "query")
+                return query;
+            if (prop === "getConnection")
+                return lend;
+            const member = Reflect.get(target, prop, target);
+            if (typeof member !== "function")
+                return member;
+            return (...args) => {
+                const result = member.apply(target, args);
+                return result === target ? wrapper : result;
+            };
+        },
+    });
+    return wrapper;
 }
 export function mysqlDriver(pool) {
     const session = poolSession(pool);
@@ -101,15 +381,28 @@ export function mysqlDriver(pool) {
         },
         query: (sql, params) => mysqlQuery(pool, sql, params),
         async connect() {
-            const c = await pool.getConnection();
-            await establishSession(session, c.connection ?? c, c, initMySqlSession);
-            return {
+            const raw = await pool.getConnection();
+            const c = leaseOf(raw);
+            const { facts, initOrdinal } = await establishSession(session, raw.connection ?? raw, c, initMySqlSession);
+            const broken = BROKEN_LEASES.get(c);
+            if (broken !== undefined)
+                throw broken.error;
+            const conn = {
                 query: (sql, params) => mysqlQuery(c, sql, params),
                 begin: () => c.beginTransaction(),
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
                 release: () => c.release(),
             };
+            const threadId = c.threadId;
+            LENT.set(conn, {
+                facts,
+                initOrdinal,
+                id: typeof threadId === "number" ? threadId : null,
+                destroy: () => c.destroy(),
+                readGlobalPacketWall: () => readGlobalMaxAllowedPacket(c),
+            });
+            return conn;
         },
     };
 }
@@ -130,6 +423,9 @@ async function initPgSession(c) {
         version: String(ver.rows[0]?.server_version ?? ""),
         isolation,
         txnMode: null,
+        maxRowBytes: null,
+        maxPacketBytes: null,
+        wallSources: { maxRowBytes: "reported", maxPacketBytes: "reported" },
     };
 }
 export function pgDriver(pool) {
@@ -142,8 +438,9 @@ export function pgDriver(pool) {
         query: (sql, params) => pgQuery(pool, sql, params),
         async connect() {
             const c = await pool.connect();
-            await establishSession(session, c, c, initPgSession);
-            return {
+            const { facts, initOrdinal } = await establishSession(session, c, c, initPgSession);
+            let destroyed = false;
+            const conn = {
                 query: (sql, params) => pgQuery(c, sql, params),
                 begin: async () => {
                     await c.query("BEGIN");
@@ -154,8 +451,23 @@ export function pgDriver(pool) {
                 rollback: async () => {
                     await c.query("ROLLBACK");
                 },
-                release: () => c.release(),
+                release: () => {
+                    if (!destroyed)
+                        c.release();
+                },
             };
+            const pid = c.processID;
+            LENT.set(conn, {
+                facts,
+                initOrdinal,
+                id: typeof pid === "number" ? pid : null,
+                destroy: () => {
+                    destroyed = true;
+                    c.release(true);
+                },
+                readGlobalPacketWall: async () => null,
+            });
+            return conn;
         },
     };
 }