@sema-agent/server 7.148.0 → 7.150.0

package/dist/plugins/replica-registration.d.ts

@@ -0,0 +1,35 @@
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+/** 表名。 */
+export declare const REPLICA_REGISTRATION_TABLE = "replica_registration";
+/**
+ * 本构建的能力名单(常设、只增):每一条读停-迁-起证据的一次性迁移一个名。删码之后名字留着 —— 名单只增不减(钉:`test/replica-registration.test.ts`)。
+ * 守卫读证据时传的名在型上就要在这里(`ReplicaCapability`):不在名单里的迁移读不了证据,编译期红。
+ */
+export declare const REPLICA_CAPABILITIES: readonly ["M40", "M41", "M42", "M43", "M51"];
+export type ReplicaCapability = (typeof REPLICA_CAPABILITIES)[number];
+/** 留存视界(写者钟):登记早于此的别人的行在下一次登记时删。量级取远大于任一副本的寿命与副本间钟差。 */
+export declare const REPLICA_REGISTRATION_HORIZON_MS: number;
+/** 登记行(纯数据)。 */
+export interface ReplicaRegistration {
+    readonly instanceId: string;
+    /** 发布线(`package.json` 的版本串;只作归因,不进任何判据)。 */
+    readonly releaseLine: string;
+    readonly capabilities: readonly string[];
+    readonly hostName: string;
+    readonly pid: number;
+}
+/** 本进程的登记行:身份 · 本构建的发布线 · 能力名单 · 主机 · pid。 */
+export declare function buildThisReplicaRegistration(): ReplicaRegistration;
+/** 能力格的存形:逗号连接。 */
+export declare function capabilitiesCell(capabilities: readonly string[]): string;
+/** `knows(r, M)`:能力名单里有 M(整词相等;读不出的格 ⇒ 不知道,保守)。观察与准入共用这一只判据。 */
+export declare function knowsCapability(capabilities: readonly string[], migrationId: string): boolean;
+/** 能力格的读形(存形的逆;空串 ⇒ 空名单)。 */
+export declare function capabilitiesOfCell(cell: unknown): readonly string[];
+/** 建表句(两方言;幂等)。中央建表语句读它(`tidb-pool.ts` / `pg-pool.ts`),与 `one-time-migration-marker.ts` 同形:键列钉二进制排序。 */
+export declare function replicaRegistrationDdl(dialect: SqlDialect): string;
+/** 登记:先删视界外的别人的行,再缺席才落本行(两句,各自自动提交)。 */
+export declare function registerReplica(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration, nowMs: number): Promise<void>;
+/** 读这几只身份的登记行(不在的身份不出现在结果里;空入参 ⇒ 不读库)。 */
+export declare function readReplicaRegistrations(db: SqlExec, dialect: SqlDialect, instanceIds: readonly string[]): Promise<Map<string, ReplicaRegistration>>;
+//# sourceMappingURL=replica-registration.d.ts.map

package/dist/plugins/replica-registration.js

