@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/scheduler-support.d.ts

@@ -1,6 +1,7 @@
 import { SchedulerError } from "@sema-agent/core";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "@sema-agent/core";
 import type { SchedulerParseWarning, SchedulerRecord } from "@sema-agent/settings-schema/scheduler-store";
+import { type ConfigDirTrustHost } from "../config-dir-trust.js";
 export type { SchedulerRecord };
 /** core `Result<T,E>` shape (harness/types) — `{ok:true,value} | {ok:false,error}`. */
 type Result<T, E> = {
@@ -31,6 +32,11 @@ export declare function validateIntent(intent: ScheduledIntent, caps: Caps, nowM
 export declare function defaultSchedulerStorePath(config: {
     readonly agentConfigDir?: string;
 }): string;
+/** {@link FileSchedulerBackend} 读写之前目录信任判官要的两件:声明的属主(`CONFIG_LOCAL_OWNER_UID`,配置席 `configLocalOwnerUid`)+ 宿主事实(测试注入;缺席 = 本进程)。 */
+export interface SchedulerStoreTrust {
+    readonly declaredOwnerUid: number | undefined;
+    readonly host?: ConfigDirTrustHost;
+}
 /** 调度店读写的日志口(logger 的子集)。 */
 export interface SchedulerStoreLog {
     warn(msg: string, meta?: Record<string, unknown>): void;
@@ -57,14 +63,23 @@ export declare class FileSchedulerBackend implements SchedulerCapability {
     private readonly storePath;
     private readonly now;
     private readonly log;
+    private readonly trust;
     /** `storePath` 必填:路径是装配层从配置定的事实(`SCHEDULER_STORE_PATH` ?? {@link defaultSchedulerStorePath}),本类不自己找缺省。
-     *  `log` 必填:店的每次读都交回告警(读不懂的文件 / 被跳过的记录 / 读时改写),没有不出声的读法。 */
+     *  `log` 必填:店的每次读都交回告警(读不懂的文件 / 被跳过的记录 / 读时改写),没有不出声的读法。
+     *  `trust` 必填:每次读写之前的目录信任判官要的声明属主(`CONFIG_LOCAL_OWNER_UID`;与本地配置根同一张可信集),见 {@link FileSchedulerBackend.untrustedStore}。 */
     constructor(opts: {
         storePath: string;
         log: SchedulerStoreLog;
+        trust: SchedulerStoreTrust;
         caps?: Partial<Caps>;
         now?: () => number;
     });
+    /**
+     * 🔴 每次读写之前过本地配置根的**同一只**目录信任判官(读者 `scheduler-store`):常驻调度方按记录点名的主体起任务,别人改得动这只店(文件或路径上任一级
+     * 组 / 他人可写、属主不在可信集;店还不在而它所在的目录别人能在其中建它)就改得动起什么 ⇒ 这一次读写整条拒(`io`,一个字节都不读不写),
+     * 运维日志一行 `scheduler_store_untrusted` 带与本地配置根同族的拒句(点名路径与模式 / 属主与改法);模型面只拿一句不带路径的 `io` 拒。
+     */
+    private untrustedStore;
     /** 一次读改写(契约的唯一写原语)。`fn` 必须纯、可重放(并发写者落地时整段重放);返回 `null` = 不写。拿不到结果的三形各成一个 `io` 错。 */
     private mutate;
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{

package/dist/plugins/scheduler-support.js

@@ -1,8 +1,9 @@
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { randomBytes, createHash } from "node:crypto";
-import { SchedulerError, isValidCronExpr } from "@sema-agent/core";
+import { SchedulerError, ensureDir, isValidCronExpr } from "@sema-agent/core";
 import { loadSchedulerStore, mutateSchedulerStore } from "@sema-agent/settings-schema/node";
 import { configRootOf } from "../sema-config-dir.js";
+import { trustedFileRefusal } from "../config-dir-trust.js";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
 export const DEFAULT_SCHEDULER_CAPS = {
@@ -89,12 +90,21 @@ export class FileSchedulerBackend {
     storePath;
     now;
     log;
+    trust;
     constructor(opts) {
         this.schedulerCapabilities = { ...DEFAULT_SCHEDULER_CAPS, ...(opts.caps ?? {}) };
         this.storePath = opts.storePath;
         this.log = opts.log;
+        this.trust = opts.trust;
         this.now = opts.now ?? (() => Date.now());
     }
+    async untrustedStore() {
+        const refusal = await trustedFileRefusal({ reader: "scheduler-store", file: this.storePath, declaredOwnerUid: this.trust.declaredOwnerUid, ...(this.trust.host !== undefined ? { host: this.trust.host } : {}) });
+        if (refusal === undefined)
+            return undefined;
+        this.log.warn("scheduler_store_untrusted", { path: this.storePath, refusal, note: "the scheduled-task store can be changed by another user — this read / write was refused and nothing was written; the refusal names the path and the fix" });
+        return new SchedulerError("io", "the scheduled-task store is not trusted (another user could change it) — nothing was read or written; the operator log names the path and the fix");
+    }
     mutate(fn, what) {
         let result;
         let produced = false;
@@ -135,6 +145,10 @@ export class FileSchedulerBackend {
         if (intent.lifetime === "session" && this.schedulerCapabilities.supportsSessionLifetime === false) {
             return err(new SchedulerError("invalid_schedule", 'lifetime:"session" is not supported on this deployment (no resident daemon reaps session-lifetime records — the row would be an orphan)'));
         }
+        const untrusted = await this.untrustedStore();
+        if (untrusted)
+            return err(untrusted);
+        ensureDir(dirname(this.storePath));
         const key = dedupKey(ctx.scope, intent, ctx.sessionId);
         const decided = this.mutate((records) => {
             const existingIdx = records.findIndex((r) => {
@@ -166,6 +180,9 @@ export class FileSchedulerBackend {
         return decided.ok ? decided.value : decided;
     }
     async cancel(id, ctx) {
+        const untrusted = await this.untrustedStore();
+        if (untrusted)
+            return err(untrusted);
         const decided = this.mutate((records) => {
             const idx = records.findIndex((r) => r.id === id);
             if (idx < 0 || records[idx].scope !== ctx.scope) {
@@ -176,6 +193,9 @@ export class FileSchedulerBackend {
         return decided.ok ? decided.value : decided;
     }
     async list(ctx) {
+        const untrusted = await this.untrustedStore();
+        if (untrusted)
+            return err(untrusted);
         let read;
         try {
             read = loadSchedulerStore(this.storePath, { nowMs: this.now() });

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

@@ -26,6 +26,22 @@
  * 半径远大于本批;先解析文本,理由写在这里。)拒启文案里的那句 `ALTER TABLE … ADD COLUMN …` 也由
  * **同一份解析结果**生成,不是手写的。
  *
+ * ── 第二问:声明非空而库里允许 NULL(tightened)─────────────────────────────────────────────────────
+ * 缺列的拒句给的是 `ALTER TABLE … ADD COLUMN <原文>`;对「声明 `NOT NULL`、没有缺省、不是键」的列,那一句原文在已有行的表上会被引擎拒(PG)或写进隐式缺省(MySQL 非严格),
+ * 部署者于是把列加成**可空**——只列名对账从此转绿,而存量行在这一列上是 NULL,本构建按非空读它。所以对账多问一件事,**一条谓词**:本构建声明非空的列
+ * (顶层 `NOT NULL`,或主键成员)在库里是否也非空;库里允许 NULL ⇒ 拒,并给出收紧的下一步。谓词不分类;**配方**按同一张分类表({@link columnFill})给:
+ *   · `self`  —— 引擎自己给值(可空 / 有 DEFAULT / 自增 / 生成列):缺列 ⇒ 一句 `ADD COLUMN <原文>`;库里允许 NULL ⇒ 有 DEFAULT 的:一句**真语句**
+ *               `UPDATE t SET c = <声明的 DEFAULT 原文> WHERE c IS NULL;`(缺省是本构建声明的,不算替存量行猜值)再收紧;自增 / 生成列:只收紧(值由引擎给);
+ *   · `value` —— 声明非空、无缺省、不是键:缺列 ⇒ 可空加列 → 注释回填(值只有部署者知道) → 收紧;库里允许 NULL ⇒ 只打后两(三)句;
+ *   · `key`   —— 主键成员:给存量行加主键列等于改它们的身份,**不出语句**,只一句话(出路走「部署匹配的构建」)。
+ * 反方向(构建可空、库里非空)不判:现网库里可能有,判了会让数量不明的库起不来。
+ *
+ * ── 位置:建表之后、一次性迁移之前;比的是「待跑迁移跑完之后」的形 ─────────────────────────────────────
+ * 起服的每一只拒启判都先于第一笔一次性迁移写(拒启的那一次起服对存量一笔没改写;迁移读数只出现在起得来的那一次)。本探针因此在迁移段**之前**跑,
+ * 而库上可能还有本构建带着的迁移待跑(它们删 / 改名 / 补 / 重建的列):登记表每一行用 `shapeChanges` 声明它对表形做的事,{@link projectPendingShape}
+ * 是唯一一只投影 —— 先把库形投影成迁移之后的样子再对账。迁移要动的列不算不符;别的缺列 / 多列 / 可空列照拒。发车门 1.10 第三档读同一只投影。
+ * 迁移段之后起服再调一次、待跑集为空(收口):声明多报了迁移没做的改动 ⇒ 这一次拒(构建缺陷;不收口则投影在窗内每次起服都把那一处抹平)。
+ *
  * ── 失败方向:读不到就拒,不跳过 ─────────────────────────────────────────────────────────────
  * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
  * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
@@ -44,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 的记录按契约物理不可变,本仓没有合法缝改写它们,同由那条读腿接住。
@@ -51,12 +69,16 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { SqlDialect } from "./sql-driver.js";
-import { type SchemaProbeRead } from "./schema-live-columns.js";
+import { type LiveColumns, type SchemaProbeRead } from "./schema-live-columns.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
-/** 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。 */
+/**
+ * 一列:名字 + 它在 `CREATE TABLE` 里的**原样定义文本**(生成 ADD COLUMN 指路用,不另手写)。
+ * `key` 只在为真时出现:这一列是主键成员(内联 `PRIMARY KEY`,或表级 / 命名约束 `PRIMARY KEY (…)` 的成员);缺席 = 不是键。
+ */
 export interface ParsedColumn {
     readonly name: string;
     readonly ddl: string;
+    readonly key?: true;
 }
 /** 一张表的列形。 */
 export interface ParsedTable {
@@ -66,11 +88,25 @@ export interface ParsedTable {
 /**
  * 解析一条 `CREATE TABLE`。不是建表语句(CREATE INDEX / INSERT / SELECT / CREATE EXTENSION)⇒ `undefined`。
  *
- * 认识面窄得刻意:只取**表名 + 顶层列名 + 该列的定义文本**。类型、默认值、可空性一律**不比对** ——
+ * 认识面窄得刻意:取**表名 + 顶层列名 + 该列的定义文本 + 是否主键成员**。类型、默认值**不比对** ——
  * 本探针守的是「列在不在」这一类(T-47 的真病),把类型也拉进来会让方言差异(`DATETIME(3)` ⇄
  * `TIMESTAMPTZ(3)`、`vector(d)` ⇄ `jsonb` 的运行期参数化)变成一堆假红,而那是另一条判据另一台车。
+ * 唯一多看的一件是声明非空的列在库里是否仍允许 NULL({@link declaresNotNull} / {@link diffSchema}),原因见文件头「第二问」。
  */
 export declare function parseCreateTable(stmt: string): ParsedTable | undefined;
+/** 这一列声明的 `DEFAULT` 表达式原文;没有缺省(或值由引擎给)⇒ `undefined`;有缺省却读不出 ⇒ 抛。 */
+export declare function declaredDefault(col: ParsedColumn): string | undefined;
+/** 本构建声明这一列非空:顶层 `NOT NULL`,或主键成员。**tightened 的唯一谓词**(库里该列允许 NULL ⇒ 拒)。 */
+export declare function declaresNotNull(col: ParsedColumn): boolean;
+/**
+ * 一列的「给存量行补值」类:**配方的分类表**(见文件头「第二问」;判 tightened 用 {@link declaresNotNull} 一条谓词,不按类开例外)。
+ *   · `key`   —— 主键成员(优先于其它);
+ *   · `value` —— 声明非空(顶层 `NOT NULL`)∧ 无 `DEFAULT` ∧ 不是自增 / 序列 / 生成列:值只有部署者知道;
+ *   · `self`  —— 其余:可空、或引擎自己给值(DEFAULT 的值就是声明的那个)。
+ * 关键字只在顶层算({@link maskNested}):列名、引号串、括号组里的字样不参与。
+ */
+export type ColumnFill = "key" | "value" | "self";
+export declare function columnFill(col: ParsedColumn): ColumnFill;
 /** 启动时真会建出来的**全部**表形(录制 → 解析)。同名表二次出现以**先到**为准(`IF NOT EXISTS` 的真语义)。 */
 export declare function expectedTableShapes(dialect: SqlDialect): Promise<Map<string, ParsedTable>>;
 /** 一张表的对账结论。 */
@@ -80,27 +116,108 @@ export interface TableMismatch {
     readonly missing: readonly ParsedColumn[];
     /** 库有、代码没有(库比代码**新** —— 滚动窗里的旧副本)。 */
     readonly ghost: readonly string[];
+    /** 列在库里、构建声明非空({@link declaresNotNull})而库里允许 NULL(库比代码**旧**:缺列时部署者把它加成了可空,还没补值收紧;或手工放宽过)。 */
+    readonly tightened: readonly ParsedColumn[];
+}
+/** 对账(纯函数:期望 × 实况 → 不符表清单)。实况 = {@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 declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
+/** 投影的结果:迁移跑完之后的库形 + 真改了表形的那几条迁移(按登记序)。 */
+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[];
 /**
  * 逐表段 + 闭集出路段(多行):整库对账的拒启句与单表探针的拒因共用这一份句形(`schema-drift-sentence.ts` 的 `describeProbedTableDrift` 读它)。
- * ADD COLUMN 句由解析结果**生成**,不手写。
+ * 语句由解析结果**生成**,不手写;逐列配方按 {@link columnFill} 三类(缺列:自填 = 一句 ADD COLUMN,要值 = 可空加列 → 回填注释 → 收紧,键 = 一句话没有语句;
+ * 列在而允许 NULL:见 {@link tightenedColumnLines})。
  *
  * 出路段 = {@link SCHEMA_MISMATCH_WAYS_OUT}(**闭集三条**,常量;句子的属主在 `schema-drift-sentence.ts`):
- * ① 部署与这个库匹配的构建;② 库比构建旧(缺列)⇒ 部署者自己执行上面逐字打印的 `ALTER TABLE … ADD COLUMN …`(列集对账与拒启句永不改库);
- * ③ 库比构建新(多列)⇒ 部署持有那些列的构建(先升库、再升副本)。
+ * ① 部署与这个库匹配的构建;② 库比构建旧(缺列,或声明非空而库里允许 NULL)⇒ 部署者自己执行上面逐字打印的语句(要值的列,值归部署者;打印的语句全部生效之前拒启不松)
+ * (列集对账与拒启句永不改库);③ 库比构建新(多列)⇒ 部署持有那些列的构建(先升库、再升副本)。
  * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据 —— 这里不写,拒启句的钉也守着(`test/schema-consistency.test.ts` ⑤)。
  */
-export declare function describeMismatchedTables(mismatches: readonly TableMismatch[]): string[];
-/** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
-export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string;
+export declare function describeMismatchedTables(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string[];
+/**
+ * **升级清单**(多行;`[]` = 没有语句要部署者执行,清单不出):一次起服的拒句里「这只库此刻对本构建还差什么、先后顺序」一段。
+ * 缺列拒、判活拒、一次性迁移的拒本来各报各的一段 —— 运维补一句再起、才撞上下一族(列册对账在迁移段之后时,第四次起服才拒出其余全部 ALTER)。
+ * 清单把本构建对存量库的全部动作写成一张:① 逐表的 ALTER(其下 {@link describeMismatchedTables} 的逐表段,全库一次列全)② 本构建带的停-迁-起迁移(登记表 `stopThenStart` 一格,
+ * 行在 ⇒ 码在;一次性迁移文件静态依赖本文件,所以惰性载入)③ 起服。第 ② 步对「已经走过这些迁移」的库是空操作(迁移在自己的守卫处判),清单不替守卫判「这一只库欠不欠」。
+ */
+export declare function describeUpgradeChecklist(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(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` 臂)。
+ * 启动期对账:**建表之后、一次性迁移之前**跑,不符即抛(= 拒启;拒的时候迁移一笔没写)。两方言 + 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`,运维面一个拒启码一个读法。拒句点名在场的坐标、说明第三条(旧拼法改写)同样没跑过、给出路。