@sema-agent/server 7.132.0 → 7.133.0

package/dist/plugins/session-store.d.ts

@@ -1,6 +1,8 @@
 import { type SessionStore } from "@sema-agent/core";
 import type { ServiceConfig } from "../config-types.js";
 import type { StoreBackend } from "./store-backend.js";
+import { type DelegationRootWitness, type DelegationTree, type OrphanOwnerLog } from "../delegated-session-owner.js";
+import type { OwnerAwareSessionStore } from "../security.js";
 /**
  * Session-store plugin seam.
  *
@@ -43,15 +45,23 @@ export declare function ensureSessionDurable(hostStore: SessionStore, sessionId:
  * [ref] 主动晋升版 ensureChildSessionDurable(cli TiDB 真机撞获:1.263 的只查不迁形在拆店生产形下
  * 恒否决 park——bg 子会话住 subRunner 私有 TTL 店、从不在 host 店,core 收 veto 即 expire checkpoint
  * (14ms~2s)+ settle failed,赎回窗口不存在):
- *   1. 快路:已在 host 店且有真内容 → 直接通过(幂等/重入)。
+ *   0. 属主(S-1770,`delegated-session-owner.ts`):按委派继承律判一次(唯一判据 `judgeDelegatedOwner`)—— 来源集 = 见证的根这一只(调用方交出的委派树根 + 调用方判断那一刻
+ *      读到的根行住客:请求腿 = 本请求经鉴权解析的会话与受理时那一读,`/decide` 赎回腿 = 行上的 `rootSessionId` 与 claim 前后两读的那一位;core 的挂点签名只给子代 id,
+ *      场景层把见证绑进闭包交下来)。此刻根行在而住客不是见证的那一位(删了、同 id 被重新登记)⇒ **拒**(`assertRootStillWitnessed`:不按新住客晋升 / 认领);
+ *      缺席(行上没有根)或根行此刻不在 ⇒ 孤行哨兵。
+ *   1. 快路:已在 host 店且有真内容 → 通过,**前提是那一行的属主按律定得下来**(`settleDelegatedOwner`:记着别的委派树 ⇒ 抛;记着这一棵 ⇒ 按它记录的根、父再判一次
+ *      (与 M23 同读数),无主 ⇒ 认领(CAS 子行,写判断时的读数)、没落下 ⇒ 抛(只有记录委派树的 SQL 店;local 店的行不记委派树 ⇒ 不认领);此刻属主不是律给的那一只 ⇒ 那是别人的同 id 会话,
+ *      不是这只子代的转录 ⇒ 抛 = 停驻否决;与晋升建行前那一道同一只函数)。
  *   2. 晋升:routing.promoteToHost 把子会话整树从私店拷进 host 店(拷贝→私店 forget→路由记 host,
- *      三步见 ForkRoutingSessionStore.promoteToHost)。
- *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)——晋升产物必须达到与既有校验完全相同的
- *      durable 标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ *      三步见 ForkRoutingSessionStore.promoteToHost),宿主行在建行那一笔里带第 0 步的属主;写的是哨兵 ⇒ 写落下之后一行 warn。
+ *   3. 复验:同一把 `ensureSessionDurable` 严检(leaf 非空)+ 同一只属主定夺 —— 晋升产物必须达到与快路完全相同的
+ *      标准,任何一步失败=如实 reject=veto=pre-153 行为(不放大)。
+ * 宿主店必须读得出属主(`delegatedOwnerHostOf`:`ownerOf` + `sessionFaceOf`;记录委派树的店另交 `placementOf` + `claimOwnerless`,两只同在或同缺;生产的 SQL / local 店与缓存包装层都满足),
+ * 否则响亮拒。
  * 调用方纪律与 {@link ensureSessionDurable} 同款:hostStore 必须是 release 非破坏性的真 durable 店
- * (main.ts 的 `config.sessionBackend === "tidb"` 门不变)。
+ * (stage-07 的 `config.sessionBackend === "tidb"` 门不变 —— 该词在 local 后端上同样归一成 `tidb`,所以本腿在 local 宿主店上也跑)。
  */
