@sema-agent/server 7.149.0 → 7.151.0

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

@@ -2,7 +2,10 @@ import { uuidv7 } from "@sema-agent/core";
 import { escapeLike } from "./sql-escape.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { pgSafeJsonStringify } from "./pg-safe-json.js";
-import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement, readDeletingTokenOn } from "./session-ext-table.js";
+import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, SESSION_KIND_COLUMN, ensureSessionExtRowStatement, readDeletingTokenOn } from "./session-ext-table.js";
+import { sessionKindFromCell } from "../session-kind.js";
+import { sessionLiveReferenceSql } from "./retention-sql.js";
+import { lockHoldSentinel } from "./retention-lane-store-sql.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { createSqlExecutionPlacementSeat, markMirrorStatement, readCellOn, readClaimOn, writeCellOn } from "./execution-placement-sql.js";
 import { judgeSessionWrite, sessionWriteTouchesCell } from "../execution-placement.js";
@@ -10,9 +13,10 @@ import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSour
 import { forkLineageOfRow, headFromRow, incarnationFromCell } from "../session-incarnation.js";
 import { CROSS_PROCESS_TAKEOVER_AFTER_MS, deletionTokenMintedAt } from "../session-deletion.js";
 import { sessionRowTagKey } from "../session-row.js";
-import { writeSessionRowCellsSql } from "./session-row-sql.js";
+import { lockSessionRootOn, withLandedRow, writeSessionRowCellsSql } from "./session-row-sql.js";
 import { bumpClientWritesOn, createSqlWithdrawJudge } from "./session-withdraw-sql.js";
 import { WITHDRAWABLE_ENTRY_TYPES } from "./session-birth.js";
+import { sealStoreClass, sealStoreObject } from "./store-boundary.js";
 const RUN_PREVIEW_PRESENT = "CHAR_LENGTH(objective_preview) > 0";
 function binder(dialect) {
     const values = [];
@@ -57,17 +61,30 @@ export function createSqlSessionWriteHooks(db) {
                 return { owner: row.owner === null || row.owner === undefined ? null : String(row.owner), forkKey: row.fork_key === null || row.fork_key === undefined ? null : String(row.fork_key) };
             },
         },
+        birth: {
+            async record(txn, born) {
+                const ensure = ensureSessionExtRowStatement(dialect, born.rootSessionId);
+                await txn.query(ensure.text, [...ensure.values]);
+                const b = binder(dialect);
+                const res = await txn.query(`UPDATE ${SESSION_EXT_TABLE} SET ${SESSION_KIND_COLUMN.name} = ${b.p(born.kind)} WHERE session_id = ${b.p(born.rootSessionId)}`, b.values);
+                if (res.affected !== 1)
+                    throw new Error(`registration of session ${born.rootSessionId}: the session kind write matched ${res.affected} row(s) of a row this transaction just created — engine/driver anomaly, refusing to guess`);
+            },
+        },
     };
 }
