@sema-agent/server 7.150.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,13 +2,14 @@
  * 「停-迁-起」那一段的**唯一属主**。
  *
  * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
- * 起服时由守卫判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`one-time-migrations.ts` 的 `readOlderReplicaEvidence`):
+ * 起服时由守卫段判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`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})。
+ * 起服准入(`serving-requirement.ts`:库上记着本构建没有的能力 ⇒ 拒启)的拒句同属这一族,也在这里({@link servingRequirementUnmetSentence});
+ * 起服拒句升级清单里「这只库要求本构建没有的能力」一步的句子同在这里({@link unmetRequirementChecklistStep})。
  *
- * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
+ * 叶子模块:零 import(守卫段、各条的拒句、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
  */
 /** 证据里一只登记过、却没有这条迁移能力的持有者(归因用:点名它是谁)。 */
 export interface OlderReplicaHolder {
@@ -47,9 +48,14 @@ export declare function stopThenStartAction(after?: string): string;
 /** 起服准入里一行本构建没有的要求(`state` = 判读的态,词表外的词读作 `in_force`;`word` = 库里存的原词)。 */
 export interface UnmetServingRequirement {
     readonly migration: string;
-    readonly state: "pending" | "in_force";
+    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

@@ -15,11 +15,9 @@ export function stopThenStartAction(after) {
 }
 function requirementClause(r) {
     switch (r.state) {
-        case "pending":
-            return `${r.migration} (pending: a newer build recorded it and has not changed any data for it yet)`;
         case "in_force":
             return r.word === "in_force"
-                ? `${r.migration} (in force: data has been changed for it)`
+                ? `${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;
@@ -27,17 +25,23 @@ function requirementClause(r) {
         }
     }
 }
+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": {
-            const inForce = unmet.filter((r) => r.state === "in_force").map((r) => r.migration);
+        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(", ")}.` +
-                (inForce.length === 0
-                    ? ""
-                    : ` Only to roll back on purpose, after handling the data of that migration: ${inForce.map((m) => `DELETE FROM serving_requirement WHERE migration_id = '${m}';`).join(" ")}`));
-        }
+                `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. ' +

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

