@sema-agent/server 7.134.0 → 7.136.0

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -5,6 +5,8 @@
  * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
  * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
  * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ * `WORKSPACE_SNAPSHOT_BUCKET`(缺省 `workspaces`,k8s 工作区快照桶)同病且更隐:起服不核它 ⇒ 缺桶 / 无权限时每条 run 读 `latest` 得 404,
+ * 被读成「这个空间头一回」,从空目录起;run 末的保存虽失败,报的却是一条不点名桶的 curl 404,没有一行说「桶没建」。
  *
  * ## 形(一条规则,不加特例)
  *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
@@ -13,24 +15,57 @@
  *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
  *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
  *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
- *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 核的桶是一张角色表({@link SNAPSHOT_BUCKET_ROLES},闭集两行)里的两只,**同一只探针、同一条规则、同一只兜底口**:
+ *    `session` = `config.snapshotBlobStore.bucket`(`SESSION_SNAPSHOT_BUCKET`;SendUserFile 的私桶缺省同一只);
+ *    `workspace` = k8s 车道的 `config.remoteExec.s3Snapshot.bucket`(`WORKSPACE_SNAPSHOT_BUCKET`,缺省 `workspaces`)—— 车道没开 / 没配对象存储 ⇒ 没有这只桶,不核。
+ *    拒句的旋钮名跟着桶走(缺的是哪只桶就只点哪只的旋钮)。公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 运行期的对应臂:工作区 `latest` 指针读答 404 `NoSuchBucket`(同一条「桶不在」判据 `isNoSuchBucketAnswer`)⇒ 那条 run 响亮拒绝,不再读成「空间头一回」
+ *    (`remote-env-k8s.ts` `readPointer`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
  */
 import type { ServiceConfig } from "../config-types.js";
 import { type StoreOpenWaitClock } from "./store-open-wait.js";
 type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** 被核的桶的角色(闭集):`session` = 快照 blob / SendUserFile 私桶;`workspace` = k8s 工作区快照桶。 */
+export type SnapshotBucketRole = "session" | "workspace";
+/** 两只被核的桶的角色表 —— 拒句、`snapshot_bucket_wait` 披露与 {@link ensureSnapshotBuckets} 都读这一张(缺一行 = 编译错)。 */
+export declare const SNAPSHOT_BUCKET_ROLES: {
+    readonly session: {
+        readonly noun: "snapshot bucket";
+        readonly knob: "SESSION_SNAPSHOT_BUCKET";
+        readonly defaultName: "session-snapshots";
+        readonly consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)";
+        readonly createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment";
+    };
+    readonly workspace: {
+        readonly noun: "workspace snapshot bucket";
+        readonly knob: "WORKSPACE_SNAPSHOT_BUCKET";
+        readonly defaultName: "workspaces";
+        readonly consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing";
+        readonly createHint: "";
+    };
+};
 /** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
 /** 缺桶的拒启句(唯一铸点)。 */
 /** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */
-export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number): string;
+export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number, role?: SnapshotBucketRole): string;
 /** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
 /**
- * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * boot 期核一次**一只**快照桶。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
  * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ * @param role 这只桶的角色({@link SNAPSHOT_BUCKET_ROLES}):决定拒句点名哪根旋钮;缺省 `session`。
  */
 export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
     warn(msg: string, meta?: Record<string, unknown>): void;
-}, clock?: StoreOpenWaitClock): Promise<void>;
+}, clock?: StoreOpenWaitClock, role?: SnapshotBucketRole): Promise<void>;
+/**
+ * boot 期核**这份配置要用的全部**快照桶(`boot/stores.ts`,排在打开任何店之前):角色表的每一行,配置里有这只桶才核 —— 会话快照桶 ⇐ 配了对象存储
+ * (`snapshotBlobStore`);工作区快照桶 ⇐ k8s 车道配了对象存储(`remoteExec.s3Snapshot`)。依角色表顺序逐只核,每只各有自己的 `STORE_LOCK_WAIT_MS` 窗
+ * (缺的桶才占窗;在场的桶一次探针就过),第一只缺的桶即拒启。
+ */
+export declare function ensureSnapshotBuckets(config: Pick<ServiceConfig, "snapshotBlobStore" | "remoteExec" | "storeLockWaitMs">, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}): Promise<void>;
 export {};
 //# sourceMappingURL=snapshot-bucket-presence.d.ts.map

package/dist/plugins/snapshot-bucket-presence.js

@@ -1,21 +1,39 @@
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { MinioBlobBackend } from "./blob-backend.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_ROLES = {
+    session: {
+        noun: "snapshot bucket",
+        knob: "SESSION_SNAPSHOT_BUCKET",
+        defaultName: SESSION_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)",
+        createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment",
+    },
+    workspace: {
+        noun: "workspace snapshot bucket",
+        knob: "WORKSPACE_SNAPSHOT_BUCKET",
+        defaultName: WORKSPACE_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing",
+        createHint: "",
+    },
+};
 export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
 class SnapshotBucketMissing extends Error {
     constructor() {
         super("snapshot bucket missing");
     }
 }
