@sema-agent/server 7.132.0 → 7.134.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. */
@@ -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;

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

@@ -10,6 +10,7 @@ import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
 import { type ApprovalNonceStore } from "./approval-nonce-store.js";
+import { type OrgDeliveryQuotaStore } from "./org-delivery-quota-store.js";
 import { type ApprovalAskStore as ApprovalAskStoreType } from "./approval-ask-store-sql.js";
 import { type MemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js";
 import { type SendFileLedger } from "./send-file-ledger.js";
@@ -59,6 +60,19 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  *  whole-tree `ServiceFileSnapshotStore` ([ref]: the boundary covers the TRACKED set only — files this
  *  session edited; there is no whole-tree manifest anymore). Also the 2c history-transfer store
  *  (exportHistory/importHistory + the blob negotiation faces below). */
+/**
+ * The 2c `putBlob` answer: core's `FileHistoryResult` plus ONE arm — the SQL blob judge refused the blob on the connection that
+ * would have written it ({@link import("./blob-backend.js").BlobTooLargeError}, code `blob_too_large_for_sql`). `PUT /sync/blobs`
+ * answers that arm 413 (the store's sentence, plus the machine-readable `wallSource` = where the cap came from) and every other failure 502 (retryable).
+ */
+export type SyncBlobPutResult = import("@sema-agent/core").FileHistoryResult | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: import("./blob-backend.js").BlobTooLargeError["code"];
+        readonly message: string;
+        readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+    };
+};
 export type ServiceFileHistoryStore = FileHistoryStore & {
     /** 2c sync blob-face marker — see SqlFileHistoryStore.syncBlobFaces (codex R2-high: name-probing
      *  `putBlob` on an arbitrary store collides with the local core store's PRIVATE void helper). */
@@ -70,7 +84,7 @@ export type ServiceFileHistoryStore = FileHistoryStore & {
      *  protected — never a synchronous external-store delete). Reaper-driven; SQL twins only. */
     sweepOrphanBlobs?(): Promise<number>;
     /** 2c blob negotiation: upload one content-addressed blob ahead of importHistory. SQL twins only. */
-    putBlob?(hash: string, bytes: Uint8Array): Promise<import("@sema-agent/core").FileHistoryResult>;
+    putBlob?(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
     /** 2c blob read face (scope-checked by the route against the session's history graph). SQL twins only. */
     getBlob?(hash: string): Promise<Uint8Array | undefined>;
     /** The subset of `hashes` already present — a cheap SQL INDEX probe (the import presence pre-check,
@@ -163,6 +177,11 @@ export interface StoreBackend {
      *  `approvalExemption` 同姿势:tidb/pg = SQL 双方言(单类双语句),local = File 追加日志 + 压实。
      *  **不能**退化成进程内易失形:一次重启若把记录抹掉,JWT TTL 窗内的重放就复活了,而那正是本店要关的洞。 */
     approvalNonce(): ApprovalNonceStore;
+    /** [ref] §10.2 —— 跨主体投递门的配额店(`org-delivery-quota-store.ts`:一次 take 在同一把锁下判并记对偶界与收件人
+     *  聚合界)。REQUIRED on all backends —— tidb/pg = SQL 双方言(单类双语句,窗按库钟),local = File 整份快照(本进程墙钟;
+     *  数据根锁保证一个进程)。门装配时才取(`PRINCIPAL_INBOX_ASSISTANT` 在场);**不能**退化成进程内易失形:多副本各数各的
+     *  = 额度 × 副本数,一次重启清零 = 窗内额度复活。 */
+    orgDeliveryQuota(): OrgDeliveryQuotaStore;
     /** [ref]([ref] §3.0-§3.2)流内审批协议持久层:每个流内工具调用一行的 ask 状态机 + 批行。
      *  REQUIRED **且持久** on all backends — tidb/pg = SQL 双方言 twin;local = {@link FileApprovalAskStore}。
      *
@@ -287,6 +306,11 @@ export interface StoreBackend {
      *  缺席**是一个真答案**:那里的索引家在 run 店同一间屋子里(`LocalWorkflowAgentSessionIndex`,文件账本
      *  或纯内存),不需要经过 backend。契约与单写者纪律的属主 = orchestration/workflow-agent-session-index.ts。 */
     workflowAgentSessionIndex?(): import("../orchestration/workflow-agent-session-index.js").WorkflowAgentSessionIndex;
+    /** workflow 子代停驻卡的耐久决定行(一张卡一行,键 = 子代 checkpoint 的 token),**绑在本后端的 {@link run} 那只 run 店上**(每一笔写都在它的会话认领栅栏里落)。
+     *  与 `run()` 同形:无参、恒交同一只(三孪生同),所以这只决定店绑的就是部署的 run 店。SQL 后端 = 跨副本表,读写走 run 店的池;`local` 后端 = 进程内,
+     *  账本位置由后端按自己的数据根与 `WORKFLOW_RUN_STORE` 定(`<数据根>/workflows/workflow-park-decisions/decisions.jsonl`;`memory` ⇒ 纯内存)。
+     *  契约与律的属主 = orchestration/workflow-park-decision.ts。 */
+    workflowParkDecisions?(): import("../orchestration/workflow-park-decision.js").WorkflowParkDecisionStore;
     /** Cloud-only stores below are OPTIONAL: the `local` (in-memory/file) backend omits them (it has no core
      *  in-memory twin carrying the service extras, and these are fleet/multi-replica concepts), so a local HTTP
      *  service degrades EXACTLY like today's no-DB env (the consumers gate on `backend?.X?.()`). TiDB/PG provide all. */
@@ -301,6 +325,17 @@ export interface StoreBackend {
     checkpoint?(logger?: {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
+    /**
+     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」就走这一口,不走 {@link checkpoint}。
+     * 区别只有一条:这一口**不牵动任何别的店**。local 车道的 `checkpoint()` 是 durable 停驻面的装配点 —— 它给 run 店接上 [ref] 的收割探针(停驻行的收割从 no-op 变生效),
+     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;留存腿在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失,看不见就会把还能被决的停驻的问删掉),
+     * 所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
+     *
+     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:留存腿读不到这一口的后果在**删除方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删),
+     * 「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端(`checkpoint` 缺席)交一只恒空的读口
+     * (`{ listPendingSessionIds: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
+     */
+    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds">;
     toolResult?(): ToolResultStoreFull;
     imageIndex?(): ImageIndex;
     imageBake?(): ImageBake;