@@ -0,0 +1,109 @@
+/**
+ * **停-迁-起**(SQL 两方言;常设,不带窗)—— 一次性迁移登记表里每一条停-迁-起行的声明型、它唯一的判官、守卫段与证据读法。
+ *
+ * ## 它回答哪一问(只这一问)
+ * 「一只**已在服务**、不认迁移 M 的副本,在 M 之后写下的那一笔不兼容写,由谁挡?」—— 答案是一格闭集 {@link StopThenStartFence}(围栏类):
+ *  · `structural` —— 库挡:M 的第一笔改动是 DDL(就地改名 / 删退役列 / 按建表语句重建),更早副本点名旧对象的每一句不兼容写当场失败(先围后搬);
+ *  · `per-write` —— 写句挡:从 `fencedSince` 起的构建,点名的那几句写在同一句 / 同一事务里读起服要求行;`fencedSince` 严格早于 M 的引入版
+ *    (逐写围栏只对带这段代码的构建生效,所以必须早至少一版装入);
+ *  · `accepted` —— 没有人挡:`residual` 一句写明残余(MIGRATION 原样引),停光旧副本是唯一的补偿。
+ * 类取「从第一笔不兼容写起就成立」的那一种:晚于任何一笔搬运的 DDL 围栏不使本条成 `structural`;`per-write` 与 `structural` 同时成立 ⇒ 取 `structural`。
+ * **围栏类没有起服期的分臂**:三类在起服时同一只序 —— 守卫段读证据(有 ⇒ 拒)、各条在自己的第一笔不兼容写之前记一行起服要求(`serving-requirement.ts`)。
+ * 类只决定放行判据({@link judgeStopThenStart})、残余的披露与作者该选哪一形。
+ *
+ * ## 一份声明、一只判官
+ * 登记表(`one-time-migrations.ts` 的 `ONE_TIME_MIGRATIONS`)每一行**显式**写 `stopThenStart: StopThenStartRow | null`(缺键 = tsc 红,形门再红一次);
+ * `null` 只说「本条不声明停-迁-起」(不拒启、不进升级清单的停-迁-起一步),**不是**混跑安全的证明。判官只答「这份声明合不合本类的放行判据」;
+ * 读者两处:形门(全表,非空 ⇒ 红)与起服({@link assertStopThenStartDeclarations}:SQL 一次性迁移段**取连接之前**判本构建的每一条停-迁-起行,非空 ⇒ 抛构建缺陷,一句库语句都没发)。
+ *
+ * ## 守卫段在一切写之前
+ * {@link guardOwedStopThenStart} 在 SQL 一次性迁移段的锁内、准入复核之后、第一步迁移之前跑(`runSqlOneTimeMigrations`):按登记序逐条问「这只库还欠不欠」,
+ * 欠的读证据,任一有证据 ⇒ 抛那一条自己的拒(码与句是那一条的)—— 迁移段一字节没写,各拒句里的「Nothing was changed」由构造成立。迁移步里不再读证据。
+ *
+ * ## 证据读法(常设)
+ * {@link readOlderReplicaEvidence}:判活窗内心跳过的 `running` run(谓词 = run 店的 `runningHeartbeatPredicate` 的 `live` 一侧,与死亡判决同一只构造、同一个窗),
+ * 按持有者分组,减去登记为知道 M 的持有者(`replica-registration.ts`)。早于副本登记的副本不登记,只经它们持有的 run 心跳可见;没登记的持有者照算(保守)——
+ * 回滚到早于副本登记的构建、跳过公开序列的嵌入方、登记行过了留存视界的长寿进程会一直可能存在,所以这一读法不是过渡、没有删除日期。
+ * 它是观察谓词,不是存活证明:空闲的(零 `running` run)副本看不见;刚停的副本留下的 run 在窗内仍算(拒句给「全停之后何时再起」)。
+ * 「库上的副本够不够新」(服务下限)就是这一读法读空,不另立读口、不加版本常量。
+ *
+ * local 车道:数据根独占(起服锁只许一个进程)⇒ 没有混跑窗,守卫段与证据读法只在 SQL 腿。
+ */
+import type { StoreBootRefusalError } from "./store-contracts.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
+import type { SqlDialect } from "./sql-driver.js";
+import type { PendingShapeChange } from "./schema-consistency.js";
+import type { OlderReplicaEvidence } from "./stop-then-start-sentence.js";
+import { type ReplicaCapability } from "./replica-registration.js";
+/** 已在服务、不认本条的副本在本条之后那一笔不兼容写由谁挡(闭集;停-迁-起行必填)。 */
+export type StopThenStartFence = 
+/** 库挡:`fencedBy` 是本行 `shapeChanges` 里的一项(`rename` / `drop` / `rebuild`,不许 `add`),且是本条的第一笔改动。 */
+{
+    readonly kind: "structural";
+    readonly fencedBy: PendingShapeChange;
+}
+/** 写句挡:从 `fencedSince`(x.y.z,严格早于本行 `introducedIn`)起的构建,`statements` 点名的那几句写读起服要求行,`(本条, in_force)` 在 ⇒ 不写、响亮。 */
+ | {
+    readonly kind: "per-write";
+    readonly fencedSince: string;
+    readonly statements: string;
+}
+/** 没人挡:`residual` 一句写明残余(MIGRATION 原样引);停光旧副本是唯一的补偿。 */
+ | {
+    readonly kind: "accepted";
+    readonly residual: string;
+};
+/**
+ * 一条停-迁-起迁移的登记格(登记表里只写引用,判据与拒句的码在本条的迁移步旁边):
+ *  · `reason` —— 一句英文:更早版本的副本在迁移之后还会写什么、写了会怎样(= 为什么不能两版滚动;升级清单原样列给运维);
+ *  · `owedOn` —— **这只库还欠不欠本条**的唯一读法(只读、无参语句):守卫段先问它(不欠 ⇒ 不读证据),升级清单的停-迁-起一步只列它答「欠」的行;
+ *  · `refuse` —— 有证据时本条的拒(本条自己的码与句;`read` = 锁连接上的无参读口,拒句尾的库况 / 本条的计数从它读);守卫段调它,迁移步里不再读证据;
+ *  · `fence` —— 围栏类({@link StopThenStartFence})。
+ */
+export interface StopThenStartRow {
+    readonly reason: string;
+    readonly owedOn: (read: SchemaProbeRead, dialect: SqlDialect) => Promise<boolean>;
+    readonly refuse: (evidence: OlderReplicaEvidence, read: SchemaProbeRead, dialect: SqlDialect) => Promise<StoreBootRefusalError>;
+    readonly fence: StopThenStartFence;
+}
+/** 一条停-迁-起行连同判官要读的两格(登记表行的 `id` / `introducedIn` / `shapeChanges`;一次性迁移文件的 `stopThenStartMigrations()` 交出这一形)。 */
+export interface StopThenStartEntry extends StopThenStartRow {
+    readonly id: string;
+    readonly introducedIn: string;
+    readonly shapeChanges?: readonly PendingShapeChange[];
+}
+/** 停-迁-起证据读法的判活窗输入:= 本部署的 `REAP_RUN_STALE_SEC`(收割器判「这条 run 的持有者还活着」用的同一个窗)。 */
+export interface LiveRunWindowInput {
+    readonly liveRunWindowMs: number;
+}
+/** 证据读法要的读口(一次性迁移段的锁连接;只读)。 */
+export interface EvidenceDb {
+    rows(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+}
+/**
+ * **唯一判官**:这份停-迁-起声明自相矛盾的清单(空 = 放行)。三类各自的放行判据(穷尽 `switch`,加第四类不处理 = tsc 红),外加三类共同的两条
+ * (名在能力名单里 —— 守卫读证据 ⇔ 名在名单里;缘由句不空)。纯函数。
+ */
+export declare function judgeStopThenStart(entry: StopThenStartEntry): readonly string[];
+/**
+ * **停-迁-起证据的唯一读法**(守卫段与 M43 的启用判同读;拒句与读数的句子属主 = `stop-then-start-sentence.ts`):判活窗内心跳过的 `running` run
+ * (run 店的 {@link runningHeartbeatPredicate} `live` 一侧 —— 收割器判活的同一只构造、同一个窗),按持有者(`task_run.instance_id`,建行铸、认领接管)分组,
+ * **减去登记为知道 `migrationId` 的持有者**(`knowsCapability`,与起服准入同一只判据)—— 剩下的 run 就是证据:持有者没有登记行(早于副本登记的副本、`NULL` 身份、
+ * 自传身份的嵌入方)或登记了而能力名单里没有这条迁移,照算(保守)。登记一半只作归因(点名持有者),**不判活**。
+ * 本进程此刻还在迁移段里、一条 run 都没起过 ⇒ 证据里只有别的进程。`task_run` 不在 ⇒ `undefined`。
+ * `migrationId` 在型上就要在能力名单里(`ReplicaCapability`):一条迁移读证据 ⇔ 它的名在名单里。
+ */
+export declare function readOlderReplicaEvidence(db: EvidenceDb, dialect: SqlDialect, input: LiveRunWindowInput, migrationId: ReplicaCapability): Promise<OlderReplicaEvidence | undefined>;
+/**
+ * 起服时的判官读者:本构建的每一条停-迁-起声明过 {@link judgeStopThenStart},任一条自相矛盾 ⇒ 抛(构建缺陷)。纯函数;唯一调用点 = SQL 一次性迁移段的入口
+ * (`runSqlOneTimeMigrations`),**在取连接之前** —— 抛出时这一次起服对库一句语句都没发(段头的登记、准入、取锁都还没开始)。
+ */
+export declare function assertStopThenStartDeclarations(entries: readonly StopThenStartEntry[]): void;
+/**
+ * **守卫段**(一次性迁移段的锁内、准入复核之后、第一步迁移之前;锁连接上;`entries` 已由调用方在取连接之前过了 {@link assertStopThenStartDeclarations}):
+ * 按登记序逐条 —— 不欠 ⇒ 跳过(不读证据);欠 ⇒ 读证据,有 ⇒ 抛那一条自己的拒({@link StopThenStartRow.refuse})。拒 ⇒ 迁移段一字节没写。
+ * 放行之后,各条在它**自己的**第一笔不兼容写之前记一行起服要求(`serving-requirement.ts` 的 `recordServingRequirement`;三类同记)—— 不在这里记:
+ * 本条若在本次起服里不欠,就没有那一笔写,也就不记。
+ */
+export declare function guardOwedStopThenStart(db: EvidenceDb, dialect: SqlDialect, input: LiveRunWindowInput, entries: readonly StopThenStartEntry[]): Promise<void>;
+//# sourceMappingURL=stop-then-start.d.ts.map