@sema-agent/server 7.130.0 → 7.132.0

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

@@ -157,7 +157,148 @@ export interface SqlEngineFacts {
     readonly isolation: string;
     /** TiDB's session `tidb_txn_mode`; `null` = this engine has no such indicator (NOT "optimistic"). */
     readonly txnMode: "pessimistic" | null;
+    /**
+     * The largest single row this engine stores, in bytes — the **one** source of that number in this repo. Every
+     * row this service writes from a submitted request (the user message in `session_event`, the resume inputs in
+     * `checkpoint_ctx`) has to fit it, so the submit admission reads it (`http/request-guards.ts`
+     * `refuseSubmitBody`) instead of carrying a copy of the number.
+     *  · **TiDB** — the effective `txn-entry-size-limit`, read at initialization: the session variable
+     *    `@@tidb_txn_entry_size_limit` when it is non-zero (TiDB 7.6+; 0 there means "use the config item"), else
+     *    `performance.txn-entry-size-limit` from `SHOW CONFIG` (the smallest value across TiDB instances: a request
+     *    may land on any of them). Neither readable (the config read needs the `CONFIG` privilege; older TiDB has no
+     *    session variable) ⇒ TiDB's own default {@link TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT}, recorded through
+     *    `recordFailOpen("server.sql.tidb-row-cap-unread")` (a per-hit count and one warn line naming both reads).
+     *  · **`null`** — this engine has **no single-row wall** below the request cap: PostgreSQL (`jsonb` holds 255 MiB)
+     *    and InnoDB (it has no row-size wall of this kind; its wall is the statement-level one, a different fact:
+     *    {@link maxPacketBytes}). `null` is the ONLY spelling of "no wall" — an unreadable value is never folded into it.
+     *    Only two writes translate a row-size refusal into the coded
+     *    `StoreRowTooLargeError` (`sql-errors.ts`): the checkpoint store's `putCtx` (resume inputs) and `put` (the INSERT of
+     *    a pending row). Every other write — the checkpoint store's updates (`resolve` / `reopen` / …), the session log —
+     *    keeps its existing driver error.
+     */
+    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").
+     *  · **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.
+     */
+    readonly maxPacketBytes: number | null;
+    /**
+     * Where each wall's number came from — the **one** record of "read, or fell back to a documented default", parallel to {@link maxRowBytes} and
+     * {@link maxPacketBytes} (see {@link SqlWallSource}). `"reported"` = the database answered at connection initialization (or, for a `null` wall,
+     * the engine has no such wall by construction); `"assumed"` = the reading failed and the documented default of the server family stands in for the
+     * number (the same two reads that go through `recordFailOpen`). The submit admission and the SQL snapshot-blob cap report it as `wallSource`, so a
+     * refusal never presents a default as the database's own limit.
+     */
+    readonly wallSources: SqlWallSources;
+}
+/** TiDB's documented default for `performance.txn-entry-size-limit` (6 MiB): the cap a single row (key + value)
+ *  may reach. Used only when the engine's own reading cannot be had ({@link SqlEngineFacts.maxRowBytes}). */
+export declare const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6291456;
+/**
+ * 一份载荷落进库行时,行里**载荷之外**的那部分的余量(字节)—— **按行的形各一只**:行墙只有一堵(`SqlEngineFacts.maxRowBytes`),余量是落进它的那种行的物理,
+ * 两种行的余量差两个数量级,借用就会让一个读者的门限偏离它自己那种行能装下的量。
+ *  · `json` —— 提交体落进的两种行:会话日志里的用户消息(`session_event.payload`:条目把内联图 / 附件 / objective 包上 id 与时间戳)与 durable 审批部署上的续跑输入
+ *    (`checkpoint_ctx.ctx`:体 + 写者版本 / memoryScope / 两枚读法记号)。余量盖住其余全部:
+ *     - 包装键与行上的其余列:几百字节(TiDB 7.5.1 实测:体里带一只 6 815 544 字符串的续跑输入行,库报 6 815 845 字节 —— 比那只串多 301 字节,其中约 105 字节是串外面的 JSON 文本);
+ *     - TiDB 以二进制形存 JSON,每个数组元素 / 对象成员比文本多约 5–11 字节;一份提交体的结构(三只规则桶各 ≤ 1000 条、agents、skills…)在几千个元素以内 ⇒ 几十 KiB。
+ *    64 KiB 盖住这两件还有富余;结构超出它的体照样会被库在写的那一刻拒 —— 提交时写续跑输入的那一笔(durable 审批部署)答同一个 413(店的带码拒,`submit-ctx.ts`),
+ *    开跑后的写(会话日志的用户消息)按各自的既有失败面。
+ *  · `blob` —— SQL 快照 blob 的行(`snapshot_blob` / `file_history_blob`:`blob_hash CHAR(64)` 主键 + `byte_len BIGINT` + `created_at DATETIME(3)` + `bytes LONGBLOB`)。
+ *    TiDB 的单行上限量的是这一行的键值对。键 ≈ 表前缀 `t` + 8 字节表 id + `_r` + 行句柄(非聚簇 8 字节;聚簇时是 CHAR(64) 主键的可比较编码,每 8 字节加 1 字节组标 = 72 字节)
+ *    ⇒ 至多约 83 字节;值 = 行格式 v2:头 6 字节 + 4 列的列 id 与偏移(大行形各 4 字节 = 32 字节)+ 三列定长数据(哈希 64 + 长度 8 + 时间 8 = 80 字节)+ 可选行校验 5 字节
+ *    ⇒ 约 123 字节。合计约 206 字节;字节列按原字节存,没有 JSON 的逐元素开销。取 1 KiB = 实需的近 5 倍(与包墙那只语句余量 {@link STATEMENT_ALLOWANCE_BYTES} 同一量级),
+ *    真库读数由 db 组 `sql-txn-semantics-integration` ①c 钉(恰在帽上的 blob 真写得进)。
+ *
+ * 余量是**墙的物理**:每堵墙、每种行一只余量,各只在这里定义一次;两个读者(提交体受理口读 `json`、blob 缺省帽读 `blob`)经 {@link rowWallPayloadBytes} 按行的形取。
+ */
+export declare const ROW_WALL_ALLOWANCE_BYTES: {
+    readonly json: number;
+    readonly blob: 1024;
+};
+/** 落进行墙的两种行(见 {@link ROW_WALL_ALLOWANCE_BYTES})。 */
+export type RowWallRowShape = keyof typeof ROW_WALL_ALLOWANCE_BYTES;
+/**
+ * 一条语句里**载荷之外**的字节余量 —— 固定语句文本 + 表名 + 64 字符哈希 + 长度 + 时间戳 + 行包装(mysql2 真格式化量过:最长表名
+ * `file_history_blob` 的 blob INSERT 在 blob 之外 240 字节)。1 KiB 盖住它的 4 倍还多,又不松到压低可用量(16 MiB 包墙下少 1 KiB)。
+ * 不扣的话恰在包墙上的载荷整条语句会超出包墙几百字节:放行、库在写那一刻拒。经 {@link packetWallStatementBytes} 被两个读者共读。
+ */
+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 缺省帽的包墙腿(再按膨胀律折半)读它。 */
+export declare function packetWallStatementBytes(maxPacketBytes: number): number;
+/**
+ * 一段文本作为**一只字符串字面**进 MySQL 协议语句时占的字节数(不含外层两只引号)—— 店真正发出去的字节,不是文本自己的字节数。
+ * 店用 `pool.query(sql, [text])`,mysql2 在客户端把参数格式化进语句(`sql-escaper` 的 `escapeString`):`\0 \b \t \n \r \x1a " ' \` 九个字符各变成两个字符
+ * (多一个反斜杠字节),其余字符原样 —— 多字节 UTF-8 不受影响。所以一份 JSON 里引号 / 反斜杠越多,语句越比文本长(上界 2×:每个字符至多多一字节)。
+ *
+ * 受理口的包墙腿量它(`http/request-guards.ts` `refuseSubmitBody`):门承诺「写不进去的体在任何副作用之前 413」,量的就必须是语句字节。
+ * 这是 mysql2 转义表的**镜像**,不是第二份读法:`test/store-row-cap.test.ts` 把它逐字钉在 mysql2 自己的 `escape` 上(`escapedStatementBytes(s) ===
+ * Buffer.byteLength(mysql.escape(s)) − 2`,含全码点表扫),mysql2 升级改转义表时那格先红。不直接调 `escape` 取长度,是因为那会为一份 8 MiB 的体再造一份 8–16 MiB 的字符串。
+ */
+export declare function escapedStatementBytes(text: string): number;
+/**
+ * The documented default `max_allowed_packet`, per MySQL-protocol engine family — the landing when the live reading cannot be
+ * had ({@link SqlEngineFacts.maxPacketBytes}). Closed over the MySQL-protocol engines (an engine added to {@link SqlEngine} is a
+ * compile error here until its row is written).
+ *  · **tidb** — 64 MiB (67 108 864): TiDB's system-variable reference, `max_allowed_packet`, default `67108864`.
+ *  · **innodb** — 16 MiB (16 777 216): the smaller of the two documented defaults among the servers behind this word — MariaDB
+ *    16 MiB (its server-system-variables reference, `max_allowed_packet`, default `16777216`) and MySQL 8.0 64 MiB (its
+ *    server-system-variables reference, default `67108864`; 5.7 and before shipped 4 MiB, outside the supported set). A landing above
+ *    the true wall lets through a write the server refuses; below it only refuses early, so the smaller one is the landing.
+ */
+export declare const PACKET_CAP_UNREAD_LANDING_BYTES: {
+    readonly tidb: 67108864;
+    readonly innodb: 16777216;
+};
+/** 一份写入要装进的两堵墙 —— {@link SqlEngineFacts} 里的那两位(`null` 恒且只表示「这堵墙不存在」)。 */
+export type SqlWalls = Pick<SqlEngineFacts, "maxRowBytes" | "maxPacketBytes">;
+/**
+ * 一个墙数字从哪来(上 wire:413 拒体的 `wallSource`)—— **只看「这个数是不是库自己报的」**:
+ *  · `reported` = 库报的:引擎在连接初始化时读到的(或按构造没有这堵墙:没有 SQL 后端、PostgreSQL、InnoDB 的行墙);
+ *  · `assumed` = 不是库报的、是受支持引擎里最保守的缺省顶上的:引擎事实还没建立(连是哪个引擎都不知道,{@link SQL_FACTS_ABSENT_WALLS}),
+ *    或事实在场但这一堵墙读失败、退回了文档缺省({@link SqlEngineFacts.wallSources} 逐墙记着,登记过的 fail-open)。
+ */
+export type SqlWallSource = "reported" | "assumed";
+/** 两堵墙各自的出处(与 {@link SqlWalls} 同键):事实里一处记录,判官 {@link sqlWallsOf} 原样带出。 */
+export type SqlWallSources = {
+    readonly [K in keyof SqlWalls]: SqlWallSource;
+};
+/** {@link sqlWallsOf} 的读数:两堵墙 + 它们各自从哪来(逐墙:一堵读到、另一堵退缺省时,拒哪一堵就报哪一堵的出处)。 */
+export interface SqlWallsReading extends SqlWalls {
+    readonly sources: SqlWallSources;
 }