+export function sessionKindSql(view, p) {
+    return view === undefined ? `se.${SESSION_KIND_COLUMN.name} IS NULL` : `se.${SESSION_KIND_COLUMN.name} = ${p(view)}`;
+}
+const IDLE_SESSION_READ = { deadlineMs: 2_000 };
 const BASELINE_STATEMENT = { deadlineMs: BASELINE_IO_DEADLINE_MS };
 async function withLockedSessionExt(db, sessionId, lock, write) {
     const conn = await db.connect();
     const query = (sql, params) => conn.query(sql, params, lock.statement);
     try {
         await conn.begin();
-        const b = binder(db.dialect);
-        const locked = await query(`SELECT session_id FROM session_meta WHERE session_id = ${b.p(sessionId)}${lock.where === undefined ? "" : ` AND ${lock.where(b.p)}`} FOR UPDATE`, b.values);
-        if (locked.rows.length === 0) {
+        const root = await lockSessionRootOn(async (text, values) => (await query(text, [...values])).rows, db.dialect, sessionId);
+        if (root === undefined || (lock.incarnation !== undefined && root.incarnation !== lock.incarnation)) {
             await conn.rollback();
             return false;
         }
@@ -90,6 +107,10 @@ const listedLineageOf = (sessionId, forkedFrom) => {
     const lineage = forkLineageOfRow(sessionId, forkedFrom, undefined);
     return lineage.forkedFrom !== undefined ? { forkedFrom: lineage.forkedFrom } : {};
 };
+const listedKindOf = (sessionId, cell) => {
+    const kind = sessionKindFromCell(sessionId, cell);
+    return kind !== undefined ? { sessionKind: kind } : {};
+};
 function holderMayBeAlive(holder, token) {
     switch (holder) {
         case "running":
@@ -123,8 +144,15 @@ export class SqlSessionStore {
     register(sessionId, owner) {
         return this.seat.register(sessionId, owner);
     }
-    registerWithReceipt(sessionId, owner) {
-        return this.seat.registerWithReceipt(sessionId, owner);
+    registerWithReceipt(sessionId, owner, kind) {
+        return this.seat.registerWithReceipt(sessionId, owner, kind);
+    }
+    async sessionKindOf(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT sm.incarnation, se.${SESSION_KIND_COLUMN.name} AS session_kind FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        if (row === undefined)
+            return undefined;
+        return { incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"), kind: sessionKindFromCell(sessionId, row.session_kind) };
     }
     withdrawBirth(birth, ownTaskId) {
         const cond = {
@@ -190,7 +218,7 @@ export class SqlSessionStore {
     sweepStagingSessions() {
         return this.seat.sweepStagingSessions();
     }
-    sessionDeletion = {
+    sessionDeletion = sealStoreObject({
         fence: (sessionId, owner, opts) => this.fenceDeletion(sessionId, owner, opts),
         holds: async (sessionId, token) => {
             const b = binder(this.db.dialect);
@@ -201,21 +229,25 @@ export class SqlSessionStore {
             const rows = (await this.db.query(`SELECT sm.session_id, sm.owner, se.${DELETING_TOKEN_COLUMN.name} AS token FROM session_meta sm JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE se.${DELETING_TOKEN_COLUMN.name} IS NOT NULL ORDER BY sm.session_id`, [])).rows;
             return rows.map((r) => ({ sessionId: String(r.session_id), owner: r.owner ?? null, token: String(r.token) }));
         },
-    };
+    }, "sql-session-deletion", { fence: "exit", holds: "exit", pending: "exit" });
     async fenceDeletion(sessionId, owner, opts) {
         const dialect = this.db.dialect;
         const conn = await this.db.connect();
         try {
             await conn.begin();
             const rows = async (sql, values) => (await conn.query(sql, [...values])).rows;
-            const root = (await rows(`SELECT owner, incarnation FROM session_meta WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+            if (opts.ageOut !== undefined && (await lockHoldSentinel(conn, dialect, owner ?? ""))) {
+                await conn.rollback();
+                return undefined;
+            }
+            const root = await lockSessionRootOn(rows, dialect, sessionId);
             if (root === undefined || (root.owner ?? null) !== owner) {
                 await conn.rollback();
                 return undefined;
             }
             const held = await readDeletingTokenOn(rows, dialect, sessionId);
             if (held === null) {
-                if (opts.expect !== undefined) {
+                if (opts.expect !== undefined || (opts.ageOut !== undefined && !(await this.ageOutHoldsOn(rows, sessionId, root, opts.ageOut)))) {
                     await conn.rollback();
                     return undefined;
                 }
@@ -251,6 +283,45 @@ export class SqlSessionStore {
             conn.release();
         }
     }
+    async ageOutHoldsOn(rows, sessionId, root, ageOut) {
+        if (incarnationFromCell(sessionId, root.incarnation, "absent") !== ageOut.incarnation)
+            return false;
+        const lastActivity = root.updated_at instanceof Date ? root.updated_at : new Date(String(root.updated_at));
+        if (!(lastActivity.getTime() < ageOut.idleBefore.getTime()))
+            return false;
+        const b = binder(this.db.dialect);
+        const cell = (await rows(`SELECT ${SESSION_KIND_COLUMN.name} AS session_kind FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)} FOR UPDATE`, b.values))[0];
+        if (sessionKindFromCell(sessionId, cell?.session_kind) !== ageOut.kind)
+            return false;
+        const live = binder(this.db.dialect);
+        return (await rows(`SELECT 1 AS live FROM session_meta sm WHERE sm.session_id = ${live.p(sessionId)} AND ${sessionLiveReferenceSql(this.db.dialect)} FOR UPDATE`, live.values)).length === 0;
+    }
+    async listIdleOfKind(kind, idleBefore, page) {
+        const b = binder(this.db.dialect);
+        const where = [sessionKindSql(kind, b.p), `sm.updated_at < ${b.p(idleBefore)}`, `NOT ${sessionLiveReferenceSql(this.db.dialect)}`];
+        if (page.after !== undefined) {
+            const at = new Date(page.after.lastActivityAt);
+            where.push(`(sm.updated_at > ${b.p(at)} OR (sm.updated_at = ${b.p(at)} AND sm.session_id > ${b.p(page.after.sessionId)}))`);
+        }
+        const sql = `SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at FROM session_meta sm JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            `WHERE ${where.join(" AND ")} ORDER BY sm.updated_at ASC, sm.session_id ASC LIMIT ${b.p(page.limit)}`;
+        const conn = await this.db.connect();
+        try {
+            const rows = (await conn.query(sql, b.values, IDLE_SESSION_READ)).rows;
+            return rows.map((r) => {
+                const sessionId = String(r.session_id);
+                return {
+                    sessionId,
+                    owner: r.owner ?? null,
+                    incarnation: incarnationFromCell(sessionId, r.incarnation, "absent"),
+                    lastActivityAt: r.updated_at instanceof Date ? r.updated_at.toISOString() : new Date(String(r.updated_at)).toISOString(),
+                };
+            });
+        }
+        finally {
+            conn.release();
+        }
+    }
     get size() {
         return this.seat.size;
     }
@@ -265,7 +336,7 @@ export class SqlSessionStore {
         return this.selectListRows({
             limit: opts.limit,
             where: (p) => {
-                const where = ["sm.placement_kind IS NULL"];
+                const where = ["sm.placement_kind IS NULL", sessionKindSql(opts.sessionKind, p)];
                 if (opts.owner !== undefined)
                     where.push(opts.includeUnowned ? `(sm.owner = ${p(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${p(opts.owner)}`);
                 if (opts.q) {
@@ -311,7 +382,7 @@ export class SqlSessionStore {
                 runAnd() +
                 "  ) pr WHERE rn = 1) pv ON pv.session_id = sm.session_id ";
         const where = [...q.where(b.p), `se.${DELETING_TOKEN_COLUMN.name} IS NULL`];
-        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.forked_from, se.title, se.pinned, " +
+        const sql = `SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.forked_from, se.title, se.pinned, se.${SESSION_KIND_COLUMN.name} AS session_kind, ` +
             "  COALESCE(r.run_count, 0) AS run_count, pv.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
             "FROM session_meta sm " +
             `LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
@@ -342,6 +413,7 @@ export class SqlSessionStore {
                 pinned,
                 ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
                 ...listedLineageOf(sessionId, r.forked_from),
+                ...listedKindOf(sessionId, r.session_kind),
             };
             return { row, occupant: { owner, incarnation } };
         });
@@ -356,11 +428,12 @@ export class SqlSessionStore {
             return "none";
         return row.title === null || row.title === undefined ? "untitled" : "titled";
     }
-    async setTitleIfNull(sessionId, title) {
-        return withLockedSessionExt(this.db, sessionId, {}, async (query) => {
+    async setTitleIfNull(sessionId, title, landed) {
+        const out = await withLandedRow(this.db, sessionId, landed, async (tx) => {
             const b = binder(this.db.dialect);
-            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
+            return (await tx.query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
         });
+        return out.landed && out.value;
     }
     async readInstructionSource(sessionId) {
         const b = binder(this.db.dialect);
@@ -389,10 +462,18 @@ export class SqlSessionStore {
     async recordSessionWorkspace(sessionId, incarnation, workspace) {
         const dialect = this.db.dialect;
         const cell = encodeSessionWorkspaceCell(workspace, dialect === "pg" ? pgSafeJsonStringify : JSON.stringify, sessionId);
-        await withLockedSessionExt(this.db, sessionId, { where: (p) => `incarnation = ${p(incarnation)}` }, async (query) => {
+        await withLockedSessionExt(this.db, sessionId, { incarnation }, async (query) => {
             const b = binder(dialect);
             return (await query(`UPDATE ${SESSION_EXT_TABLE} SET workspace = ${b.p(cell)}${dialect === "pg" ? "::jsonb" : ""} WHERE session_id = ${b.p(sessionId)}`, b.values)).affected > 0;
         });
     }
 }
+sealStoreClass(SqlSessionStore, "sql-session-store", {
+    acquire: "exit", register: "exit", registerWithReceipt: "exit", withdrawBirth: "exit", placementOf: "exit", listPlaced: "exit", headOf: "exit",
+    deletionHeadOf: "exit", touch: "exit", release: "exit", forget: "exit", fork: "exit", forkTo: "exit", exportEntries: "exit", listEntryIds: "exit",
+    exportEntriesStream: "exit", importEntries: "exit", replaceEntries: "exit", beginImportStaging: "exit", readStagedEntries: "exit",
+    sweepStagingSessions: "exit", dispose: "exit", listSessions: "exit", listSessionRows: "exit", sessionSummaryOf: "exit", writeSessionRowCells: "exit",
+    probeTitle: "exit", setTitleIfNull: "exit", readInstructionSource: "exit", recordInstructionSource: "exit", readSessionWorkspace: "exit",
+    recordSessionWorkspace: "exit", sessionKindOf: "exit", listIdleOfKind: "exit",
+});
 //# sourceMappingURL=session-store-sql.js.map

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -118,6 +118,7 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
      * 并发读被写者串起来,而这是会话附着的热路径)。规则少了一条:全店从此只有写方法开事务。
      */
     private readBinding;
+    /** 交给引擎的读器(快照兑现之后才拨库)—— 出店口,造对象处封(读器上的库错同样只带原码 + 稳定句)。 */
     private readerFor;
     /** One keyset window. Always the PAGED shape — a large library must never be materialized per call. */
     private listDocuments;

package/dist/plugins/shared-memory-store-sql.js

@@ -2,6 +2,7 @@ import { writeLogText } from "../observability/logger.js";
 import { isOrgScopeKey, isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { sealStoreClass, sealStoreObject } from "./store-boundary.js";
 const isDupKey = isDupKeyError;
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
@@ -159,10 +160,10 @@ export class SqlSharedMemoryStore {
         };
     }
     readerFor(storeId, scopeKey) {
-        return {
+        return sealStoreObject({
             list: (prefix, opts) => this.listDocuments(storeId, scopeKey, prefix, opts),
             read: (path, opts) => this.readDocument(storeId, scopeKey, path, opts),
-        };
+        }, "sql-shared-memory-reader", { list: "exit", read: "exit" });
     }
     async listDocuments(storeId, scopeKey, prefix, opts) {
         throwIfAborted(opts.signal);
@@ -363,6 +364,9 @@ export class SqlSharedMemoryStore {
         }
     }
 }
+sealStoreClass(SqlSharedMemoryStore, "sql-shared-memory-store", {
+    snapshot: "exit", putScopeState: "exit", putStore: "exit", putDocument: "exit", deleteDocument: "exit", deleteStore: "exit",
+});
 export class TiDBSharedMemoryStore extends SqlSharedMemoryStore {
     constructor(pool, authorizer, opts) {
         super(mysqlDriver(pool), authorizer, opts);

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

@@ -423,7 +423,8 @@ export declare function connectJudged<R>(db: SqlDriver, judge: (facts: SqlEngine
  * (`getConnection` → 守卫租约上执行 → 归还,被守卫销毁的不归还)。语句契约不变:参数原样到连接,结果是 mysql2 的 `[rows, fields]` 元组,`{ sql, timeout }` 对象形
  * 一并支持(原样交给连接);池的其余成员(`end` / `execute` / `on` …)原样转给底池,返回底池自身的方法(`on` 之类)返回本包装体 —— 链式调用不会逃出守卫。
  * 生产池(`createTidbPool`)恒是它;mysql2 自己的 `pool.query` 对只读类错误(1290 / 1792 / 1836)的销毁收在同一张表里({@link isConnectionUnusableError}),不丢。
- * 不覆盖 `pool.execute`(预备语句:今天只有任务附件店一处,语句是小定长行,碰不到语句墙)。
+ * 不覆盖 `pool.execute`(预备语句:今天只有任务附件店一处,语句是小定长行,碰不到语句墙)—— 它与其余原样转给底池的成员一样,只给拒绝打驱动出身记号。
+ * **驱动出身记号**(`error-origin.ts` 的 `driver` 一词)是这只池座的第二件事:借连接、守卫租约上的语句与事务动词、原样转给底池的承诺,它们的拒绝都打记号(只记,不改对象、不记日志、不改控制流)。
  */
 export declare function createCloseAwarePool(pool: MySqlPool): MySqlPool;
 /** MySQL-protocol driver (TiDB / MySQL / MariaDB — `dialect` is the SQL TEXT axis, `facts.engine` the

package/dist/plugins/sql-driver.js

@@ -3,6 +3,8 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
 import { writeLogText } from "../observability/logger.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
+import { markErrorOrigin } from "./error-origin.js";
+import { storeBoundaryFault } from "../terminal.js";
 export class SqlStatementDeadlineExceeded extends Error {
     deadlineMs;
     constructor(deadlineMs) {
@@ -245,7 +247,8 @@ async function initMySqlSession(c) {
             await c.query("SET SESSION tidb_txn_mode = 'pessimistic'");
         }
         catch (err) {
-            throw refuseSession(`this TiDB session is in "${txnMode}" transaction mode and SET SESSION tidb_txn_mode='pessimistic' was rejected (${err.message})`);
+            storeBoundaryFault(err, "sql-driver.initMySqlSession");
+            throw refuseSession(`this TiDB session is in "${txnMode}" transaction mode and SET SESSION tidb_txn_mode='pessimistic' was rejected`);
         }
         txnMode = await mysqlVar(c, "SELECT @@tidb_txn_mode AS v");
         if (txnMode !== "pessimistic") {
@@ -342,6 +345,7 @@ function leaseOf(raw) {
                 return await run();
             }
             catch (err) {
+                markErrorOrigin(err, "driver");
                 if (isConnectionUnusableError(err)) {
                     destroy();
                     BROKEN_LEASES.set(lease, { error: err });
@@ -375,7 +379,9 @@ function leaseOf(raw) {
     return lease;
 }
 export function createCloseAwarePool(pool) {
-    const lend = async () => leaseOf(await pool.getConnection());
+    const lend = async () => leaseOf(await pool.getConnection().catch((err) => {
+        throw markErrorOrigin(err, "driver");
+    }));
     const query = async (...args) => {
         const c = await lend();
         try {
@@ -396,12 +402,21 @@ export function createCloseAwarePool(pool) {
                 return member;
             return (...args) => {
                 const result = member.apply(target, args);
-                return result === target ? wrapper : result;
+                if (result === target)
+                    return wrapper;
+                return isThenable(result)
+                    ? result.then(undefined, (err) => {
+                        throw markErrorOrigin(err, "driver");
+                    })
+                    : result;
             };
         },
     });
     return wrapper;
 }
+function isThenable(v) {
+    return v !== null && (typeof v === "object" || typeof v === "function") && typeof v.then === "function";
+}
 export function mysqlDriver(pool) {
     const session = poolSession(pool);
     return {

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

@@ -109,7 +109,13 @@ export declare function isDeadlockError(dialect: SqlDialect, err: unknown): bool
 /** 引擎仲裁之后整段重来的**唯一**上界(全仓每一条「撞死锁就重来」的腿共用这一个数)。8 = 锁形并发套的并发度:缺行首写的 N 路竞争每轮至多多走一轮([ref] 读数 1 成 7 死锁)。 */
 export declare const DEADLOCK_RETRY_LIMIT = 8;
 /**
- * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError};用尽 / 其它错误原样抛。
+ * 语句源在一只**别人开的**事务里输了仲裁(例:文件历史的 scope 哨兵在锁读那一刻物理消失)—— 它不许自己回滚重开那只事务(段首的锁与判会随之丢掉),
+ * 只抛这一只;{@link retryOnDeadlock} 把它与死锁同读,从事务主人的段首整段重来(落定段、店自己的图事务同一条)。
+ */
+export declare class SqlArbitrationLostError extends Error {
+}
+/**
+ * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError} ∪ {@link SqlArbitrationLostError};用尽 / 其它错误原样抛。
  * `attempt` 必须整段重做语义等价(读-判-写全在里面的一只事务,或一条幂等语句)。`alsoArbitrated`:店自己认的另一种仲裁产物(例:缺行首写撞主键 ——
  * 并发的另一只首写赢了,重读即走更新腿),与死锁同族、同一个上界。锁等待超时不在任何一族里(延迟信号,见 {@link isDeadlockError} 的注):它照抛。
  */
@@ -241,17 +247,16 @@ export declare function isDeploymentFaultError(err: unknown): boolean;
  */
 export declare function databaseAnswerCodesOf(dialect: SqlDialect, err: unknown): string | undefined;
 /**
- * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
- * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。
- * `row` = 哪一张表的哪一格、为谁写(进句子与运维日志);`wall` = 拒它的那堵墙({@link rowTooLargeWallOf} 的读数;提交腿按它选 413 的出路);
- * `dbMessage` = 引擎自己的那句(TiDB 的句子带着上限与这一行的实际字节数),截到 200 字符。
+ * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以驱动错上抛。
+ * `row` = 哪一张表的哪一格、为谁写(进句子);`wall` = 拒它的那堵墙({@link rowTooLargeWallOf} 的读数;提交腿按它选 413 的出路)。
+ * 句子是本仓的固定句,**不带**库的原句(店的出口只带原码 + 稳定句);库的那句(TiDB 的句子带上限与这一行的实际字节数)挂在 `cause` 上 ——
+ * 它出店时由店边界(`terminal.ts` 的 `storeBoundaryFault`:带词法内码的 typed 错原样过,`cause` 链上的驱动错就地换成边界形)记进 `at=store` 那一行、换成边界形。
  * 提交腿把它答成 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` 它)。 */

package/dist/plugins/sql-errors.js

@@ -55,13 +55,15 @@ export function isDeadlockError(dialect, err) {
     return keyOf(err, "errno") === MYSQL_ER_LOCK_DEADLOCK_ERRNO || keyOf(err, "code") === MYSQL_ER_LOCK_DEADLOCK_CODE;
 }
 export const DEADLOCK_RETRY_LIMIT = 8;
+export class SqlArbitrationLostError extends Error {
+}
 export async function retryOnDeadlock(dialect, attempt, alsoArbitrated) {
     for (let tries = 0;; tries++) {
         try {
             return await attempt();
         }
         catch (err) {
-            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || alsoArbitrated?.(err) === true))
+            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || err instanceof SqlArbitrationLostError || alsoArbitrated?.(err) === true))
                 continue;
             throw err;
         }
@@ -214,16 +216,13 @@ 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}). ` +
+        super(`${row} was refused by the database: the row is larger than the database stores in one row. ` +
             "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)");
+            "(TiDB: performance.txn-entry-size-limit, or the tidb_txn_entry_size_limit variable on TiDB 7.6+; MySQL / MariaDB: max_allowed_packet)", { cause });
         this.row = row;
         this.wall = wall;
         this.name = "StoreRowTooLargeError";
-        this.dbMessage = dbMessage;
     }
 }
 export function rowTooLargeOrSelf(dialect, err, row) {

package/dist/plugins/stop-then-start-sentence.d.ts

@@ -2,15 +2,60 @@
  * 「停-迁-起」那一段的**唯一属主**。
  *
  * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
- * 起服时由守卫判 —— 判活窗内(`REAP_RUN_STALE_SEC`,收割器判 run 持有者还活着的同一个窗)库里还有 `running` run 在心跳 ⇒ 拒启、一字节不写。
+ * 起服时由守卫段判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`stop-then-start.ts` 的 `readOlderReplicaEvidence`):
+ * 判活窗内(`REAP_RUN_STALE_SEC`,收割器判 run 持有者还活着的同一个窗)心跳过的 `running` run,持有者没有登记为知道这条迁移(`replica-registration.ts`)。
  * 四只守卫(M40 · M41 · M42 · M51)的拒句和起服列册对账的升级清单**说同一件事**:先停光更早版本的副本、等满判活窗、再起本版。
- * 这件事的句子只在这里写一遍;各守卫只讲「为什么这一条要停」,不各抄一份动作段。
+ * 这件事的句子只在这里写一遍:证据一段({@link olderReplicaEvidenceSentence})与动作一段({@link stopThenStartAction});各守卫只讲「为什么这一条要停」。
+ * 起服准入(`serving-requirement.ts`:库上记着本构建没有的能力 ⇒ 拒启)的拒句同属这一族,也在这里({@link servingRequirementUnmetSentence});
+ * 起服拒句升级清单里「这只库要求本构建没有的能力」一步的句子同在这里({@link unmetRequirementChecklistStep})。
  *
- * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件与列册对账都静态 import 它,不成环)。
+ * 叶子模块:零 import(守卫段、各条的拒句、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
  */
+/** 证据里一只登记过、却没有这条迁移能力的持有者(归因用:点名它是谁)。 */
+export interface OlderReplicaHolder {
+    readonly instanceId: string;
+    readonly releaseLine: string;
+    readonly hostName: string;
+    readonly pid: number;
+    /** 它持有的、判活窗内心跳过的 `running` run 数。 */
+    readonly runs: number;
+}
+/**
+ * 停-迁-起守卫的证据(纯数据):判活窗内心跳过、持有者没有登记为知道 {@link migration} 的 `running` run。
+ * 登记为知道它的持有者的 run 不在这里(它们不是旧形写者);登记只作归因,不判活。
+ */
+export interface OlderReplicaEvidence {
+    readonly migration: string;
+    /** 算进证据的 run 总数(= {@link unregisteredRuns} + 各 {@link registeredWithout} 的 `runs`)。 */
+    readonly liveRuns: number;
+    readonly windowSec: number;
+    /** 全停之后可以再起的最早时刻(ISO;= 最新心跳 + 判活窗;读不出最新心跳 ⇒ 现在 + 窗,上界)。 */
+    readonly restartAfter: string;
+    /** 同一时刻的人读形(带「离现在还有几秒」)。 */
+    readonly after: string;
+    /** 持有者没有登记行(或没有持有者)的 run 数。 */
+    readonly unregisteredRuns: number;
+    /** 登记了而能力名单里没有这条迁移的持有者,逐只点名。 */
+    readonly registeredWithout: readonly OlderReplicaHolder[];
+}
+/** 证据一段(各守卫拒句与 M43 的读数共用;句子不含时刻 —— 时刻在动作段)。 */
+export declare function olderReplicaEvidenceSentence(e: OlderReplicaEvidence): string;
 /**
  * 动作段:停光 → 等窗 → 再起。`after` = 全停之后可以再起的最早时刻(守卫读到的最新心跳 + 判活窗,人读形);
  * 缺席 ⇒ 读不到具体心跳(列册对账的清单:此刻没有守卫在判),只说「等满判活窗」。
  */
 export declare function stopThenStartAction(after?: string): string;
+/** 起服准入里一行本构建没有的要求(`state` = 判读的态,词表外的词读作 `in_force`;`word` = 库里存的原词)。 */
+export interface UnmetServingRequirement {
+    readonly migration: string;
+    readonly state: "in_force";
+    readonly word: string;
+}
+/**
+ * 起服拒句**升级清单**里的那一步(排在 `ALTER` 一步之前;多行,第一行是步骤首句):这只库要求本构建没有的能力 —— 照清单补完语句也不会让本构建能在这里服务。
+ * `unmet` 空 ⇒ 调用方不出这一步。`unreadable` 在 ⇒ 读要求表抛了:照出这一步并如实说没读到(多停一次,不漏停)。
+ */
+export declare function unmetRequirementChecklistStep(unmet: readonly UnmetServingRequirement[], unreadable?: string): string[];
+/** 起服准入的拒句(`reason` 闭集两词;码由调用方交,本模块零 import)。 */
+export declare function servingRequirementUnmetSentence(code: string, reason: "capability_missing" | "table_absent", unmet: readonly UnmetServingRequirement[], absentTables: readonly string[], releaseLine: string): string;
 //# sourceMappingURL=stop-then-start-sentence.d.ts.map

package/dist/plugins/stop-then-start-sentence.js

@@ -1,7 +1,55 @@
+export function olderReplicaEvidenceSentence(e) {
+    const parts = [];
+    if (e.unregisteredRuns > 0)
+        parts.push(`${e.unregisteredRuns} by replicas with no registration on this database (a release that predates replica registration, or a process that skipped the start sequence)`);
+    for (const h of e.registeredWithout)
+        parts.push(`${h.runs} by instance ${h.instanceId} (release ${h.releaseLine}, host ${h.hostName}, pid ${h.pid}), registered without it`);
+    return (`${e.liveRuns} running run(s) on this database heartbeated within the last ${e.windowSec}s (REAP_RUN_STALE_SEC), held by replicas not registered as knowing one-time migration ${e.migration}` +
+        ` (${parts.join("; ")})`);
+}
 export function stopThenStartAction(after) {
     return ("Stop every replica of the earlier version, then start this version (stop, migrate, start — this release cannot be rolled across replicas of both versions). " +
         (after === undefined
             ? "Wait out the heartbeat window (REAP_RUN_STALE_SEC) after the last replica stops, then start this version."
             : `If every replica is already stopped, those are the runs they left behind: start this version again after ${after}`));
 }
+function requirementClause(r) {
+    switch (r.state) {
+        case "in_force":
+            return r.word === "in_force"
+                ? `${r.migration} (in force: a build that has it was admitted on this database and may have changed data for it)`
+                : `${r.migration} (state "${r.word}", which this build does not know — read as in force)`;
+        default: {
+            const unhandled = r.state;
+            throw new Error(`stop-then-start-sentence: unknown requirement state ${String(unhandled)}`);
+        }
+    }
+}
+const rollbackDelete = (migration) => `DELETE FROM serving_requirement WHERE migration_id = '${migration}';`;
+export function unmetRequirementChecklistStep(unmet, unreadable) {
+    if (unreadable !== undefined) {
+        return [`Whether this database requires a capability this build lacks could not be read (${unreadable}); read serving_requirement before going on — a row this build does not have means it must not serve here.`];
+    }
+    return [
+        `This database requires every serving replica to have ${unmet.map(requirementClause).join(", ")}; this build does not, and must not serve on it — the statements below do not make it safe.`,
+        `Start a build that has ${unmet.map((r) => r.migration).join(", ")} instead. Only to roll back on purpose, after handling the data of that migration: ${unmet.map((r) => rollbackDelete(r.migration)).join(" ")}`,
+    ];
+}
+export function servingRequirementUnmetSentence(code, reason, unmet, absentTables, releaseLine) {
+    switch (reason) {
+        case "capability_missing":
+            return (`${code} (reason: capability_missing): this database requires every serving replica to have ${unmet.map(requirementClause).join(", ")}; this build (release ${releaseLine}) does not. ` +
+                "No one-time migration ran and no stored data was changed (the section head only registered this replica and removed registrations of other replicas older than 90 days). " +
+                `Start a build that has ${unmet.map((r) => r.migration).join(", ")}. ` +
+                `Only to roll back on purpose, after handling the data of that migration: ${unmet.map((r) => rollbackDelete(r.migration)).join(" ")}`);
+        case "table_absent":
+            return (`${code} (reason: table_absent): this database has no ${absentTables.join(" / ")} table — the serving requirements recorded there cannot be read, ` +
+                'and an unreadable requirement is not "no requirement", so this build refuses to start. Nothing was written. ' +
+                "Open the store with the public sequence createStoreBackend() → ensureSchema() → runOneTimeMigrations(): ensureSchema() creates these tables.");
+        default: {
+            const unhandled = reason;
+            throw new Error(`stop-then-start-sentence: unknown refusal reason ${String(unhandled)}`);
+        }
+    }
+}
 //# sourceMappingURL=stop-then-start-sentence.js.map