@@ -0,0 +1,48 @@
+import { hostname } from "node:os";
+import { processInstanceId } from "../process-instance.js";
+import { serviceVersion } from "../service-version.js";
+export const REPLICA_REGISTRATION_TABLE = "replica_registration";
+export const REPLICA_CAPABILITIES = ["M40", "M41", "M42", "M43", "M51"];
+export const REPLICA_REGISTRATION_HORIZON_MS = 90 * 24 * 60 * 60 * 1000;
+export function buildThisReplicaRegistration() {
+    return { instanceId: processInstanceId(), releaseLine: serviceVersion(), capabilities: REPLICA_CAPABILITIES, hostName: hostname(), pid: process.pid };
+}
+export function capabilitiesCell(capabilities) {
+    return capabilities.join(",");
+}
+export function knowsCapability(capabilities, migrationId) {
+    return capabilities.includes(migrationId);
+}
+export function capabilitiesOfCell(cell) {
+    return typeof cell === "string" && cell !== "" ? cell.split(",") : [];
+}
+export function replicaRegistrationDdl(dialect) {
+    return dialect === "mysql"
+        ? `CREATE TABLE IF NOT EXISTS ${REPLICA_REGISTRATION_TABLE} (instance_id VARCHAR(64) NOT NULL PRIMARY KEY, release_line VARCHAR(64) NOT NULL, capabilities VARCHAR(1024) NOT NULL, host_name VARCHAR(255) NOT NULL, pid BIGINT NOT NULL, registered_at_ms BIGINT NOT NULL) COLLATE utf8mb4_bin`
+        : `CREATE TABLE IF NOT EXISTS ${REPLICA_REGISTRATION_TABLE} (instance_id VARCHAR(64) COLLATE "C" NOT NULL PRIMARY KEY, release_line VARCHAR(64) COLLATE "C" NOT NULL, capabilities VARCHAR(1024) COLLATE "C" NOT NULL, host_name VARCHAR(255) COLLATE "C" NOT NULL, pid BIGINT NOT NULL, registered_at_ms BIGINT NOT NULL)`;
+}
+const ph = (dialect, i) => (dialect === "mysql" ? "?" : `$${i}`);
+export async function registerReplica(db, dialect, me, nowMs) {
+    await db.query(`DELETE FROM ${REPLICA_REGISTRATION_TABLE} WHERE registered_at_ms < ${ph(dialect, 1)} AND instance_id <> ${ph(dialect, 2)}`, [nowMs - REPLICA_REGISTRATION_HORIZON_MS, me.instanceId]);
+    const insert = `INSERT INTO ${REPLICA_REGISTRATION_TABLE} (instance_id, release_line, capabilities, host_name, pid, registered_at_ms) VALUES (${[1, 2, 3, 4, 5, 6].map((i) => ph(dialect, i)).join(", ")})`;
+    await db.query(dialect === "mysql" ? `${insert} ON DUPLICATE KEY UPDATE instance_id = instance_id` : `${insert} ON CONFLICT (instance_id) DO NOTHING`, [
+        me.instanceId,
+        me.releaseLine,
+        capabilitiesCell(me.capabilities),
+        me.hostName,
+        me.pid,
+        nowMs,
+    ]);
+}
+export async function readReplicaRegistrations(db, dialect, instanceIds) {
+    const out = new Map();
+    if (instanceIds.length === 0)
+        return out;
+    const { rows } = await db.query(`SELECT instance_id, release_line, capabilities, host_name, pid FROM ${REPLICA_REGISTRATION_TABLE} WHERE instance_id IN (${instanceIds.map((_, i) => ph(dialect, i + 1)).join(", ")})`, [...instanceIds]);
+    for (const r of rows) {
+        const instanceId = String(r["instance_id"]);
+        out.set(instanceId, { instanceId, releaseLine: String(r["release_line"]), capabilities: capabilitiesOfCell(r["capabilities"]), hostName: String(r["host_name"]), pid: Number(r["pid"]) });
+    }
+    return out;
+}
+//# sourceMappingURL=replica-registration.js.map

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -1,6 +1,6 @@
 /**
  * 托管留存执行面的**非破坏性 SQL 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12;先例 =
- * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/DESIGN-270-retention-lane.md` v1.3。
+ * `retention-store-sql.ts` 本身)。[ref] 车2,设计稿 `docs/[ref]-retention-lane.md` v1.3。
  *
  * ── 为什么与车1 的 `retention-store-sql.ts` 分家(而不是往那只店上再挂三组方法)────────────────────
  * 车1 那只店是 core `ManagedRetentionCapability` 的**实现体**:它的每一个公开方法都是一次**破坏性**

package/dist/plugins/run-store-sql.d.ts

@@ -170,8 +170,16 @@ export declare class SqlRunStore {
      * 同一只入口、同列同序列化),不是引擎交出的原件:`paused.token` / `failed.nestedPause.token` 两座在落列前摘掉,
      * 所以 poll 这一行的调用方(`GET /v1/runs/:id → result`)拿到的是「停在哪扇门上」而拿不到 resume 能力。
      * `result = null` = 这条腿没观察到 park 结果(断连竞态 / 重开 re-park),列写空 —— 与修前行形同。
+     *
+     * 🔴 **停驻写的 CAS = 「行仍归 `legId` 这条腿 ∧ 仍在跑(或已停在本词上)∧ 没挂取消请求」**(内存 / 文件孪生同一句):
+     *  · 持有腿(`leg_id`,认领铸、交回认领者):一笔丢了回执的停驻写之后卡被决、下一条腿认领了这条行 ⇒ 前一条腿的再提交落不到接手腿的行上;
+     *  · `running`:失联收割已把行落成 `failed` 并删掉 `task_active` 认领时,这一写若把它翻回停驻,会话就没了锁、卡还待决 ⇒ 收割的判决立住;
+     *  · 取消旗:取消动词对在跑行只置旗(`requestCancel`,CAS `status = 'running'`);停驻写认这面旗 ⇒ 同一行上两只写各 CAS 对方的事实,恰一个赢
+     *    (旗先 ⇒ 停驻不落,提交点以取消收场;停驻先 ⇒ 置旗落空,取消路由按停驻结算)。
+     * 交回 CAS 的答:命中行数 > 0 ⇔ 这一写之后行停在这个词上(MySQL 协议缺省带 FOUND_ROWS ⇒ 计的是匹配行,同值重写照算;PG 的 rowCount 同义);
+     * 0 ⇔ 上面三件有一件不成立(或行不在)—— 是哪一件由提交点读行答(`park-row-commit.ts`)。
      */