+/**
+ * 一只 SQL 池的**引擎读口**:方言(SQL 文本轴,装配事实,恒在)+ 此刻的引擎事实(`null` = 没建立)。墙的方言只从这里来 —— 与事实同出一只驱动
+ * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobBackend`)各读本池的这一只。
+ */
+export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
+/**
+ * MySQL 协议方言上**事实缺席**时的墙(池上还没建立过,或最近一次连接初始化被拒:`SqlDriver.facts === null`)。这时连引擎是哪一个都不知道,
+ * 每堵墙各取受支持引擎里最矮的一格:行墙 = TiDB 自己的缺省(InnoDB 没有行墙,保守取有墙的那一个),包墙 = 各引擎族文档缺省里最小的那个
+ * ({@link PACKET_CAP_UNREAD_LANDING_BYTES})—— 没读到事实时的墙不会比读到任何一个缺省事实时的墙更松。它们是**假定**的墙(两堵的出处都是 `assumed`),
+ * 拒句不能把它们说成库报的墙。
+ */
+export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
+/**
+ * 🔴 **此刻一份写入要装进的墙 —— 唯一判官**。两个读者同调它、不各读 `facts`:提交受理口(`http/request-guards.ts` `refuseSubmitBody`)与 SQL 快照 blob 的缺省帽
+ * (`plugins/blob-backend.ts` `sqlBlobCapBytes`,店的写前帽与 `PUT /sync/blobs` 的前置 413 都经它)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出一只驱动),一种读法:
+ *  · 读口缺席 = 没有 SQL 后端 ⇒ 没有墙(「忘了给」读不成这一臂:后端交出了 SQL 池而没给读口 ⇒ `createHttpServer` 起服拒,见 `ServiceDeps.sqlEngine`);
+ *  · 事实在场 ⇒ 事实里的两位,出处逐墙取事实里记的那一份({@link SqlEngineFacts.wallSources}:读到的 `reported`,读失败退文档缺省的 `assumed`);
+ *  · 事实缺席(`null`)⇒ 按读口的方言:PG 没有墙(扩展协议没有这两堵墙 —— 方言事实,不随引擎事实缺席);MySQL 协议 ⇒ {@link SQL_FACTS_ABSENT_WALLS}(两堵都 `assumed`;
+ *    fail-closed:按最保守的墙,不是「没有墙」)。池拒绝初始化本身已在 {@link establishSession} 里响亮报过。
+ * 「没有 SQL 后端」与「事实还没建立」是两个可区分的值:前者是读口缺席,后者是 `facts === null`。
+ */
+export declare function sqlWallsOf(engine: SqlEngineReading | undefined): SqlWallsReading;
 /**
  * **数据库自己的钟**(毫秒),两方言各一句 —— 本仓这口钟在 SQL 面的**唯一**铸点([ref] A7 / [ref] /
  * 合并复审 R2 把 S-280 的 nonce 店并进来)。

package/dist/plugins/sql-driver.js

@@ -1,4 +1,59 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+export const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6_291_456;
+export const ROW_WALL_ALLOWANCE_BYTES = { json: 64 * 1024, blob: 1024 };
+export const STATEMENT_ALLOWANCE_BYTES = 1024;
+export function rowWallPayloadBytes(maxRowBytes, row) {
+    return Math.max(0, maxRowBytes - ROW_WALL_ALLOWANCE_BYTES[row]);
+}
+export function packetWallStatementBytes(maxPacketBytes) {
+    return Math.max(0, maxPacketBytes - STATEMENT_ALLOWANCE_BYTES);
+}
+export function escapedStatementBytes(text) {
+    let escaped = 0;
+    for (let i = 0; i < text.length; i++) {
+        switch (text.charCodeAt(i)) {
+            case 0:
+            case 8:
+            case 9:
+            case 10:
+            case 13:
+            case 26:
+            case 34:
+            case 39:
+            case 92:
+                escaped++;
+        }
+    }
+    return Buffer.byteLength(text, "utf8") + escaped;
+}
+export const PACKET_CAP_UNREAD_LANDING_BYTES = {
+    tidb: 67_108_864,
+    innodb: 16_777_216,
+};
+const NO_WALLS = Object.freeze({ maxRowBytes: null, maxPacketBytes: null, sources: Object.freeze({ maxRowBytes: "reported", maxPacketBytes: "reported" }) });
+export const SQL_FACTS_ABSENT_WALLS = Object.freeze({
+    maxRowBytes: TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT,
+    maxPacketBytes: Math.min(...Object.values(PACKET_CAP_UNREAD_LANDING_BYTES)),
+    sources: Object.freeze({ maxRowBytes: "assumed", maxPacketBytes: "assumed" }),
+});
+export function sqlWallsOf(engine) {
+    if (engine === undefined)
+        return NO_WALLS;
+    const facts = engine.facts;
+    if (facts !== null)
+        return { maxRowBytes: facts.maxRowBytes, maxPacketBytes: facts.maxPacketBytes, sources: facts.wallSources };
+    switch (engine.dialect) {
+        case "pg":
+            return NO_WALLS;
+        case "tidb":
+            return SQL_FACTS_ABSENT_WALLS;
+        default: {
+            const unhandled = engine.dialect;
+            throw new Error(`sql walls: unknown dialect ${String(unhandled)}`);
+        }
+    }
+}
 export const SQL_DB_NOW_MS = {
     tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)",
     pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint",
@@ -90,7 +145,63 @@ async function initMySqlSession(c) {
     if (isolation !== "REPEATABLE-READ") {
         throw refuseSession(`this session reports isolation "${isolation}" after SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ`);
     }
-    return { engine, version: (await mysqlVar(c, "SELECT VERSION() AS v")) ?? "", isolation, txnMode: engine === "tidb" ? "pessimistic" : null };
+    const version = (await mysqlVar(c, "SELECT VERSION() AS v")) ?? "";
+    const rowWall = engine === "tidb" ? await readTidbEntrySizeLimit(c) : null;
+    const packetWall = await readMaxAllowedPacket(c, engine);
+    return {
+        engine,
+        version,
+        isolation,
+        txnMode: engine === "tidb" ? "pessimistic" : null,
+        maxRowBytes: rowWall === null ? null : rowWall.bytes,
+        maxPacketBytes: packetWall.bytes,
+        wallSources: { maxRowBytes: rowWall === null ? "reported" : rowWall.source, maxPacketBytes: packetWall.source },
+    };
+}
+function positiveIntOf(v) {
+    const n = typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v.trim()) ? Number(v.trim()) : Number.NaN;
+    return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+async function readTidbEntrySizeLimit(c) {
+    const unread = [];
+    try {
+        const v = await mysqlVar(c, "SELECT @@tidb_txn_entry_size_limit AS v");
+        const n = positiveIntOf(v);
+        if (n !== undefined)
+            return { bytes: n, source: "reported" };
+        unread.push(v === null ? "@@tidb_txn_entry_size_limit is unknown (TiDB before 7.6)" : `@@tidb_txn_entry_size_limit=${JSON.stringify(v)} (0 = use the config item)`);
+    }
+    catch (err) {
+        unread.push(`@@tidb_txn_entry_size_limit: ${err.message}`);
+    }
+    try {
+        const r = await mysqlQuery(c, "SHOW CONFIG WHERE type = 'tidb' AND name = 'performance.txn-entry-size-limit'");
+        const values = r.rows.map((row) => positiveIntOf(row.Value ?? row.value)).filter((n) => n !== undefined);
+        if (values.length > 0)
+            return { bytes: Math.min(...values), source: "reported" };
+        unread.push(`SHOW CONFIG returned no readable performance.txn-entry-size-limit (${r.rows.length} row(s))`);
+    }
+    catch (err) {
+        unread.push(`SHOW CONFIG: ${err.message}`);
+    }
+    recordFailOpen("server.sql.tidb-row-cap-unread", `assumed=${TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT} ${unread.join("; ")}`);
+    return { bytes: TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT, source: "assumed" };
+}
+async function readMaxAllowedPacket(c, engine) {
+    const landing = PACKET_CAP_UNREAD_LANDING_BYTES[engine];
+    let unread;
+    try {
+        const v = await mysqlVar(c, "SELECT @@max_allowed_packet AS v");
+        const n = positiveIntOf(v);
+        if (n !== undefined)
+            return { bytes: n, source: "reported" };
+        unread = v === null ? "@@max_allowed_packet is unknown" : `@@max_allowed_packet=${JSON.stringify(v)} (not a positive integer)`;
+    }
+    catch (err) {
+        unread = `@@max_allowed_packet: ${err.message}`;
+    }
+    recordFailOpen("server.sql.packet-cap-unread", `assumed=${landing} engine=${engine} ${unread}`);
+    return { bytes: landing, source: "assumed" };
 }
 export function mysqlDriver(pool) {
     const session = poolSession(pool);
@@ -130,6 +241,9 @@ async function initPgSession(c) {
         version: String(ver.rows[0]?.server_version ?? ""),
         isolation,
         txnMode: null,
+        maxRowBytes: null,
+        maxPacketBytes: null,
+        wallSources: { maxRowBytes: "reported", maxPacketBytes: "reported" },
     };
 }
 export function pgDriver(pool) {

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

@@ -20,6 +20,9 @@
  * 于是一次 dup 变成一个裸驱动对象漏给调用方。`Reflect.get` 与属性访问一样走原型链,写成 `Reflect.get`
  * 是把"必须走原型链"这件事写在码面上(收编前唯一的硬化形 `shared-memory-store-sql.ts` 即此形)。
  *
+ * 例外只有一只**类**:{@link StoreRowTooLargeError} —— 「一行装不下」这条判据的带码产物,与它的谓词住在一起
+ * (判据与产物分家 = 两处各写一份「哪些驱动错算这一类」)。
+ *
  * ## 本模块**不**管的事(与 `sql-driver.ts` 头注的分工一致)
  * 「撞的是**哪一个** UNIQUE 键」留在店内:mysql2 把键名写进 `sqlMessage` 文本、node-pg 写进
  * `err.constraint`,而怎么按键名分诊(良性重发 vs 必须重试的竞态)是 store-specific 的判别规则,
@@ -93,4 +96,42 @@ export declare const PG_DEADLOCK_DETECTED_SQLSTATE = "40P01";
  * **MySQL 协议腿**,两方言都认只是为了让店不必自己判引擎。
  */
 export declare function isDeadlockError(dialect: SqlDialect, err: unknown): boolean;