-export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs, role = "session") {
+    const r = SNAPSHOT_BUCKET_ROLES[role];
     const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first check (STORE_LOCK_WAIT_MS=0: no wait)";
-    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the snapshot bucket "${bucket}" (SESSION_SNAPSHOT_BUCKET; default session-snapshots) does not exist there ${waited} — refusing to boot: ` +
-        `the server never creates buckets, so every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever). ` +
-        `Next: create the bucket (mc mb <alias>/${bucket}; this version's sema-up scripts create it — re-run them on an existing sema-up deployment), or set SESSION_SNAPSHOT_BUCKET to a bucket that exists.`);
+    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the ${r.noun} "${bucket}" (${r.knob}; default ${r.defaultName}) does not exist there ${waited} — refusing to boot: ` +
+        `the server never creates buckets, so ${r.consequence}. ` +
+        `Next: create the bucket (mc mb <alias>/${bucket}${r.createHint}), or set ${r.knob} to a bucket that exists.`);
 }
 export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
-export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+export async function ensureSnapshotBucket(store, waitMs, logger, clock, role = "session") {
     const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
     let verdict;
     try {
@@ -24,11 +42,11 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
             if (r.state === "missing")
                 throw new SnapshotBucketMissing();
             return r;
-        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
+        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { role, bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
     }
     catch (err) {
         if (err instanceof SnapshotBucketMissing)
-            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs, role), { cause: err });
         if (!isStoreOpenWindowExpired(err))
             throw err;
         verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
@@ -37,4 +55,14 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
         recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
     }
 }
+export async function ensureSnapshotBuckets(config, logger) {
+    const wanted = [
+        ["session", config.snapshotBlobStore],
+        ["workspace", config.remoteExec?.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
+    ];
+    for (const [role, store] of wanted) {
+        if (store)
+            await ensureSnapshotBucket(store, config.storeLockWaitMs, logger, undefined, role);
+    }
+}
 //# sourceMappingURL=snapshot-bucket-presence.js.map

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

@@ -26,14 +26,14 @@
  *     exec; this seam stays on the plain (sql, params) form.
  *
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * @contract txn.read-semantics — 本仓「事务里的读看到什么」的**唯一**成文处(S-131 / B-020 / B-022)
+ * @contract txn.read-semantics — 本仓「事务里的读看到什么」的**唯一**成文处([ref] / [ref] / [ref])
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
  * 五只店的头注此前各写一套「为什么用这个事务动词」的理由(截断的、漏数的、讲历史沿革的都有)。
  * 判据从今天起只有这一处,店里只留一行 `{@link SqlTxConn.begin}` 指回来。
  *
  * **① 事务动词只有一个** —— `begin()`。曾经那个「悲观」专用动词(MySQL 腿发 TiDB 专有的
  *    `BEGIN PESSIMISTIC`)已删除:那条语句在真 MySQL / MariaDB 上是 `ER_PARSE_ERROR`,四店 18 个事务
- *    一个都开不了(**B-020**),而它真正保证的东西现在由 ② 结构性地给出。同理,那个「可重复读」专用
+ *    一个都开不了(**[ref]**),而它真正保证的东西现在由 ② 结构性地给出。同理,那个「可重复读」专用
  *    动词也一并并入:隔离级不再由动词决定。
  *
  * **② 隔离级与事务模式是「连接的事实」,不是「动词的参数」** —— 见 {@link SqlDriver.facts}。
@@ -54,12 +54,12 @@
  *    的行**、读**值/时钟表达式**(不触任何存量行)、以及 PG 语法明禁加锁的形(**只有**聚合 / GROUP BY /
  *    DISTINCT / 窗口 / 集合运算;`ORDER BY … LIMIT 1` 尾行读在 PG 上**合法**加锁,不属此类——7.60.0 重扫纠)。
  *    理由:TiDB 悲观事务的普通 SELECT 仍钉 `start_ts`,`lockScope` 的锁等待窗内别副本的提交看不见
- *    (**B-022**);InnoDB REPEATABLE READ 下则由本事务的第一条一致性读建 read view —— 两条都是
+ *    (**[ref]**);InnoDB REPEATABLE READ 下则由本事务的第一条一致性读建 read view —— 两条都是
  *    **版本相关的副作用**,不是保证。机器门:`test/sql-txn-semantics-gate.test.ts`(G-B,例外闭集
  *    `INTRA_TXN_PLAIN_READS` 每条带理由);真值神谕:`test/sql-txn-semantics-integration.test.ts`(三引擎)。
  *
  * **④ 引擎事实不进店** —— `SqlDriver.facts` 是**运维读面**(`GET /v1/diagnostics/wiring` 的 `sqlEngine`
- *    段与 `GET /v1/capabilities` 的 `store.sql` 位(7.106.0 起;此前顶层 `sql`,S-866 ①))的料。店里不许出现 `if (engine === …)`:引擎判别在全仓
+ *    段与 `GET /v1/capabilities` 的 `store.sql` 位(7.106.0 起;此前顶层 `sql`,[ref] ①))的料。店里不许出现 `if (engine === …)`:引擎判别在全仓
  *    只有连接初始化这一处,机器门 G-A 守着。`SqlDialect`(SQL **文本**方言,两值)与 `engine`(运行期
  *    引擎事实,三值)是两条轴,刻意不合成一个三值。
  *
@@ -125,7 +125,7 @@ export interface SqlExec {
 /** A pooled connection with transaction control (released by the caller in a `finally`). */
 export interface SqlTxConn extends SqlExec {
     /**
-     * The ONE transaction verb (S-131). What its reads see is NOT decided here — it is decided once per
+     * The ONE transaction verb ([ref]). What its reads see is NOT decided here — it is decided once per
      * pooled connection at initialization and reported by {@link SqlDriver.facts}. Read the
      * `@contract txn.read-semantics` block at the top of this file before adding a transaction: the
      * short version is **intra-transaction collection reads are LOCKING reads**, and a plain `SELECT`
@@ -145,7 +145,7 @@ export interface SqlTxConn extends SqlExec {
  */
 export type SqlEngine = "tidb" | "innodb" | "pg";
 /**
- * What connection initialization ESTABLISHED and then READ BACK on this driver's pool (S-131 §1
+ * What connection initialization ESTABLISHED and then READ BACK on this driver's pool ([ref] §1
  * 补偿面). Operator read faces: `GET /v1/diagnostics/wiring` → `sqlEngine`, `GET /v1/capabilities`
  * → `sql`. Store code must never read this (machine gate G-A) — engine discrimination exists in
  * exactly one place in this repo, and it is `connect()`.
@@ -322,7 +322,7 @@ export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
 export declare function sqlWallsOf(engine: SqlEngineReading | undefined): SqlWallsReading;
 /**
  * **数据库自己的钟**(毫秒),两方言各一句 —— 本仓这口钟在 SQL 面的**唯一**铸点([ref] A7 / [ref] /
- * 合并复审 R2 把 S-280 的 nonce 店并进来)。
+ * 合并复审 R2 把 [ref] 的 nonce 店并进来)。
  *
  * 用处永远是同一条:**一个时刻量的铸造点与它的判定点必须在同一个钟域**。副本各拿各的墙钟时,两台机器
  * 之间的偏差没有任何一条腿强制过上界(本仓 [ref]③ 记过一次真实的 11 分钟 NTP 纠正),于是
@@ -359,7 +359,7 @@ export interface SqlDriver extends SqlExec {
      *  · `null`(还没借出过连接)—— 没有可报的东西,**不猜**;
      *  · 事实 —— 最近一次初始化**回读复核**过的值。每条池连接首次借出都重跑一次初始化(记忆化按连接身份),
      *    所以池在致命错误后重连时,保证是在新连接上**重新建立**的,不是继承来的;
-     *  · `null`(借出过、但最近一次初始化被**拒**)—— S-137 ④:保证此刻建立不起来,读面就报缺席。
+     *  · `null`(借出过、但最近一次初始化被**拒**)—— [ref] ④:保证此刻建立不起来,读面就报缺席。
      *    此前这里是「一次成功即长期有效」的快照:连接被驱逐、新连接初始化被拒之后,诊断面仍在陈述一条
      *    已经不成立的结构保证。降级由 `establishSession()` 一处完成,并留 loud warn。
      */

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

@@ -90,7 +90,7 @@ export declare const PG_DEADLOCK_DETECTED_SQLSTATE = "40P01";
  * 它**不是**「锁序可以随便写」的许可证 —— 锁序的属主仍是店(真值神谕 =
  * `test/sql-lock-shape-innodb-integration.test.ts` 三引擎并发套)。
  *
- * 引擎事实(2026-09-20 真 InnoDB 实测,S-529 取证):同一把缺行主键上 N=8 路并发「`FOR UPDATE` 缺行读
+ * 引擎事实(2026-09-20 真 InnoDB 实测,[ref] 取证):同一把缺行主键上 N=8 路并发「`FOR UPDATE` 缺行读
  * → `INSERT`」,InnoDB(REPEATABLE READ,gap lock + insert-intention)恒定 1 成 7 死锁;TiDB(悲观、无
  * gap lock)与 PG(READ COMMITTED,缺行 `FOR UPDATE` 不取锁)各自零死锁。⇒ 这条谓词实际的受众是
  * **MySQL 协议腿**,两方言都认只是为了让店不必自己判引擎。
@@ -129,11 +129,13 @@ export declare function rowTooLargeWallOf(dialect: SqlDialect, err: unknown): Ro
  * (`ErrEntryTooLarge`,事务层的语句错;真库读数:同池上 8025 写之后的读照常 —— `checkpoint-row-size-db-integration` ②③④)。
  * 断连形(`ECONNRESET` / `EPIPE` / `PROTOCOL_CONNECTION_LOST`)也不在表里:那是 mysql2 的**致命错误**,连接对象自己已经 `_removeFromPool`。
  * PostgreSQL 没有对应面:node-pg 的 `pool.query` 对任何错误都丢弃那条 client。
+ * `statementRefusal`:这一行的错说的是**这一条语句**被拒(连接坏只是后果)—— 同一句话换一条连接重试仍被拒。{@link isConnectionFaultError} 读同一张表,认其余各行为连接类故障,唯独不认带这个标记的行。
  * 新增一行 = 改表 + 在 `test/db-closed-connection-never-pooled.test.ts` 的码表里加一格。
  */
 export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
     readonly errno: number;
     readonly code: string;
+    readonly statementRefusal?: true;
 }>;
 /**
  * 「抛出这个错误的那条连接还能不能回池」的单一判据:{@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 里的错 ⇒ **不能** —— 持连接的一方(`sql-driver.ts` 的 `leaseOf`)
@@ -141,6 +143,43 @@ export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
  * 认不出的一律不是(连接照常归还;断连形由 mysql2 自己清出池)。只管 MySQL 协议的错误形:PG 的错误没有这两个键,恒 false。
  */
 export declare function isConnectionUnusableError(err: unknown): boolean;
+/**
+ * **连接类故障**的识别表(闭集;逐行登记「为什么」)—— 「到库的那条连接坏了 / 库此刻不接」:与这一条语句的内容无关、什么都不改稍后再试可能成。
+ * 读者(整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,三处同读):审批队列读口、文件历史店的折点(`permanence: "transient"`)、会话同步拉取口(`503`)。
+ *
+ * 识别集 = 三张表的并集,**没有第四处**:
+ *  · 本表(下):套接字层与协议层的断连 / 拒连 / 连接数满 / 库的关停与只读切换,按 `code` 登记(MySQL 协议的数字 errno 在场的并登 —— 同本文件其余谓词的姿势:`errno` 与 `code` 是同一件事的两种写法);
+ *  · {@link MYSQL_CONNECTION_UNUSABLE_ERRORS}(「这条连接不许再回池」的 MySQL 协议错):整表读入,**唯独不认带 `statementRefusal` 的行**(1153:拒的是这一条语句,不是连接);
+ *  · {@link CONNECTION_FAULT_DRIVER_SENTENCES}:驱动自己抛的**无 `code` 的裸 `Error`**(node-pg 的断连在这一形),按整句相等认。
+ *
+ * **不在识别集里**(认不出一律不是 —— 错判成连接类的代价是调用方被劝「再试」去撞一个注定失败的语句):
+ *  · 语句级的错:唯一键冲突、CHECK 被拒、缺表缺列、语法错、权限错、行 / 包超墙(1153 / 8025 / `54000`);
+ *  · 死锁(引擎的仲裁产物,重试的前提在调用方的整事务重来,见 {@link isDeadlockError})与锁等待 / 语句超时(延迟信号,重试只把长等待乘上次数);
+ *  · 认证类拒连(MySQL 1045、PG `28xxx`、`08004`:凭据 / 白名单要人去改)与协议违例(PG `08P01`、mysql2 `PROTOCOL_ERROR`:我方的码病);
+ *  · TiDB 自己的忙 / 区域不可用(9001 / 9005 一族)—— 候真库逐码读数再登,今天不在表里(登记在案的未收项);
+ *  · 池已被我方关闭(`Pool is closed.` / `Cannot use a pool after calling end on the pool`):那是本进程在收摊,不是库的事。
+ * 只看被抛出的**这一只**对象(不沿 `cause` 链往下找):店层把驱动错包进自己的类时,包它的那一层要不要继承连接类,归那一层的契约说,不在这里猜。
+ */
+export declare const CONNECTION_FAULT_ERRORS: ReadonlyArray<{
+    readonly code: string;
+    readonly errno?: number;
+    readonly why: string;
+}>;
+/**
+ * 驱动**自己抛的、不带 `code` 的裸 `Error`** 的整句 —— 连接类故障的第三种归因键。node-pg 的断连 / 池连接超时就是这一形(`new Error('Connection terminated unexpectedly')`,
+ * 没有任何结构化字段可读),mysql2 的「连接已关闭」同形。**整句相等**才认(不是 `includes`):一句夹着用户路径 / 数据的散文伪造不出驱动句;且只认 `code` 缺席的 `Error`。
+ * 每一行的 `source` 是它在驱动源码里的出处文件,`test/store-fault-judge.test.ts` 读已装驱动的源码核句子仍在(驱动升级改了句子 ⇒ 红,而不是判官悄悄静音)。
+ */
+export declare const CONNECTION_FAULT_DRIVER_SENTENCES: ReadonlyArray<{
+    readonly sentence: string;
+    readonly source: string;
+    readonly why: string;
+}>;
+/**
+ * 「这个错误**是**连接类故障吗」—— {@link CONNECTION_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
+ * 归因键三种:`code`(字符串)、`errno`(数字)、无 `code` 的驱动裸 `Error` 的整句 —— 只读被抛出的这一只对象身上的结构化字段 / 整句,**不读散文里的在册词**。
+ */
+export declare function isConnectionFaultError(err: unknown): boolean;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -64,7 +64,7 @@ export function rowTooLargeWallOf(dialect, err) {
 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: 1153, code: "ER_NET_PACKET_TOO_LARGE", statementRefusal: true },
     { errno: 1158, code: "ER_NET_READ_ERROR" },
     { errno: 1159, code: "ER_NET_READ_INTERRUPTED" },
     { errno: 1160, code: "ER_NET_ERROR_ON_WRITE" },
@@ -82,6 +82,54 @@ export function isConnectionUnusableError(err) {
     const code = keyOf(err, "code");
     return (typeof errno === "number" && UNUSABLE_ERRNOS.has(errno)) || (typeof code === "string" && UNUSABLE_CODES.has(code));
 }
+export const CONNECTION_FAULT_ERRORS = [
+    { code: "ECONNRESET", why: "对端重置了连接(库重启 / 代理断流 / 空闲连接被回收)" },
+    { code: "ECONNREFUSED", why: "库此刻不接连接(进程没起 / 端口没开 / 滚动重启中)" },
+    { code: "ECONNABORTED", why: "连接在建立或使用中被本机协议栈中止" },
+    { code: "EPIPE", why: "写一条对端已经关掉的连接" },
+    { code: "ETIMEDOUT", why: "连接 / 套接字超时(mysql2 的 `connectTimeout` 同答此码)" },
+    { code: "EHOSTUNREACH", why: "到库的主机不可达(路由 / 节点切换)" },
+    { code: "ENETUNREACH", why: "到库的网络不可达" },
+    { code: "EAI_AGAIN", why: "DNS 临时失败(「稍后再试」是它自己的定义)" },
+    { code: "PROTOCOL_CONNECTION_LOST", why: "mysql2:服务端关了连接(`Connection lost: The server closed the connection.`,带 `fatal: true`)" },
+    { code: "ER_CON_COUNT_ERROR", errno: 1040, why: "连接数满(`Too many connections`)—— 别人放连接之后就好" },
+    { code: "08000", why: "PG connection_exception" },
+    { code: "08001", why: "PG sqlclient_unable_to_establish_sqlconnection" },
+    { code: "08003", why: "PG connection_does_not_exist" },
+    { code: "08006", why: "PG connection_failure" },
+    { code: "57P01", why: "PG admin_shutdown(库被管理员关停 / 重启)" },
+    { code: "57P02", why: "PG crash_shutdown" },
+    { code: "57P03", why: "PG cannot_connect_now(启动 / 恢复中)" },
+    { code: "53300", why: "PG too_many_connections" },
+    { code: "25006", why: "PG read_only_sql_transaction(故障切换后落在只读节点)" },
+];
+export const CONNECTION_FAULT_DRIVER_SENTENCES = [
+    { sentence: "Connection terminated unexpectedly", source: "pg/lib/client.js", why: "node-pg:连接在使用中被对端关掉" },
+    { sentence: "Client has encountered a connection error and is not queryable", source: "pg/lib/client.js", why: "node-pg:这条 client 的连接已出错,后续语句直接拒" },
+    { sentence: "Connection terminated due to connection timeout", source: "pg-pool/index.js", why: "node-pg 池:建连超过 `connectionTimeoutMillis`" },
+    { sentence: "timeout exceeded when trying to connect", source: "pg-pool/index.js", why: "node-pg 池:排队等连接超过 `connectionTimeoutMillis`" },
+    { sentence: "Can't add new command when connection is in closed state", source: "mysql2/lib/base/connection.js", why: "mysql2:往一条已被对端关掉的连接上发语句(带 `fatal: true`、无 `code`)" },
+];
+const CONNECTION_FAULT_CODES = new Set([
+    ...CONNECTION_FAULT_ERRORS.map((r) => r.code),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.code),
+]);
+const CONNECTION_FAULT_ERRNOS = new Set([
+    ...CONNECTION_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.errno),
+]);
+const CONNECTION_FAULT_SENTENCES = new Set(CONNECTION_FAULT_DRIVER_SENTENCES.map((r) => r.sentence));
+export function isConnectionFaultError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = keyOf(err, "code");
+    const errno = keyOf(err, "errno");
+    if (typeof code === "string" && CONNECTION_FAULT_CODES.has(code))
+        return true;
+    if (typeof errno === "number" && CONNECTION_FAULT_ERRNOS.has(errno))
+        return true;
+    return err instanceof Error && code === undefined && CONNECTION_FAULT_SENTENCES.has(err.message);
+}
 export class StoreRowTooLargeError extends Error {
     row;
     wall;

package/dist/plugins/sql-json-column.d.ts

@@ -1,5 +1,5 @@
 /**
- * **SQL JSON 列读腿的唯一属主**(S-550 设计稿 §2)—— 一列 JSON 怎么**投影**、怎么**恰好解一次码**、
+ * **SQL JSON 列读腿的唯一属主**([ref] 设计稿 §2)—— 一列 JSON 怎么**投影**、怎么**恰好解一次码**、
  * 读不出形怎么**拒**,整仓只有这一份定义。
  *
  * ── 病(KM / 7.92.2 C1 的真案,三库实测两次换形之后的终形)────────────────────────────────────
@@ -23,11 +23,11 @@
  * `test/sql-json-column-single-owner.test.ts` 四道:①`JSON.parse(` 在 `src/plugins/**` 只许出现在本文件
  * (未改调的店走显式 `PENDING_STORES` 登记 + 反向门);②JSON 承载列(清单由 `schema-ensure-legs` 的录制
  * 驱动**机器派生**,不手抄)在 SELECT 投影里必须经 {@link jsonColumnText};③{@link decodeJsonColumn} 的
- * `read` 实参必须是具名读者,禁内联 `(b) => b as T`;④(S-577)**读者 × 列可空性**求交,**双向**:每一只
+ * `read` 实参必须是具名读者,禁内联 `(b) => b as T`;④([ref])**读者 × 列可空性**求交,**双向**:每一只
  * 形读者对承载列的可空性要求写在门的那张闭集表里,与 DDL 机器派生的读数不符即红(两个方向各一格)。
  * 那条要求此前是注释里的一句散文,而整仓第二个用它的地方把它违了一整版。
  *
- * ── 「任意 JSON 值」那一族的三只铸点(S-577;区别在**名字**里,不在散文里)─────────────────────
+ * ── 「任意 JSON 值」那一族的三只铸点([ref];区别在**名字**里,不在散文里)─────────────────────
  * 一列的载荷没有声明形时,`null` 字面算不算合法值,**只由这一列有没有「缺席」这个状态**决定 —— 而那是
  * 列可空性的另一种说法。所以这一族按可空性拆成三只,各自的前置条件由门双向咬:
  *  | 铸点 | 承载列必须 | JSON 字面 `null` |
@@ -69,9 +69,9 @@ export interface JsonColumnMember {
  *
  * 🔴 存在的唯一理由是「别名位在那里不合法」,**不是**给读腿留第二条路:读腿一律用 {@link jsonColumnText}
  * (别名是它的产物的一部分,理由见那只函数)。今天整仓**两处**消费方,各自的「别名位不合法」都是真的:
- *  · `one-time-migrations.ts` 的 M4(把 `device_audit.detail` 里 JSON 文本 `null` 的旧行改成列 NULL)——
- *    它要在 `WHERE` 里判这一列的**文本**,而 `WHERE` 没有别名位;
- *  · `workflow-journal-store-sql.ts` 的 `loadPage`(S-550 车③a)—— 那一列的投影裹在一条
+ *  · `one-time-migrations.ts` 的几条改写(M8 / M17 / M18 / M21 的候选扫描与按原文 CAS 回写)——
+ *    它们要在 `WHERE` 里判这一列的**文本**,而 `WHERE` 没有别名位;
+ *  · `workflow-journal-store-sql.ts` 的 `loadPage`([ref] 车③a)—— 那一列的投影裹在一条
  *    `CASE WHEN LENGTH(result) > ? THEN NULL ELSE <expr> END AS result_json` 里:**别名属于整条 CASE**
  *    (`result_json`,因为超字节门的那一支要给 `NULL`),CASE 里面的表达式位上写别名是语法错。
  * 而「怎么把一列 JSON 取成文本」这件事整仓只能有一种写法:两种承载(真 JSON 列 / LONGTEXT 别名)在这条
@@ -106,9 +106,9 @@ export type SqlJsonColumnBodyProblem = Exclude<SqlJsonColumnProblem, "not-text">
  * 店层码,**不上 wire**:店层折码口 {@link foldJsonColumn} 把它折成 {@link StoreCorruptError}
  * (有自己闭集契约词的店折成自己的码)。终局对外码经 7.92.2 的词法门,永不裸穿。
  *
- * 🔴 **它只许在 `not-text` 那一形上穿过店的边界**(S-608):`not-text` 是读腿自己的缺陷(投影漂),
+ * 🔴 **它只许在 `not-text` 那一形上穿过店的边界**([ref]):`not-text` 是读腿自己的缺陷(投影漂),
  * 按 {@link foldJsonColumn} 的规则不折、原样上抛;而体的两形一旦穿出去,上层就得**按列错误类**分类,
- * 那正是 S-608 的病 —— 读口按列错误分类、店按店拒绝形折码,两层各说各话,坏体于是落进「店抖动」臂。
+ * 那正是 [ref] 的病 —— 读口按列错误分类、店按店拒绝形折码,两层各说各话,坏体于是落进「店抖动」臂。
  */
 export declare class SqlJsonColumnError extends Error {
     readonly problem: SqlJsonColumnProblem;
@@ -157,9 +157,9 @@ export declare function decodeNullableJsonColumn<T>(cell: unknown, read: JsonCol
 /**
  * **「这一格耐久载荷读不出来」的店层拒绝**(整仓唯一一只)—— {@link foldJsonColumn} 的**恒定产物**。
  *
- * 🔴 为什么它必须是一只**具名类**而不是 `new Error(…)`(S-608 真案,7.95.1):折码的产物是**店交给
+ * 🔴 为什么它必须是一只**具名类**而不是 `new Error(…)`([ref] 真案,7.95.1):折码的产物是**店交给
  * 上层的契约**。折成裸 `Error` 之后,「这一行确定性地读不出来」与「店抖了一下」在上层**没有任何判别位**,
- * 而两者的处置完全相反(前者要人去修那一行,后者重试 / 保守当缺席)。S-577 给续跑上下文修的正是这条
+ * 而两者的处置完全相反(前者要人去修那一行,后者重试 / 保守当缺席)。[ref] 给续跑上下文修的正是这条
  * 分家,可它在 SQL 车道上**结构不可达**整整一版:读口按**列错误类**分类,而店早把列错误折成了裸
  * `Error` ⇒ 坏体一路掉进「店抖动 ⇒ 当缺席」臂,用户拿到的还是那个 409(local 车道答对,只是因为它
  * 根本没折码、把列错误漏了出来 —— 巧合式正确,不是同一份契约)。
@@ -187,9 +187,9 @@ export declare class StoreCorruptError extends Error {
 /**
  * 店层折码的**唯一规则**(`catch (e) { throw foldJsonColumn(e, (m) => \`XStore: ${m} — refusing …\`); }`)。
  *
- * 🔴 回调交出来的是**一句话**,不是一只错误(S-608 按类改):产物恒是 {@link StoreCorruptError},于是
+ * 🔴 回调交出来的是**一句话**,不是一只错误([ref] 按类改):产物恒是 {@link StoreCorruptError},于是
  * 「折成一只没有判别位的错」在**构造上**写不出来。此前这一格的签名是 `(message) => Error`,21 个调用点
- * 里 19 个折成了裸 `Error` —— 每一个都是一枚等着下一个消费方来踩的 S-608。
+ * 里 19 个折成了裸 `Error` —— 每一个都是一枚等着下一个消费方来踩的 [ref]。
  *
  * 🔴 `not-text` **不折**:它是读腿自己的缺陷(投影漏了),折成「这一行坏了」会把一次代码漂伪装成一次
  * 数据事故 —— 这条判别只写在这里一处(与它的容忍侧孪生 {@link isJsonColumnBodyProblem} 共用),
@@ -233,7 +233,7 @@ export declare function createZodColumnReader<T>(schema: z.ZodType<T>): JsonColu
  * 该店的域型交出去。整仓**只有这一处**做这一跳断言。
  *
  * 🔴 什么时候用它(硬条件,别扩大):这一列的键表属主**不在本层**,而那一层**没有导出验证器**。
- * 两族,判据同一条(S-577 把这段与本函数第一句对齐 —— 它此前只写了 core 那一族,于是第二族要么被迫
+ * 两族,判据同一条([ref] 把这段与本函数第一句对齐 —— 它此前只写了 core 那一族,于是第二族要么被迫
  * 违注、要么被迫另造一只读者,而「加一只特例读者」在本仓是红旗):
  *  · 属主在 **core**:`Checkpoint` / `ResumeOutcome` / `GateOutcome` / `WorkflowRun` /
  *    `BackgroundAgentRecord` …;
@@ -246,7 +246,7 @@ export declare function createZodColumnReader<T>(schema: z.ZodType<T>): JsonColu
  * 一列只要有**本层自己的** schema 属主,就必须用 {@link createZodColumnReader} —— 用本函数等于把形判据关小。
  *
  * 🔴 为什么是一只工厂而不是让每个店各写一遍 `typeof body !== "object"`:那是同一条判据的 N 份拷贝
- * (S-550 车② 初版真的写了六份),而且每一份都要自己那一跳 `as`。收成一处之后,判据只有一个写者,
+ * ([ref] 车② 初版真的写了六份),而且每一份都要自己那一跳 `as`。收成一处之后,判据只有一个写者,
  * 断言也只发生在这一行 —— 类型卫生门因此在每个店里都读到零。
  */
 export declare function createObjectColumnReader<T extends object>(): JsonColumnReader<T>;
@@ -265,17 +265,17 @@ export declare function isJsonObject(v: unknown): v is Record<string, unknown>;
  *
  * 🔴 前置条件(**门④ 机器执法,不是散文**):承载列**可空**,而「缺席」在它上面由**列的 NULL** 单独表达
  * (三态列);于是 JSON 字面 `null` 是一个与缺席**不同形**的合法值。用在 `NOT NULL` 列上当场红 —— 那种列
- * 根本没有缺席态,`null` 字面与「没有这一行」在点读的消费点上逐字同答,而那正是 S-577 的病灶
+ * 根本没有缺席态,`null` 字面与「没有这一行」在点读的消费点上逐字同答,而那正是 [ref] 的病灶
  * (`checkpoint_ctx.ctx`:`JSON NOT NULL` + 有结构的载荷,一整版都读回一个没人分得出来的 `null`)。
  * NOT NULL 且契约不透明的列用 {@link readOpaqueJsonValueColumn};缺席落 SQL NULL 的用
  * {@link readNonNullJsonValueColumn}(那一族把 `null` 字面判坏)。
  *
  * 之所以叫得出「三态」:范本是 `approval_ask.updated_input`([ref] / [ref])—— 列 NULL = 没带编辑,
  * JSON 文本 `"null"` = **编辑成 null**,对象 = 编辑成那只对象;把 `"null"` 判成坏体会把一条合法的人类
- * 编辑抹掉。这一句是**理由**,不是名单:哪几处在用它由门数,别在这里写计数(S-577 之前这里写着
+ * 编辑抹掉。这一句是**理由**,不是名单:哪几处在用它由门数,别在这里写计数([ref] 之前这里写着
  * 「今天整仓只有一处符合」—— 那句话当时就是假的,而没有门看着的计数,下一个人加第二处时不会来改它)。
  *
- * 一列只要有结构,就**不许**用它 —— 那是把形判据静默关掉(这条是 S-577 的病灶判据,三只铸点同守)。
+ * 一列只要有结构,就**不许**用它 —— 那是把形判据静默关掉(这条是 [ref] 的病灶判据,三只铸点同守)。
  */
 export declare const readTriStateJsonValueColumn: JsonColumnReader<unknown>;
 /**
@@ -294,14 +294,14 @@ export declare const readTriStateJsonValueColumn: JsonColumnReader<unknown>;
  * 🔴 **它与 {@link readTriStateJsonValueColumn} 的实现逐字相同,而且必须各自独立写出来** —— 不许收成
  * `export const readOpaqueJsonValueColumn = readTriStateJsonValueColumn`(门④c2 会红)。两只的区别整个
  * 落在**前置条件**上(一只要可空列、一只要 NOT NULL 列),而前置条件的载体就是**名字**:合成一个名字就等于
- * 把两条互斥的前置条件重新揉回一起 —— 那正是 S-577 立案时那条散文析取的形。「去重」在这里去掉的不是重复,
+ * 把两条互斥的前置条件重新揉回一起 —— 那正是 [ref] 立案时那条散文析取的形。「去重」在这里去掉的不是重复,
  * 是判据。
  */
 export declare const readOpaqueJsonValueColumn: JsonColumnReader<unknown>;
 /**
  * **任意 JSON 值,但缺席由「列 NULL」表达**的列的形读者 —— `null` 字面判坏,其余一律是值。
  *
- * 🔴 这是**写腿吃 `unknown` 的那一族列**的正解(codex 对抗复审 [high] 验真后定形,S-550 车②):
+ * 🔴 这是**写腿吃 `unknown` 的那一族列**的正解(codex 对抗复审 [high] 验真后定形,[ref] 车②):
  * 写腿接的是 `unknown`(`PendingAction.args` / 账本行载荷 / leader 结果……),于是**数组 / 串 / 数 /
  * 布尔实参都写得进去** —— 拿 {@link readJsonObjectColumn} 判它们就是「写腿收得下、读腿读不出」,而且
  * 后果往往不是一行坏:`rows.map` 里一条这样的合法行会让整只读面抛。
@@ -312,14 +312,14 @@ export declare const readOpaqueJsonValueColumn: JsonColumnReader<unknown>;
  * (根本没有缺席态),用 {@link readOpaqueJsonValueColumn}。
  *
  * 🔴 与 {@link readTriStateJsonValueColumn} 同属「承载列必须**可空**」这一族,所以同受门④ 约束
- * (S-577):这族读者用在 `NOT NULL` 列上一律红 —— 列上没有 NULL 这个状态,「缺席」就无处安放,而写腿把
+ * ([ref]):这族读者用在 `NOT NULL` 列上一律红 —— 列上没有 NULL 这个状态,「缺席」就无处安放,而写腿把
  * 缺席落成 SQL NULL 这句话在那种列上根本执行不了。
  */
 export declare const readNonNullJsonValueColumn: JsonColumnReader<unknown>;
 /**
  * **一只 JSON 数组**的承载形读者(内容判据归各列自己的既有属主,这里只判承载形)。
  *
- * 🔴 为什么在属主里而不是各店各写一遍(S-550 车③a 把车② 的店内私有形上收):今天有三个消费方
+ * 🔴 为什么在属主里而不是各店各写一遍([ref] 车③a 把车② 的店内私有形上收):今天有三个消费方
  * (checkpoint 的 `rule_suggestions` / `pending_steer_queue`、memory-engine 的 `embedding`),判据逐字
  * 相同,而「这一格是不是一只数组」恰好是坏体四形的落点 —— 三份拷贝迟早有一份忘了判 `null` 字面。
  */

package/dist/plugins/sql-row-helpers.d.ts

@@ -4,8 +4,8 @@
  * These were duplicated verbatim across the pg-/tidb- store twin pairs; each store imports the flavor
  * it was written against so call sites and semantics are byte-identical to before.
  *
- * 🔴 **JSON 列的解析不在这里,也永远不会回来**(S-550):本文件曾住着三只 `parseJson*`
- * (lenient → `null` / strict → 抛 / fallback → 兜底),三种失败方向由**调用点自选** —— 那正是 S-550
+ * 🔴 **JSON 列的解析不在这里,也永远不会回来**([ref]):本文件曾住着三只 `parseJson*`
+ * (lenient → `null` / strict → 抛 / fallback → 兜底),三种失败方向由**调用点自选** —— 那正是 [ref]
  * 要消灭的现状:同一格读不出的 JSON,在一个店里是「空体」、在另一个店里是「这一行不存在」、在第三个
  * 店里是异常。三只在车③b **删除**(零别名、零转出),整仓唯一属主 = `sql-json-column.ts`
  * (按文本投影 · 恰好解一次码 · 坏体一律拒),容忍写在店的调用点上(显式 `try/catch` + `recordFailOpen`)。