-    setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
+    setSuspended(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
     /**
      * [ref] D-B: PARK a run that paused on a REVIEW gate — a `needs_review` result (a dry-run diff review OR a
      * pre-action `plan_review`; core assemble-result slot 8.6). Like {@link setSuspended} this is a NON-terminal park
@@ -179,8 +187,8 @@ export declare class SqlRunStore {
      * resume path (`getActiveTaskId` → `markResuming`) can find + claim the row. core treats a review pause "like a
      * suspend, an INTENTIONAL durable pause" ([ref] §2.5) — the service MUST park it the same way, else the run is
      * terminalized + its lock released and the plan_review/dry_run_review resume can never run (it gets
-     * taskId=undefined and drives the model unprotected on an unlocked session). CAS on `running`/`needs_review`
-     * (reaper-revert guard, mirrors setSuspended). The park→resume→claim invariant is pinned on BOTH REAL engines by
+     * taskId=undefined and drives the model unprotected on an unlocked session). CAS = {@link setSuspended}'s three conditions
+     * (holding leg · `running`/`needs_review` · no cancel request). The park→resume→claim invariant is pinned on BOTH REAL engines by
      * `test/run-store-reaper-integration.test.ts` (`inv#1` row ownership across park→resume→handover, `inv#2` two
      * replicas racing one session ⇒ exactly one claim wins, `inv#3`/`inv#3'` stale-claim takeover vs fresh/parked
      * claims), closing the former required-before-GA gap. Keep it that way: the P2 lease-SQL bug and this
@@ -189,14 +197,15 @@ export declare class SqlRunStore {
      * mocked run-store unit tests stayed green. A mock cannot observe a unique-key claim race, a rolled-back loser,
      * or a multi-table reaper DELETE.
      */
-    setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
     /**
      * Durable F4 resume: a suspended run is being actively resumed. Flip it back to `running` (CAS — only if
      * still suspended) and refresh liveness, so the in-flight resume is protected by the running-run heartbeat
      * and is NOT killed by `reapSuspended` (which targets `status='suspended'` past the approval TTL). Without
      * this the row sits at `suspended`/updated_at=suspend-time for the WHOLE resume execution, so a resume that
-     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns true
-     * if it claimed the flip (false ⇒ the reaper already expired it, or it isn't suspended).
+     * crosses the TTL is marked `failed` mid-run and its session lock (`task_active`) is released. Returns the
+     * HOLDING LEG this claim minted ({@link RunRecord.legId}; the resumed leg's park writes carry it) when it claimed
+     * the flip, `undefined` otherwise (the reaper already expired it, or it isn't suspended).
      *
      * [ref](codex R1 [medium],红先双库证):认领 = **接管 `instance_id`**。此前该列只在 createRun 铸、此处不动,
      * 于是 A 创建、C 认领 resume 的行永远记 A —— 而 steer/interrupt 的「他副本」臂与 sendHandleMiss 都拿这列当
@@ -204,10 +213,10 @@ export declare class SqlRunStore {
      * 语义自此成文:`instance_id` = **当前持有副本**(createRun 铸、markResuming 认领接管);CAS 输不改列
      * (一个输掉的认领不许覆盖赢家的持有记录——同一条条件 UPDATE 天然保证)。
      */
-    markResuming(taskId: string, instanceId: string): Promise<boolean>;
+    markResuming(taskId: string, instanceId: string): Promise<string | undefined>;
     /**
      * 认领当写栅栏用(进程内两孪生的契约 = `store-contracts.ts` 的 `InProcessClaimFence`;本孪生是它的事务形):一个事务 ——
-     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
+     *  ① 锁读这条 run 行且它在跑(`task_run … FOR UPDATE`;副本与持有腿两列随行交给 `write`,见 `FencedRun`);② 锁读会话的认领行且它是这条 run 的(`task_active … FOR UPDATE`);
      *  ③ 刷新这条 run 的活性戳;④ `write` 在**同一个事务连接**上跑(另收锁住那一行的 {@link FencedRun});提交即放锁。任一没读到 ⇒ 不持有,不刷新、`write` 不调。`write` 抛或提交失败 ⇒ 整只抛。
      * 🔴 **取锁序 = task_run → task_active**,与 `setTerminal` / `reapStale` / `reapSuspended` 同序(它们先改 run 行、再删认领行):两行用两条语句按序锁,
      *    不用连表锁读(那一形的先后由计划器定,与终局 / 收割相反时两只事务各攥一行成环)。`createRun` 先锁根会话行再插认领行(本序从不碰 `session_meta`)、
@@ -238,6 +247,16 @@ export declare class SqlRunStore {
      *  reject): the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;
+    /** 放一条行上提交幂等键绑定的那一句(`releaseIdemKey` 与 `withdrawMintedRun` 的非在跑臂同读)。 */
+    private releaseIdemKeySql;
+    /**
+     * 撤回本请求铸的这一条 run(认领没放行,行从没交给引擎)—— 回到认领之前「没有这一行」的样子。唯一调用口 = 撤回表 `withdrawClaim` 的 `run` 臂
+     * (经 `http/claimed-run.ts` 的 `withdrawClaimedRun`)。本请求的行 = `task_id` 与建行交回的持有腿 `leg_id` 这一对(与停驻写的 CAS 同一只身份读法):
+     * 行上的持有腿不是 `legId`(没有这一行 / 别的腿持着 / 列之前的行)⇒ 一个字节不动。一个事务、取锁序 `task_run` → `task_active`(与终局 / 收割 / 栅栏同序):行仍在跑(`status = 'running'`:
+     * 没被收割、没终局)⇒ 删它的事件、它的认领、行本身(幂等键与指纹在行上,随行去);已终局 ⇒ 行零删 —— 死亡判决或别的终局写先到,那一份就是这条行的结局 ——
+     * 只放本请求在这一行上绑的提交幂等键;停驻 ⇒ 一个字节不动(撤回只对本请求铸的行,而它从没停驻过;口径与另两孪生同)(撤回之后本请求答的是「原样再发」,同键再发要真跑,不重放那一份结局)。交回删没删。
+     */
+    withdrawMintedRun(taskId: string, legId: string): Promise<boolean>;
     /** The body fingerprint this row's binding of `idem.key` holds — binding `idem.bodyFingerprint` first when it holds none (a key
      *  bound before the column existed): first arrival binds, everyone after reads. The fingerprint belongs to the KEY that bound
      *  the row, so a row this key is not bound to (hit by its `task_id` under another key, or made without a key) is never written

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

@@ -5,7 +5,7 @@ import { pgSanitizeText } from "./pg-safe-json.js";
 import { toIso as iso } from "./sql-row-helpers.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readJsonObjectColumn, readNonNullJsonValueColumn } from "./sql-json-column.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, isParkedRunStatus, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, RUN_STALL_VERDICT_UNLANDED_TAG, isParkedRunStatus, isTerminalRunStatus, mintRunLegId, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
 import { notifyRunTerminal, runTerminalLogLevel } from "../observability/run-terminal.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder, SQL_DB_NOW_MS, sqlDbNowMs } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
@@ -14,7 +14,7 @@ import { readRunIdentityCells, runIdentityCells } from "../identity-source.js";
 import { decideSpaceCommitAbandon, decideSpaceCommitClaim, fenceSpaceCommitAtTerminal, spaceCommitStateOf } from "../workspace-space-commit.js";
 function runRowCols(dialect) {
     return (`task_id, session_id, owner, status, ${jsonColumnText(dialect, "result")}, error, error_code, job_id, source, ` +
-        "identity_source, identity_scope, identity_principal_inc, instance_id, cancel_requested, objective_preview, created_at, updated_at");
+        "identity_source, identity_scope, identity_principal_inc, instance_id, leg_id, cancel_requested, objective_preview, created_at, updated_at");
 }
 const readPersistedTaskResultBody = createObjectColumnReader();
 function decodeResultColumn(v, taskId) {
@@ -101,18 +101,19 @@ export class SqlRunStore {
         }
     }
     async createRun(taskId, sessionId, owner, instanceId, meta = {}) {
+        const legId = mintRunLegId();
         const conn = await this.db.connect();
         try {
-            const first = await this.createRunOn(conn, taskId, sessionId, owner, instanceId, meta);
+            const first = await this.createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta);
             if (first.activeTaskId === undefined || !(await this.settleDueHolderOn(conn, first.activeTaskId)))
                 return first;
-            return await this.createRunOn(conn, taskId, sessionId, owner, instanceId, meta);
+            return await this.createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta);
         }
         finally {
             conn.release();
         }
     }
-    async createRunOn(conn, taskId, sessionId, owner, instanceId, meta) {
+    async createRunOn(conn, taskId, sessionId, owner, instanceId, legId, meta) {
         const idemKey = meta.idem?.key ?? null;
         let stage = "claim";
         try {
@@ -127,13 +128,14 @@ export class SqlRunStore {
                 await conn.query(this.q("INSERT INTO task_active (session_id, task_id, since) VALUES (?,?,?)", "INSERT INTO task_active (session_id, task_id, since) VALUES ($1,$2,$3)"), [sessionId, taskId, now]);
                 stage = "row";
                 const cells = runIdentityCells(meta.identity ?? null);
-                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
-                    "VALUES (?,?,?,'running',?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, job_id, source, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
-                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)"), [
+                await conn.query(this.q("INSERT INTO task_run (task_id, session_id, owner, status, instance_id, leg_id, job_id, source, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
+                    "VALUES (?,?,?,'running',?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO task_run (task_id, session_id, owner, status, instance_id, leg_id, job_id, source, identity_source, identity_scope, identity_principal_inc, objective_preview, idem_key, idem_body_fingerprint, created_at, updated_at) " +
+                    "VALUES ($1,$2,$3,'running',$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)"), [
                     taskId,
                     sessionId,
                     owner,
                     instanceId,
+                    legId,
                     meta.jobId ?? null,
                     meta.source ?? null,
                     cells.identitySource,
@@ -150,7 +152,7 @@ export class SqlRunStore {
                     now,
                 ]);
                 await conn.commit();
-                return { ok: true };
+                return { ok: true, legId };
             }
             catch (err) {
                 if (!this.isDupKey(err))
@@ -363,22 +365,25 @@ export class SqlRunStore {
             }
         }
     }
-    async setSuspended(taskId, result) {
+    async setSuspended(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
-        await this.db.query(this.q("UPDATE task_run SET status = 'suspended', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','suspended')", "UPDATE task_run SET status = 'suspended', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('running','suspended')"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId]);
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'suspended', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND leg_id = ? AND status IN ('running','suspended') AND cancel_requested = 0", "UPDATE task_run SET status = 'suspended', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND leg_id = $5 AND status IN ('running','suspended') AND cancel_requested = 0"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId, legId]);
+        return affected > 0;
     }
-    async setNeedsReview(taskId, result) {
+    async setNeedsReview(taskId, result, legId) {
         const sealed = sealRunRowResult(result);
-        await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND status IN ('running','needs_review')", "UPDATE task_run SET status = 'needs_review', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('running','needs_review')"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId]);
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'needs_review', result = ?, error_code = ?, updated_at = ? WHERE task_id = ? AND leg_id = ? AND status IN ('running','needs_review') AND cancel_requested = 0", "UPDATE task_run SET status = 'needs_review', result = $1::jsonb, error_code = $2, updated_at = $3 WHERE task_id = $4 AND leg_id = $5 AND status IN ('running','needs_review') AND cancel_requested = 0"), [sealed == null ? null : this.json(sealed), runRowErrorCodeOf(sealed), new Date(), taskId, legId]);
+        return affected > 0;
     }
     async markResuming(taskId, instanceId) {
-        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = $1, updated_at = $2 WHERE task_id = $3 AND status IN ('suspended','needs_review')"), [instanceId, new Date(), taskId]);
-        return affected === 1;
+        const legId = mintRunLegId();
+        const { affected } = await this.db.query(this.q("UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = ?, leg_id = ?, updated_at = ? WHERE task_id = ? AND status IN ('suspended','needs_review')", "UPDATE task_run SET status = 'running', cancel_requested = 0, preempt_requested = 0, result = NULL, error_code = NULL, instance_id = $1, leg_id = $2, updated_at = $3 WHERE task_id = $4 AND status IN ('suspended','needs_review')"), [instanceId, legId, new Date(), taskId]);
+        return affected === 1 ? legId : undefined;
     }
     async whileHoldingClaim(sessionId, taskId, write) {
         let fenced = { held: false };
         await this.tx(async (conn) => {
-            const run = await conn.query(this.q("SELECT task_id, instance_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
+            const run = await conn.query(this.q("SELECT task_id, instance_id, leg_id FROM task_run WHERE task_id = ? AND status = 'running' FOR UPDATE", "SELECT task_id, instance_id, leg_id FROM task_run WHERE task_id = $1 AND status = 'running' FOR UPDATE"), [taskId]);
             const row = run.rows[0];
             if (row === undefined)
                 return;
@@ -387,7 +392,7 @@ export class SqlRunStore {
             if (holder === undefined || String(holder.task_id) !== taskId)
                 return;
             await conn.query(this.q("UPDATE task_run SET updated_at = ? WHERE task_id = ?", "UPDATE task_run SET updated_at = $1 WHERE task_id = $2"), [new Date(), taskId]);
-            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null }) };
+            fenced = { held: true, value: await write(conn, { instanceId: row.instance_id ?? null, legId: row.leg_id ?? null }) };
         });
         return fenced;
     }
@@ -409,6 +414,7 @@ export class SqlRunStore {
             source: r.source ?? null,
             identity: readRunIdentityCells(r.identity_source, r.identity_scope, r.identity_principal_inc),
             instanceId: r.instance_id ?? null,
+            legId: r.leg_id ?? null,
             cancelRequested: Boolean(r.cancel_requested),
             objectivePreview: r.objective_preview ?? null,
             createdAt: iso(r.created_at),
@@ -433,7 +439,29 @@ export class SqlRunStore {
         return rows[0] ? this.rowToRun(rows[0]) : undefined;
     }
     async releaseIdemKey(taskId) {
-        await this.db.query(this.q("UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = $1"), [taskId]);
+        await this.db.query(this.releaseIdemKeySql(), [taskId]);
+    }
+    releaseIdemKeySql() {
+        return this.q("UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = ?", "UPDATE task_run SET idem_key = NULL, idem_body_fingerprint = NULL WHERE task_id = $1");
+    }
+    async withdrawMintedRun(taskId, legId) {
+        let withdrawn = false;
+        await this.tx(async (conn) => {
+            const { rows } = await conn.query(this.q("SELECT status FROM task_run WHERE task_id = ? AND leg_id = ? FOR UPDATE", "SELECT status FROM task_run WHERE task_id = $1 AND leg_id = $2 FOR UPDATE"), [taskId, legId]);
+            if (rows.length === 0)
+                return;
+            const status = rows[0].status;
+            if (status !== "running") {
+                if (isTerminalRunStatus(status))
+                    await conn.query(this.releaseIdemKeySql(), [taskId]);
+                return;
+            }
+            await conn.query(this.q("DELETE FROM task_event WHERE task_id = ?", "DELETE FROM task_event WHERE task_id = $1"), [taskId]);
+            await conn.query(this.q("DELETE FROM task_active WHERE task_id = ?", "DELETE FROM task_active WHERE task_id = $1"), [taskId]);
+            await conn.query(this.q("DELETE FROM task_run WHERE task_id = ?", "DELETE FROM task_run WHERE task_id = $1"), [taskId]);
+            withdrawn = true;
+        });
+        return withdrawn;
     }
     async bindIdemBodyFingerprint(taskId, idem) {
         await this.db.query(this.q("UPDATE task_run SET idem_body_fingerprint = ? WHERE task_id = ? AND idem_key = ? AND idem_body_fingerprint IS NULL", "UPDATE task_run SET idem_body_fingerprint = $1 WHERE task_id = $2 AND idem_key = $3 AND idem_body_fingerprint IS NULL"), [idem.bodyFingerprint, taskId, idem.key]);

package/dist/plugins/scenario-prefix-switch-m42.d.ts

@@ -1,4 +1,5 @@
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { type OlderReplicaEvidence } from "./stop-then-start-sentence.js";
 /** 本条的拒启码(机读)。 */
 export declare const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
 /** 本条在标记表(`one-time-migration-marker.ts`)里的那一行的键。 */
@@ -18,26 +19,21 @@ export interface ScenarioPrefixHit {
 export interface ScenarioPrefixReceipt {
     scenarioPrefixSourcesScanned: number;
 }
-/** 拒因闭集:存量命中 / 零命中而更早版本的副本可能仍在服务(SQL 的停-迁-起)。 */
-export type ScenarioPrefixRefusalReason = "stored_prefix" | "live_runs";
-/** 判活读数(`live_runs` 那一拒带):判活窗内心跳过的 run 数与可以再起的最早时刻。 */
-export interface ScenarioPrefixLiveRuns {
-    readonly liveRuns: number;
-    readonly windowSec: number;
-    readonly restartAfter: string;
-    readonly after: string;
-}
+/** 拒因闭集:存量命中 / 零命中而有停-迁-起证据(更早版本的副本可能仍在服务;SQL 的停-迁-起)。 */
+export type ScenarioPrefixRefusalReason = "stored_prefix" | "older_replica";
 /**
  * M42 的起服拒。具名类型 + 机读码 + 拒因;继承 {@link StoreBootRefusalError}(SQL 开库的等待窗不重试它;隐式 local 的降级臂不吞)。一个字节没改(扫描只读,标记没写)。
  *  · `stored_prefix` —— 存量里有以保留前缀开头的身份(`hits` 逐来源点名);
- *  · `live_runs` —— 零命中,但判活窗内仍有 run 在心跳:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` 带时刻)。
+ *  · `older_replica` —— 零命中,但有停-迁-起证据:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` = 证据,带时刻)。
  */
 export declare class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
     readonly reason: ScenarioPrefixRefusalReason;
     readonly hits: readonly ScenarioPrefixHit[];
-    readonly live?: ScenarioPrefixLiveRuns | undefined;
+    readonly live?: OlderReplicaEvidence | undefined;
     readonly code = "config.scenario_prefix_switch_refused";
-    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: ScenarioPrefixLiveRuns | undefined);
+    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: OlderReplicaEvidence | undefined, 
+    /** 库此刻还差的列(SQL 腿经 `describeUpgradeDriftTail` 读到的;列齐 / local 腿 ⇒ 空串):一次起服读全。 */
+    tail?: string);
     private static sentence;
 }
 /** local 腿的一处来源:店名 + 它的计数口(以保留前缀开头的属主行数)。 */