+/** TiDB `ErrEntryTooLarge` (one row's key + value over `txn-entry-size-limit`, 6 MiB by default) — TiDB's own
+ *  errno, which mysql2 carries without a symbolic name. */
+export declare const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;
+/** MySQL/MariaDB `ER_NET_PACKET_TOO_LARGE` (one statement over `max_allowed_packet`). */
+export declare const MYSQL_ER_NET_PACKET_TOO_LARGE_ERRNO = 1153;
+/** MySQL/MariaDB `ER_NET_PACKET_TOO_LARGE`'s symbolic code (mysql2 `code`). */
+export declare const MYSQL_ER_NET_PACKET_TOO_LARGE_CODE = "ER_NET_PACKET_TOO_LARGE";
+/** PostgreSQL `program_limit_exceeded` — a value or row over one of the engine's hard size limits (e.g. a `jsonb`
+ *  value over 255 MiB, an index row over its page budget). */
+export declare const PG_PROGRAM_LIMIT_EXCEEDED_SQLSTATE = "54000";
+/**
+ * 「一行装不下」是被哪一堵墙拒的(闭集;加一堵 ⇒ 读它的 switch 编译红)—— 出路随墙不同,所以墙是这类拒的一位事实:
+ *  · `row` —— TiDB 的单行墙(`txn-entry-size-limit`,errno 8025;出路:抬它);
+ *  · `statement` —— MySQL 协议的语句墙(`max_allowed_packet`,errno 1153 / `ER_NET_PACKET_TOO_LARGE`;InnoDB 与 TiDB 都有;出路:抬它);
+ *  · `value` —— PostgreSQL 的硬上限(SQLSTATE `54000`,如一只 `jsonb` 值超 255 MiB;没有可调的墙,出路只有缩小)。
+ */
+export type RowTooLargeWall = "row" | "statement" | "value";
+/**
+ * 「这个写**是**被引擎以『一行装不下』拒的吗、被哪堵墙」—— 单一判据(与本文件其余谓词同一条 single-semantic-multi-site-drift 纪律)。
+ * MySQL 协议两条墙都认 —— 两条墙对**一条单行 INSERT** 说的是同一件事(这一行写不进),出路不同;PG 认 `54000`。认不出的一律 `undefined`(原始错误原样上抛)。
+ */
+export declare function rowTooLargeWallOf(dialect: SqlDialect, err: unknown): RowTooLargeWall | undefined;
+/**
+ * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
+ * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。
+ * `row` = 哪一张表的哪一格、为谁写(进句子与运维日志);`wall` = 拒它的那堵墙({@link rowTooLargeWallOf} 的读数;提交腿按它选 413 的出路);
+ * `dbMessage` = 引擎自己的那句(TiDB 的句子带着上限与这一行的实际字节数),截到 200 字符。
+ * 提交腿把它答成 413 `request.payload_too_large`(`http/submit-ctx.ts`);停驻那一拍它经引擎的错误座落进运维日志。
+ */
+export declare class StoreRowTooLargeError extends Error {
+    readonly row: string;
+    readonly wall: RowTooLargeWall;
+    readonly code: "store.row_too_large";
+    readonly dbMessage: string;
+    constructor(row: string, cause: unknown, wall: RowTooLargeWall);
+}
+/** 店写口的翻译:{@link rowTooLargeWallOf} 认得出 ⇒ {@link StoreRowTooLargeError}(带那堵墙);其余原样交回(调用方 `throw` 它)。 */
+export declare function rowTooLargeOrSelf(dialect: SqlDialect, err: unknown, row: string): unknown;
 //# sourceMappingURL=sql-errors.d.ts.map