-export declare function ensureChildSessionDurableWithPromotion(hostStore: SessionStore, routing: {
-    promoteToHost(sessionId: string): Promise<void>;
-}, sessionId: string): Promise<void>;
+export declare function ensureChildSessionDurableWithPromotion(hostStore: OwnerAwareSessionStore, routing: {
+    promoteToHost(sessionId: string, owner: string | null, tree: DelegationTree): Promise<void>;
+}, sessionId: string, root: DelegationRootWitness | undefined, log: OrphanOwnerLog): Promise<void>;
 //# sourceMappingURL=session-store.d.ts.map

package/dist/plugins/session-store.js

@@ -1,5 +1,6 @@
 import { TtlSessionStore } from "@sema-agent/core";
 import { CachingSessionStore } from "./caching-session-store.js";
+import { assertRootStillWitnessed, delegatedOwnerHostOf, readDelegatedOwner, reportWrittenOwner, settleDelegatedOwner, sourceFacesVia, } from "../delegated-session-owner.js";
 export function createSessionStore(config, backend, metrics) {
     if (config.sessionBackend === "tidb") {
         if (!backend)
@@ -22,14 +23,24 @@ export async function ensureSessionDurable(hostStore, sessionId) {
         await hostStore.forget?.(acquired.sessionId);
     }
 }
-export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId) {
+export async function ensureChildSessionDurableWithPromotion(hostStore, routing, sessionId, root, log) {
+    const host = delegatedOwnerHostOf(hostStore);
+    if (host === undefined) {
+        throw new Error(`session "${sessionId}" cannot be parked: the host session store cannot read a session's owner (ownerOf / sessionFaceOf), or records delegation trees without being able to claim under them (placementOf / claimOwnerless), so the delegated transcript's owner cannot be derived or checked`);
+    }
+    const judged = await readDelegatedOwner(sessionId, root === undefined ? {} : { rootSessionId: root.sessionId }, sourceFacesVia(host.sessionFaceOf));
+    assertRootStillWitnessed(sessionId, root, judged);
+    let promoted = false;
     try {
         await ensureSessionDurable(hostStore, sessionId);
-        return;
     }
     catch {
+        await routing.promoteToHost(sessionId, judged.inherited.owner, judged.tree);
+        await ensureSessionDurable(hostStore, sessionId);
+        promoted = true;
     }
-    await routing.promoteToHost(sessionId);
-    await ensureSessionDurable(hostStore, sessionId);
+    const settled = await settleDelegatedOwner(host, sessionId, judged.inherited.owner, judged.tree);
+    if (promoted || settled.claimed)
+        reportWrittenOwner(log, "promotion", sessionId, settled.judged ?? judged);
 }
 //# sourceMappingURL=session-store.js.map

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. */
@@ -175,20 +176,35 @@ export interface SqlEngineFacts {
      *    `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, in bytes — the session's `@@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").
+     * 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 readers: the submit admission (`http/request-guards.ts` `refuseSubmitBody`) and the SQL snapshot-blob default cap
-     * (`plugins/blob-backend.ts` `sqlBlobDefaultCapBytes`) — both through {@link packetWallStatementBytes}, and both 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.
+     * 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;
     /**
@@ -229,19 +245,24 @@ 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} 被两个读者共读。
+ * 不扣的话恰在包墙上的载荷整条语句会超出包墙几百字节:放行、库在写那一刻拒。经 {@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})`。受理口的提交体门限(量的是转义后的语句字节,{@link escapedStatementBytes})与 blob 缺省帽的包墙腿(再按膨胀律折半)读它。 */
+/**
+ * 包墙下一条语句里的载荷最多多少字节:`max(0, 包墙 − {@link STATEMENT_ALLOWANCE_BYTES})` —— 包墙这一只规则的**唯一**算式,两个读者:
+ *  · blob 缺省帽的包墙腿(再按膨胀律折半),包墙取自将要执行写入的那条连接 —— **终判**;
+ *  · 提交体受理口(量的是转义后的语句字节,{@link escapedStatementBytes}),包墙取自池里最近初始化的那条连接 —— 同一只规则的**提前一跑**
+ *    (受理时手里没有将要写入的连接;拒 ⇒ 413 在任何副作用之前,收 ⇒ 写入那条连接上的库仍是终判)。
+ */
 export declare function packetWallStatementBytes(maxPacketBytes: number): number;
 /**
  * 一段文本作为**一只字符串字面**进 MySQL 协议语句时占的字节数(不含外层两只引号)—— 店真正发出去的字节,不是文本自己的字节数。
- * 店用 `pool.query(sql, [text])`,mysql2 在客户端把参数格式化进语句(`sql-escaper` 的 `escapeString`):`\0 \b \t \n \r \x1a " ' \` 九个字符各变成两个字符
+ * 店用 `query(sql, [text])`,mysql2 在客户端把参数格式化进语句(`sql-escaper` 的 `escapeString`):`\0 \b \t \n \r \x1a " ' \` 九个字符各变成两个字符
  * (多一个反斜杠字节),其余字符原样 —— 多字节 UTF-8 不受影响。所以一份 JSON 里引号 / 反斜杠越多,语句越比文本长(上界 2×:每个字符至多多一字节)。
  *
- * 受理口的包墙腿量它(`http/request-guards.ts` `refuseSubmitBody`):门承诺「写不进去的体在任何副作用之前 413」,量的就必须是语句字节。
+ * 受理口的包墙腿量它(`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 的字符串。
  */
@@ -291,7 +312,7 @@ export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
 export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
 /**
  * 🔴 **此刻一份写入要装进的墙 —— 唯一判官**。两个读者同调它、不各读 `facts`:提交受理口(`http/request-guards.ts` `refuseSubmitBody`)与 SQL 快照 blob 的缺省帽
- * (`plugins/blob-backend.ts` `sqlBlobCapBytes`,店的写前帽与 `PUT /sync/blobs` 的前置 413 都经它)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出一只驱动),一种读法:
+ * (`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`;
@@ -330,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`(还没借出过连接)—— 没有可报的东西,**不猜**;
      *  · 事实 —— 最近一次初始化**回读复核**过的值。每条池连接首次借出都重跑一次初始化(记忆化按连接身份),
@@ -342,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,5 +1,7 @@
 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;
@@ -84,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);
@@ -105,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}`);
@@ -203,6 +292,86 @@ async function readMaxAllowedPacket(c, engine) {
     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);
     return {
@@ -212,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;
         },
     };
 }
@@ -256,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");
@@ -268,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;
         },
     };
 }

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

@@ -118,6 +118,29 @@ export type RowTooLargeWall = "row" | "statement" | "value";
  * MySQL 协议两条墙都认 —— 两条墙对**一条单行 INSERT** 说的是同一件事(这一行写不进),出路不同;PG 认 `54000`。认不出的一律 `undefined`(原始错误原样上抛)。
  */
 export declare function rowTooLargeWallOf(dialect: SqlDialect, err: unknown): RowTooLargeWall | undefined;
+/**
+ * **这条连接不许再回池**的 MySQL 协议错误 —— 闭集,逐码登记「为什么」。两类原因:
+ *  · **库发完这个错误包之后自己关掉这条连接**(或随后必关):客户端的池只看见「这条语句完了」,连接照常归还,库的 FIN / RST 晚一拍才到 ——
+ *    池上紧接着的下一笔借到这条半死的连接,答 `write ECONNRESET`。1153 是真库读数(k3s8 TiDB v7.5.1:超墙的续跑输入写,首笔答 1153 + 带库原句,
+ *    同池下一笔 `getCtx` 答 `write ECONNRESET`);其余按各引擎的服务端行为文档登记(**未在真库上逐码复现**,收车档如实标注),错放进来的代价只是一次重连;
+ *  · **只读类**(只读模式 / 故障切换之后连接落在只读节点上):mysql2 自己的 `pool.query` 对这三个错误号同样销毁连接(`lib/base/pool.js` `isReadOnlyError`)——
+ *    本仓的池上裸语句改走租来的连接(`createCloseAwarePool`),不收进来就丢了这条既有行为;归因取 mysql2 的,不另作更窄的断言。
+ * **不在表里**的(连接仍可用,语句级错误):唯一键冲突 1062、死锁 1213、锁等待超时 1205、`KILL QUERY` 的 1317、缺表 1146、CHECK 被拒 3819,以及 **TiDB 的单行墙 8025**
+ * (`ErrEntryTooLarge`,事务层的语句错;真库读数:同池上 8025 写之后的读照常 —— `checkpoint-row-size-db-integration` ②③④)。
+ * 断连形(`ECONNRESET` / `EPIPE` / `PROTOCOL_CONNECTION_LOST`)也不在表里:那是 mysql2 的**致命错误**,连接对象自己已经 `_removeFromPool`。
+ * PostgreSQL 没有对应面:node-pg 的 `pool.query` 对任何错误都丢弃那条 client。
+ * 新增一行 = 改表 + 在 `test/db-closed-connection-never-pooled.test.ts` 的码表里加一格。
+ */
+export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
+    readonly errno: number;
+    readonly code: string;
+}>;
+/**
+ * 「抛出这个错误的那条连接还能不能回池」的单一判据:{@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 里的错 ⇒ **不能** —— 持连接的一方(`sql-driver.ts` 的 `leaseOf`)
+ * 先销毁它、再让错误出去。两个归因键任一在场即认(同本文件其余谓词的姿势:`errno` 与 `code` 是同一件事的两种写法,代理 / 序列化往返可能只留一个)。
+ * 认不出的一律不是(连接照常归还;断连形由 mysql2 自己清出池)。只管 MySQL 协议的错误形:PG 的错误没有这两个键,恒 false。
+ */
+export declare function isConnectionUnusableError(err: unknown): boolean;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -61,6 +61,27 @@ export function rowTooLargeWallOf(dialect, err) {
         return "statement";
     return undefined;
 }
+export const MYSQL_CONNECTION_UNUSABLE_ERRORS = [
+    { errno: 1053, code: "ER_SERVER_SHUTDOWN" },
+    { errno: 1152, code: "ER_ABORTING_CONNECTION" },
+    { errno: 1153, code: "ER_NET_PACKET_TOO_LARGE" },
+    { errno: 1158, code: "ER_NET_READ_ERROR" },
+    { errno: 1159, code: "ER_NET_READ_INTERRUPTED" },
+    { errno: 1160, code: "ER_NET_ERROR_ON_WRITE" },
+    { errno: 1161, code: "ER_NET_WRITE_INTERRUPTED" },
+    { errno: 1927, code: "ER_CONNECTION_KILLED" },
+    { errno: 4031, code: "ER_CLIENT_INTERACTION_TIMEOUT" },
+    { errno: 1290, code: "ER_OPTION_PREVENTS_STATEMENT" },
+    { errno: 1792, code: "ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION" },
+    { errno: 1836, code: "ER_READ_ONLY_MODE" },
+];
+const UNUSABLE_ERRNOS = new Set(MYSQL_CONNECTION_UNUSABLE_ERRORS.map((e) => e.errno));
+const UNUSABLE_CODES = new Set(MYSQL_CONNECTION_UNUSABLE_ERRORS.map((e) => e.code));
+export function isConnectionUnusableError(err) {
+    const errno = keyOf(err, "errno");
+    const code = keyOf(err, "code");
+    return (typeof errno === "number" && UNUSABLE_ERRNOS.has(errno)) || (typeof code === "string" && UNUSABLE_CODES.has(code));
+}
 export class StoreRowTooLargeError extends Error {
     row;
     wall;