package/dist/plugins/scenario-prefix-switch-m42.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { SCENARIO_SUBJECT_PREFIX } from "../owner-brands.js";
 import { atomicWriteFileSync } from "./owner-only-file-mode.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
+import { olderReplicaEvidenceSentence, stopThenStartAction } from "./stop-then-start-sentence.js";
 export const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
 export const SCENARIO_PREFIX_MARKER_ID = "M42";
 export const LOCAL_MARKER_FILE = "one-time-migration-M42.json";
@@ -12,8 +13,8 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
     hits;
     live;
     code = SCENARIO_PREFIX_SWITCH_REFUSED_CODE;
-    constructor(reason, hits, live) {
-        super(ScenarioPrefixSwitchRefusedError.sentence(reason, hits, live));
+    constructor(reason, hits, live, tail = "") {
+        super(ScenarioPrefixSwitchRefusedError.sentence(reason, hits, live) + tail);
         this.reason = reason;
         this.hits = hits;
         this.live = live;
@@ -27,10 +28,12 @@ export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
                     `). This version reads that prefix as a scenario of a person, so these rows would be attributed to another person; it refuses to start rather than misread them. ` +
                     `Nothing was changed. Rename or delete those identities (the identity boundary now rejects principals with this prefix), then restart — ` +
                     `the check runs until it finds none, then records a marker in the store and does not run again.`);
-            case "live_runs":
-                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${live?.liveRuns ?? 0} run(s) heartbeated on this database ` +
-                    `within the last ${live?.windowSec ?? 0}s — a replica of an earlier version may still be serving, and it accepts principals with that prefix, so a clean check now would not stay clean. ` +
-                    `Nothing was changed and no marker was written. Stop every replica of the earlier version, then start this version after ${live?.after ?? "the heartbeat window"} (this check is stop-then-start, not rolling).`);
+            case "older_replica":
+                if (live === undefined)
+                    throw new Error("scenario-prefix-switch: an older_replica refusal carries its evidence");
+                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: no stored identity starts with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}", but ${olderReplicaEvidenceSentence(live)} ` +
+                    `— a replica of an earlier version may still be serving, and it accepts principals with that prefix, so a clean check now would not stay clean. ` +
+                    `Nothing was changed and no marker was written. ${stopThenStartAction(live.after)}`);
             default: {
                 const unhandled = reason;
                 throw new Error(`scenario-prefix-switch: unknown refusal reason ${String(unhandled)}`);

package/dist/plugins/schema-consistency.d.ts

@@ -36,6 +36,12 @@
  *   · `key`   —— 主键成员:给存量行加主键列等于改它们的身份,**不出语句**,只一句话(出路走「部署匹配的构建」)。
  * 反方向(构建可空、库里非空)不判:现网库里可能有,判了会让数量不明的库起不来。
  *
+ * ── 位置:建表之后、一次性迁移之前;比的是「待跑迁移跑完之后」的形 ─────────────────────────────────────
+ * 起服的每一只拒启判都先于第一笔一次性迁移写(拒启的那一次起服对存量一笔没改写;迁移读数只出现在起得来的那一次)。本探针因此在迁移段**之前**跑,
+ * 而库上可能还有本构建带着的迁移待跑(它们删 / 改名 / 补 / 重建的列):登记表每一行用 `shapeChanges` 声明它对表形做的事,{@link projectPendingShape}
+ * 是唯一一只投影 —— 先把库形投影成迁移之后的样子再对账。迁移要动的列不算不符;别的缺列 / 多列 / 可空列照拒。发车门 1.10 第三档读同一只投影。
+ * 迁移段之后起服再调一次、待跑集为空(收口):声明多报了迁移没做的改动 ⇒ 这一次拒(构建缺陷;不收口则投影在窗内每次起服都把那一处抹平)。
+ *
  * ── 失败方向:读不到就拒,不跳过 ─────────────────────────────────────────────────────────────
  * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
  * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
@@ -54,6 +60,8 @@
  * (探针先于它的第一条 CREATE)—— 一次会拒的起服不许先在库里建出几十张本版新表(`task_run` 还带着新列),否则拒句里「没动过库」就是假话,
  * 按拒句指路去 7.125.x 起服的人会撞上「库比 7.125.x 新」的第二道拒。嵌入方走公开序列 `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
  * 即得到这一问,零动作。
+ * 同一处(建表之前、只读)还有本族的另一只跳版臂:`Skill` 豁免截点(`approval-exemption-skill-cutoff.ts`)—— 证据不是 schema 而是行(截点之前的 `Skill` 豁免行),
+ * 截点、判与拒(`LegacySkillExemptionsPresentError`,同码)住在那一只模块;调用点同在 `withRetiredSchemaProbe`。
  * 残余(如实):运维在第一次起带迁移的版本之前就把两件退役 schema 都手工删掉的库,残留的旧拼法由门记录的读腿接住 —— 7.129.0 起(core 7.51.0 [ref])
  * 那只读腿按 core 的档案读法读,`unresolvable` 是 core 退役词注册表里的词 ⇒ 记录原词原样读回、不改写(`trace/project.ts` `screenedGate`);local 文件车道
  * 没有表与列,没有这一问 —— 引擎 File 店里已决 checkpoint 的记录按契约物理不可变,本仓没有合法缝改写它们,同由那条读腿接住。
@@ -113,6 +121,54 @@ export interface TableMismatch {
 }
 /** 对账(纯函数:期望 × 实况 → 不符表清单)。实况 = {@link readLiveColumns} 的读数(列在不在 + 可不可空,一次读)。 */
 export declare function diffSchema(expected: Map<string, ParsedTable>, live: LiveColumns): TableMismatch[];
+/**
+ * 一条一次性迁移起服时对**存量表形**做的事(登记表 `plugins/one-time-migrations.ts` 一行的 `shapeChanges` 里的一项;纯数据,列名取自迁移语句读的那一份常量)。闭集四种,
+ * 条件都只读**迁移之前**的库形(与迁移步自己的判据同一个事实:列在不在):
+ *  · `drop`    —— 列在 ⇒ 删;
+ *  · `rename`  —— `to` 不在 ∧ `from` 里**恰有一列**在 ⇒ 那一列改名成 `to`(改名之后的可空性按方言:MySQL 协议的改名句是 `CHANGE COLUMN <旧名> <本构建的列定义>`,
+ *               列按本构建的声明重定义;PG 的 `RENAME COLUMN` 不动列定义,可空性随旧列走);别的形(两列都在 / 新名已在)迁移自己会撞库,不投影 ⇒ 对账照拒;
+ *  · `add`     —— 列不在 ⇒ 按本构建的声明加上;`whilePresent` 在场 ⇒ 只在那张表上还有其中任一列时才加(迁移步的判据就是那几列在不在);
+ *  · `rebuild` —— `whilePresent` 列在 ∧ 本构建声明的列里除 `supplies`(迁移自己给值的那几列)以外每一列都在(迁移的搬运句从旧表读的就是这几列)⇒ 整张表按本构建的建表语句重建
+ *               (列集与可空性 = 本构建的声明;旧表上别的列随重建丢掉 —— 迁移真落下的形就是这样);缺搬运要读的列 ⇒ 不投影(迁移会在搬运那一步失败)⇒ 对账照拒,拒在迁移写之前。
+ */
+export type PendingShapeChange = {
+    readonly kind: "drop";
+    readonly table: string;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "rename";
+    readonly table: string;
+    readonly from: readonly string[];
+    readonly to: string;
+} | {
+    readonly kind: "add";
+    readonly table: string;
+    readonly column: string;
+    readonly whilePresent?: {
+        readonly table: string;
+        readonly anyOf: readonly string[];
+    };
+} | {
+    readonly kind: "rebuild";
+    readonly table: string;
+    readonly whilePresent: string;
+    readonly supplies: readonly string[];
+};
+/** 一条迁移的表形声明(登记表的行结构上满足它:`id` + 可选的 `shapeChanges`)。 */
+export interface PendingShapeSource {
+    readonly id: string;
+    readonly shapeChanges?: readonly PendingShapeChange[];
+}
+/** 投影的结果:迁移跑完之后的库形 + 真改了表形的那几条迁移(按登记序)。 */
+export interface PendingShapeProjection {
+    readonly projected: LiveColumns;
+    readonly appliedBy: readonly string[];
+}
+/**
+ * 待跑的一次性迁移把库形改成什么(纯函数;**唯一**一只投影 —— 起服列册对账与发车门 1.10 第三档都读它)。条件读 `live`(迁移之前的形),改动落在一份拷贝上 ⇒ 与声明的先后无关。
+ * 一个(表 × 列)只许一条声明认领(`rebuild` 认领整张表):两条声明碰同一处 ⇒ 响亮抛(一件事一个属主,不挑一个)。
+ */
+export declare function projectPendingShape(expected: Map<string, ParsedTable>, live: LiveColumns, sources: readonly PendingShapeSource[], dialect: SqlDialect): PendingShapeProjection;
 /** 缺一列时的配方(按 {@link columnFill} 三类);拒启句里这一列的那几行就是它的返回值,真库钉据此取期望而不手抄句子。 */
 export declare function missingColumnLines(dialect: SqlDialect, table: string, c: ParsedColumn): string[];
 /**
@@ -126,14 +182,44 @@ export declare function missingColumnLines(dialect: SqlDialect, table: string, c
  * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据 —— 这里不写,拒启句的钉也守着(`test/schema-consistency.test.ts` ⑤)。
  */
 export declare function describeMismatchedTables(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string[];
-/** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
-export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string;
 /**
- * 启动期对账:**建表之后**跑,不符即抛(= 拒启)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
+ * **升级清单**(多行;`[]` = 没有语句要部署者执行,清单不出):一次起服的拒句里「这只库此刻对本构建还差什么、先后顺序」一段。
+ * 缺列拒、判活拒、一次性迁移的拒本来各报各的一段 —— 运维补一句再起、才撞上下一族(列册对账在迁移段之后时,第四次起服才拒出其余全部 ALTER)。
+ * 清单把本构建对这一只库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 这只库**还欠**的停-迁-起迁移
+ * ③ 起服。第 ② 步逐行问登记行的 `stopThenStart.owedOn`(一次性迁移文件静态依赖本文件,所以惰性载入)—— 那条迁移的守卫自己问的同一只判据,清单不另判:
+ * 已经走过它们的库(标记落了 / 部署格已搬 / 零行旧词)一条不欠 ⇒ 第 ② 步与它的「不可滚动」动作段都不出,起服是第 ② 步。某一条读不出欠不欠(探针读抛)⇒ 照列并如实说
+ * 没读到(多停一次,不漏停)。`read` = 列册对账读列册的同一只无参读口。
+ */
+export declare function describeUpgradeChecklist(read: SchemaProbeRead, dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
+/** 拒启文案(表头 + {@link describeUpgradeChecklist}〔有语句要执行时〕+ 逐表段与闭集三条出路 {@link describeMismatchedTables})。`checklist` 由调用方 `await describeUpgradeChecklist(…)` 交来(本函数保持同步纯函数,不读库)。 */
+export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[], checklist?: readonly string[]): string;
+/**
+ * 迁移段**之前 / 之中**读列册的拒句(单表探针的拒因、判活守卫的句尾)要的那一份:库经本构建**全部待跑迁移**之后({@link projectPendingShape},登记表各行的 `shapeChanges`,
+ * 与起服对账同一只投影)对本构建的不符里,只留**要部署者执行语句**的方向(缺列、声明非空而库里允许 NULL):
+ *  · 待跑迁移要删 / 改名走的旧列、自己要建的列,投影已经按迁移自己的条件换成迁移之后的形 —— 不读成「库比构建新」,也不列成部署者的 `ALTER`
+ *    (部署者照句子先加了,迁移的改名 / 加列反而撞上已存在的目标列、起服卡死);条件不成立的(如改名的源列不在)照列,迁移不会替它建;
+ *  · 投影之后还剩的幽灵列〔库里有、代码没有〕去掉 —— 没有语句可给,名字又来自库里、不受信,不进「给运维的指令」。
+ * 迁移段之中读:已跑过的迁移的条件读到的是迁移之后的形、不再投影,所以读数与迁移段之前同一份。登记表惰性载入(一次性迁移文件静态依赖本文件)。
+ */
+export declare function statementBearing(expected: Map<string, ParsedTable>, live: LiveColumns, dialect: SqlDialect): Promise<TableMismatch[]>;
+/** 清单 + 逐表段 + 闭集三条出路(多行):单表探针的拒因与判活守卫的句尾共用的正文(列册对账的拒句是 {@link describeSchemaMismatch},同一份清单与逐表段)。 */
+export declare function describeUpgradeBody(read: SchemaProbeRead, dialect: SqlDialect, mismatches: readonly TableMismatch[]): Promise<string[]>;
+/** 句尾读列册的期限(ms):这一段是拒句上的附加,不许把已经成立的拒拖住 —— 读不回来就如实说没读到,拒照出。 */
+export declare const DRIFT_TAIL_DEADLINE_MS = 10000;
+/**
+ * 别的拒启(一次性迁移的判活守卫)句尾上的「这只库此刻还差的列」一段:读整库列册对账同一份读数({@link statementBearing} 之后),没有语句要执行 ⇒ `""`;否则一个空行 + 一行引子 +
+ * {@link describeUpgradeBody}。读不出列册 / 超过 {@link DRIFT_TAIL_DEADLINE_MS} ⇒ 响亮地说没读到及原因(不静默吞:吞了运维以为列是齐的;也不无限等:拒已经成立,
+ * 这一段只是附加 —— 读卡住的那条语句留在连接上,和迁移段里任何一条卡住的语句同一个去处)。`deadlineMs` 是测试缝。
+ */
+export declare function describeUpgradeDriftTail(read: SchemaProbeRead, dialect: SqlDialect, deadlineMs?: number): Promise<string>;
+/**
+ * 启动期对账:**建表之后、一次性迁移之前**跑,不符即抛(= 拒启;拒的时候迁移一笔没写)。两方言 + InnoDB 同腿(MySQL 协议共用 `mysql` 臂)。
+ * 比的是库**经待跑的一次性迁移之后**的形({@link projectPendingShape};`pending` = 本构建带着的迁移的表形声明,起服读登记表交来):迁移要删 / 改名 / 补的列不算不符,
+ * 别的缺列 / 多列 / 可空列照拒 —— 漏了升级前 DDL 的库在迁移改写任何一行之前就被拒。
  *
- * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。
+ * 失败方向见文件头注:读抛 / 整库零行 ⇒ 拒。三条拒(读不出 / 整库零行 / 列集不符)与单表探针的拒启同一只出口 {@link SchemaMismatchRefusedError}(`code` = `config.schema_mismatch`)。
  */
-export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SqlDialect): Promise<void>;
+export declare function assertSchemaMatchesCode(read: SchemaProbeRead, dialect: SqlDialect, pending: readonly PendingShapeSource[]): Promise<void>;
 /**
  * 跳版升级的库的拒启:退役 schema(快照索引表 / 单座列)任一仍在。**具名类型**:锚类型不锚文案(日志消费端与测试按 `code` / 类型分派);
  * 码取列册对账同一个 `config.schema_mismatch`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。