package/dist/plugins/sql-errors.js

@@ -45,4 +45,40 @@ export function isDeadlockError(dialect, err) {
         return keyOf(err, "code") === PG_DEADLOCK_DETECTED_SQLSTATE;
     return keyOf(err, "errno") === MYSQL_ER_LOCK_DEADLOCK_ERRNO || keyOf(err, "code") === MYSQL_ER_LOCK_DEADLOCK_CODE;
 }
+export const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;
+export const MYSQL_ER_NET_PACKET_TOO_LARGE_ERRNO = 1153;
+export const MYSQL_ER_NET_PACKET_TOO_LARGE_CODE = "ER_NET_PACKET_TOO_LARGE";
+export const PG_PROGRAM_LIMIT_EXCEEDED_SQLSTATE = "54000";
+export function rowTooLargeWallOf(dialect, err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    if (dialect === "pg")
+        return keyOf(err, "code") === PG_PROGRAM_LIMIT_EXCEEDED_SQLSTATE ? "value" : undefined;
+    const errno = keyOf(err, "errno");
+    if (errno === TIDB_ER_ENTRY_TOO_LARGE_ERRNO)
+        return "row";
+    if (errno === MYSQL_ER_NET_PACKET_TOO_LARGE_ERRNO || keyOf(err, "code") === MYSQL_ER_NET_PACKET_TOO_LARGE_CODE)
+        return "statement";
+    return undefined;
+}
+export class StoreRowTooLargeError extends Error {
+    row;
+    wall;
+    code = "store.row_too_large";
+    dbMessage;
+    constructor(row, cause, wall) {
+        const dbMessage = (cause instanceof Error ? cause.message : String(cause)).replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 200);
+        super(`${row} was refused by the database: the row is larger than the database stores in one row (${dbMessage}). ` +
+            "Shrink what the request carries inline (images / userAttachments), or raise the database's single-row limit " +
+            "(TiDB: performance.txn-entry-size-limit, or the tidb_txn_entry_size_limit variable on TiDB 7.6+; MySQL / MariaDB: max_allowed_packet)");
+        this.row = row;
+        this.wall = wall;
+        this.name = "StoreRowTooLargeError";
+        this.dbMessage = dbMessage;
+    }
+}
+export function rowTooLargeOrSelf(dialect, err, row) {
+    const wall = rowTooLargeWallOf(dialect, err);
+    return wall !== undefined ? new StoreRowTooLargeError(row, err, wall) : err;
+}
 //# sourceMappingURL=sql-errors.js.map

package/dist/plugins/store-backend.js

@@ -12,7 +12,8 @@ import { FileRunStore } from "./file-run-store.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
-import { NO_SQL_MIGRATIONS, assertRetiredSchemaAbsentOnPool, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { NO_SQL_MIGRATIONS, runSqlOneTimeMigrations } from "./one-time-migrations.js";
+import { assertRetiredSchemaAbsentOnPool } from "./schema-consistency.js";
 import { LocalSessionStore, createLocalSessionRepo } from "./local-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";

package/dist/plugins/tidb-session-storage.d.ts

@@ -1,4 +1,4 @@
-import { BaseSessionStorage, type PromptEpochDescriptor, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { BaseSessionStorage, type SessionMetadata, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 export declare const SESSION_EVENT_LATEST_BY_TYPE_SQL: {
     readonly floor: `SELECT /*+ USE_INDEX(session_event, idx_session_event_type) */ ${string} FROM session_event WHERE session_id = ? AND type = 'compaction' ORDER BY seq DESC LIMIT 1`;
@@ -24,17 +24,13 @@ export declare class TiDBSessionStorage extends BaseSessionStorage {
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
     /**
-     * [ref] S3 [ref] pull seam — `SessionStorage.getEpochAnchor?()`: the nearest epoch carrier BELOW the
-     * bounded-wake floor. core's `Session.getPromptEpoch()` (≥1.305) calls this only when the in-window
-     * branch walk finds no carrier — i.e. a rewind/resumeAt cut inside the kept tail, where the compaction
-     * restatement is a DESCENDANT of the cut and the root pin sits under the floor. Semantics per core's
-     * ruling: highest-seq valid carrier below the floor (not an ancestor-chain walk — fallback of last
-     * resort); malformed rows are skipped (#13: fall back to the older valid pin — the write gate refuses
-     * malformed carriers, so these only exist via out-of-band writes); none ⇒ undefined = a genuine
-     * pre-epoch session (core mints legacy_migration, the correct meaning). core re-normalizes whatever we
-     * return, so this stays honest even if the two sides ever disagree on strictness.
+     * [ref] S3 [ref] pull seam — `SessionStorage.getEpochAnchor?()`: the nearest prompt-epoch carrier BELOW the
+     * bounded-wake floor, AS STORED (engine 7.52.0: `Promise<unknown>`; the engine reads the record, a retired shape
+     * included). The engine's `Session.getPromptEpoch()` asks for it only when the in-window branch walk finds no carrier
+     * (a rewind/resumeAt cut inside the kept tail; compactions without a restatement). The one reading of both SQL twins
+     * is {@link scanEpochAnchor}; this backend supplies its page query (keyset-paged to exhaustion).
      */
-    getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
+    getEpochAnchor(): Promise<unknown>;
     /**
      * Rebuild a session from its event log (= wake). Returns null if the session does not exist.
      *

package/dist/plugins/tidb-session-storage.js

@@ -1,9 +1,10 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-import { BaseSessionStorage, SessionError, leafIdAfterEntry, normalizePromptEpoch, } from "@sema-agent/core";
+import { BaseSessionStorage, SessionError, leafIdAfterEntry, } from "@sema-agent/core";
 import { toIso } from "./sql-row-helpers.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { PLACEMENT_SELECT_COLUMNS, placementFromRow } from "./session-placement.js";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
+import { scanEpochAnchor } from "./session-epoch-anchor.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { incarnationFromCell } from "../session-incarnation.js";
 const SESSION_EVENT_BY_TYPE_HINT = "/*+ USE_INDEX(session_event, idx_session_event_type) */";
@@ -23,21 +24,10 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        if (this.floorSeq <= 0)
-            return undefined;
-        let cursor = this.floorSeq;
-        for (;;) {
-            const [rows] = await this.pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.epochAnchor, [this.sessionId, cursor]);
-            if (rows.length === 0)
-                return undefined;
-            for (const r of rows) {
-                const e = decodeSessionEventPayload(r.payload, this.sessionId, r.seq);
-                const d = e.type === "prompt_epoch" ? normalizePromptEpoch(e) : normalizePromptEpoch(e.details?.promptEpoch);
-                if (d)
-                    return d;
-            }
-            cursor = Number(rows[rows.length - 1].seq);
-        }
+        return scanEpochAnchor(this.sessionId, this.floorSeq, async (beforeSeq) => {
+            const [rows] = await this.pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.epochAnchor, [this.sessionId, beforeSeq]);
+            return rows.map((r) => ({ seq: r.seq, payload: r.payload }));
+        });
     }
     static async wake(pool, sessionId) {
         const [metaRows] = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);

package/dist/plugins/tidb-session-store.js

@@ -334,7 +334,7 @@ export class TiDBSessionStore {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(placedRows[0] === undefined ? undefined : { owner: placedRows[0].owner, incarnation: placedRows[0].incarnation }, owner));
+            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRows[0] === undefined ? undefined : { owner: placedRows[0].owner, incarnation: placedRows[0].incarnation }, owner));
             await conn.commit();
         }
         catch (err) {

package/dist/prompts-domain-validate.d.ts

@@ -1,66 +1,22 @@
-import { type PromptTextDeclaration, type PublishedPromptArtifactEnvelope } from "@sema-agent/core";
-/** [ref]⓪ 下发形(remote effective 的 additive key,JSON verbatim 面——不经 registry-core parse,所以
- *  cli 补位前 center 发的 `contentHash` 也原样到达)。 */
-export interface EffectiveCenterPrompts {
-    /** `center:<contentDigest 前 12>` — 纯内容寻址(同内容重发布=同 packId,epoch 不误重 pin)。 */
-    packId: string;
-    /** canonical JSON 全量 sha256(非盐化,operator 对账位 [ref]②)。 */
-    contentDigest: string;
-    /** covering 已在 center 走完的基线终形(层信息不下发,worker 零解析义务)。 */
-    sections: PromptTextDeclaration[];
-    /** per-scenario 完整重算终形(整包替换基线,非增量);无键=用基线。 */
-    scenarioOverrides?: Record<string, PromptTextDeclaration[]>;
-}
 /**
- * 结构判形(防炸底线,非语义复检)。`ok:false` 时调用方拒绝采用该候选的 prompts 面并 warn——绝不让
- * 一个坏 pack 把每个任务的 prepare 炸掉。校验与 core assemble 的 THROW 条件同形(id 规范/长度/core/
- * 保留、slot 闭集)+ 下发信封两键形;`contentHash` 只查形(值的校验归 core 1.315,错值 core 丢弃+warn)。
+ * prompts 域候选门 —— 中心提示层的**唯一判官**(中立叶子:只依赖 `@sema-agent/core` 与契约包 `@sema-agent/settings-schema`,
+ * 不依赖 capabilities / config 任何东西;候选判官 `web-admin-client/candidate-gate.ts` 是它唯一的调用点,LKG 读回经同一只候选判官)。
+ *
+ * 律:中心层只有一种 wire 形 —— `{ schemaVersion: 2, artifact }`(契约包 `EffectivePromptsWire`;artifact 是引擎当期 schema 的发布形)。
+ * 判法两步一线:先过契约包的 wire 形(外壳、键闭集、结构与上界;旧两轴 / v2 artifact 的拒句是契约包的原句),再交引擎
+ * `verifyPromptArtifact`(语义:每条 overlay 在中心类的档权内、锁定文本、requires 复算、同目标冲突、digest —— 拒句是引擎的原句)。
+ * 本模块不写任何形判、不铸任何句子、不归一任何别的形:中心不带 prompts 键 = 不下发中心层(调用方据此撤下);带了就必须是这一种形,
+ * 否则整份候选拒(一个域都不应用)。
  */
-export declare function validateCenterPrompts(raw: unknown): {
-    ok: true;
-    value: EffectiveCenterPrompts;
+import { type PublishedPromptArtifact } from "@sema-agent/core";
+/** 判官的结论:收下 ⇒ 引擎 verify 过的发布形 artifact(调用方交给引擎的中心源采用);拒 ⇒ 拒因(契约包 / 引擎的原句)。 */
+export type PromptsWireVerdict = {
+    readonly ok: true;
+    readonly artifact: PublishedPromptArtifact;
 } | {
-    ok: false;
-    error: string;
+    readonly ok: false;
+    readonly error: string;
 };
-/** core 引擎版本(verifyPromptArtifact 的 compatibleCore range 输入)——经 exports map 解析包根读
- *  package.json(`require('@sema-agent/core/package.json')` 被 exports 封死,ERR_PACKAGE_PATH_NOT_EXPORTED
- *  第一手教训)。解析失败回 "0.0.0" = range-gated artifact 被诚实拒(fail-closed 响,绝不静默采用)。 */
-export declare const CORE_ENGINE_VERSION: string;
-/** validatePromptsDomain 的归一产物:两轴的已判形面 + 变更检测身份(adopt 去重键,跨轴稳定)。 */
-export interface PromptsDomainFaces {
-    /** A 形(declaration 轴)——centerPromptProvider 继续消费(现行链路零改动)。 */
-    declarations?: EffectiveCenterPrompts;
-    /** B 形(catalog 轴)——core S1 verify 已过(digest 复算/上限/range 全管线);server 不解释内容,
-     *  原样交 core artifact 仓(e/b 班车接线位)。 */
-    catalog?: PublishedPromptArtifactEnvelope;
-    /** 采用去重键:两轴 digest 拼接(轴缺席记 "-")。 */
-    identity: string;
-    /** 观测面([ref]a §3:`center_prompts_adopted` 增 axes,看两轴共存窗)。 */
-    axes: Array<"declarations" | "catalog">;
-}
-/**
- * prompts 域候选门 v2(validateCenterPrompts 的双轴升级;整拒语义不变=任一在场轴坏形 ⇒ 整个 prompts
- * 面拒绝采用,LKG/内置继续服务)。唯一认可形=`{schemaVersion:1, declarations?, catalog?}`
- * (registry-core `EffectivePromptsWire`)至少一轴。[ref]B-9(5.0.0):legacy 平铺兼容窗到期删——
- * 0.13.0 起 EffectivePromptsWire 首字段是 `schemaVersion: z.ZodLiteral<1>`,与 server 共用 ^0.13.0 的
- * 合规 center 不可能再发平铺;非合规体=响亮拒绝(整拒落 LKG/内置),不再静默吸收。
- * catalog 轴的语义权威=core `verifyPromptArtifact`(形/digest 逐位复算/ARTIFACT_LIMITS/compatibleCore
- * range 全在 core 一处——[ref]③ a 解,上限单真源永不漂)。
- */
-export declare function validatePromptsDomain(raw: unknown): {
-    ok: true;
-    value: PromptsDomainFaces;
-} | {
-    ok: false;
-    error: string;
-};
-/** [ref](docs/R100-PROMPTS-LANE-FIX.md §V2-B)worker 腿 effective 上 `prompts` 键的**形-肯定**判别:
- *  消费形特征(v2 `schemaVersion` 键,或 legacy 三键 packId/contentDigest/sections)⇒ 原样返回交
- *  {@link validatePromptsDomain}(收或拒,方向不变);其余=center 存储原文(global lane [ref]①e 下发
- *  存储形是合法输入)——catalog 在场则投影 `{schemaVersion:1, catalog}`(config-provider 本地腿先例),
- *  否则视为「center 未发」⇒ undefined。null=有意 cleared 语义([ref] 前 null 走拒,方向为宽是设计变更,
- *  留痕于设计档)。垃圾标量原样返回(fail-loud 归 validate)。
- *  属主放本中立叶:config-lkg 与 boot/refresh 同吃,capabilities 层会重开 S6 刚消的反向依赖边。 */
-export declare function centerPromptsFromEffective(eff: unknown): unknown | undefined;
+/** 一份候选 `prompts` 键的值(在场才调)→ 判官结论。 */
+export declare function judgePromptsWire(raw: unknown): PromptsWireVerdict;
 //# sourceMappingURL=prompts-domain-validate.d.ts.map