@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/sandbox-reaper.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 车道沙箱回收腿的接口 —— 维护 tick(`boot/reapers.ts`)上**唯一一只**沙箱回收座:k8s 车道 = 沙箱 Pod 回收器({@link createSandboxPodReaper},`k8s-pod-reaper.ts`),
+ * local-docker 车道 = 无主容器回收器({@link createLocalDockerReaper},`local-docker-reaper.ts`)。一次部署只有一条执行车道,所以座只有一只、节拍只有一个
+ * ({@link SANDBOX_REAP_PERIOD_MS})、连败告警只有一个名;两条车道各自的判据与读数留在各自的模块里,这里只有 tick 要知道的那一点。
+ */
+/** 一个副本两轮沙箱回收之间的间隔。常量:起服后第一个维护 tick 即跑一轮(起服那一轮),此后每个周期一轮。 */
+export declare const SANDBOX_REAP_PERIOD_MS: number;
+/** run 店的窄读口(三只 run 店共有的 `getRun`):回收器按 run 行的终态判「这只沙箱还有没有主人」。 */
+export interface SandboxReaperRunReader {
+    getRun(taskId: string): Promise<{
+        readonly status: string;
+        readonly updatedAt: string;
+    } | null | undefined>;
+}
+/** 一轮的公共读数(两条车道的轮次读数都是它的超集):列出来了没有 / 扫了几只 / 按各自闭集原因分的删与跳过计数。 */
+export interface SandboxReapRound {
+    readonly listed: boolean;
+    readonly scanned: number;
+    readonly deleted: Readonly<Record<string, number | undefined>>;
+    readonly skipped: Readonly<Record<string, number | undefined>>;
+}
+/** 维护 tick 调的那一口:一轮 = 列举 → 逐只判 → 收被判无主的;不抛。`runs` 缺席 = 本部署没有 run 店(判不了 run 的沙箱一律不动)。 */
+export interface SandboxReaper {
+    reapOnce(runs: SandboxReaperRunReader | undefined): Promise<SandboxReapRound>;
+}
+//# sourceMappingURL=sandbox-reaper.d.ts.map

package/dist/plugins/sandbox-reaper.js

@@ -0,0 +1,2 @@
+export const SANDBOX_REAP_PERIOD_MS = 5 * 60_000;
+//# sourceMappingURL=sandbox-reaper.js.map

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

@@ -0,0 +1,54 @@
+import { StoreBootRefusalError } from "./store-contracts.js";
+/** 本条的拒启码(机读)。 */
+export declare const SCENARIO_PREFIX_SWITCH_REFUSED_CODE = "config.scenario_prefix_switch_refused";
+/** 本条在标记表(`one-time-migration-marker.ts`)里的那一行的键。 */
+export declare const SCENARIO_PREFIX_MARKER_ID = "M42";
+/** local 车道的标记文件(数据根下,文件名即本条)。 */
+export declare const LOCAL_MARKER_FILE = "one-time-migration-M42.json";
+/** 身份列的名字判据(建表句派生扫描面的唯一一条)。 */
+export declare const IDENTITY_COLUMN_NAME: RegExp;
+/** `LIKE` 的前缀模式(`!` 作转义符:两方言同义、不碰反斜杠的方言差;前缀里的 `_` 是通配符,必须转义)。 */
+export declare const SCENARIO_PREFIX_LIKE: string;
+/** 一处命中:来源(SQL = `表.列`;local = 店名)+ 以保留前缀开头的行数。 */
+export interface ScenarioPrefixHit {
+    readonly source: string;
+    readonly rows: number;
+}
+/** 本条的读数 / 收据格(扫了几处来源;0 = 标记在场、没扫)。 */
+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;
+}
+/**
+ * M42 的起服拒。具名类型 + 机读码 + 拒因;继承 {@link StoreBootRefusalError}(SQL 开库的等待窗不重试它;隐式 local 的降级臂不吞)。一个字节没改(扫描只读,标记没写)。
+ *  · `stored_prefix` —— 存量里有以保留前缀开头的身份(`hits` 逐来源点名);
+ *  · `live_runs` —— 零命中,但判活窗内仍有 run 在心跳:更早版本的副本可能还在服务,扫描之后它还会收下这类身份 ⇒ 全停之后再起(`live` 带时刻)。
+ */
+export declare class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
+    readonly reason: ScenarioPrefixRefusalReason;
+    readonly hits: readonly ScenarioPrefixHit[];
+    readonly live?: ScenarioPrefixLiveRuns | undefined;
+    readonly code = "config.scenario_prefix_switch_refused";
+    constructor(reason: ScenarioPrefixRefusalReason, hits: readonly ScenarioPrefixHit[], live?: ScenarioPrefixLiveRuns | undefined);
+    private static sentence;
+}
+/** local 腿的一处来源:店名 + 它的计数口(以保留前缀开头的属主行数)。 */
+export interface LocalScenarioPrefixSource {
+    readonly source: string;
+    readonly rows: () => number | Promise<number>;
+}
+/**
+ * 🔴 M42 的 local 腿(唯一调用点 `LocalBackend.runOneTimeMigrations`,第一步):标记文件在 ⇒ 0(零扫描);否则逐店计数,一处命中 ⇒ {@link ScenarioPrefixSwitchRefusedError}
+ * (一字节没写);零命中 ⇒ 原子写标记文件(`required`:标记没落盘就不算扫过 —— 写不进 ⇒ 抛,起服拒,下一次起服重扫)。返回扫了几处来源。
+ * 数据根独占(根锁):同一只根上没有第二个起服者、也没有更早版本的副本与本次并跑 ⇒ 没有 SQL 腿的判活守卫。
+ */
+export declare function switchLocalScenarioPrefixM42(markerPath: string, sources: readonly LocalScenarioPrefixSource[]): Promise<number>;
+//# sourceMappingURL=scenario-prefix-switch-m42.d.ts.map

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

@@ -0,0 +1,55 @@
+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";
+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";
+export const IDENTITY_COLUMN_NAME = /(^|_)(owner|scope|principal|subject)$/;
+export const SCENARIO_PREFIX_LIKE = `${SCENARIO_SUBJECT_PREFIX.replace(/[!%_]/g, "!$&")}%`;
+export class ScenarioPrefixSwitchRefusedError extends StoreBootRefusalError {
+    reason;
+    hits;
+    live;
+    code = SCENARIO_PREFIX_SWITCH_REFUSED_CODE;
+    constructor(reason, hits, live) {
+        super(ScenarioPrefixSwitchRefusedError.sentence(reason, hits, live));
+        this.reason = reason;
+        this.hits = hits;
+        this.live = live;
+        this.name = "ScenarioPrefixSwitchRefusedError";
+    }
+    static sentence(reason, hits, live) {
+        switch (reason) {
+            case "stored_prefix":
+                return (`${SCENARIO_PREFIX_SWITCH_REFUSED_CODE}: stored identities start with the reserved prefix "${SCENARIO_SUBJECT_PREFIX}" (` +
+                    hits.map((h) => `${h.source}: ${h.rows} row${h.rows === 1 ? "" : "s"}`).join(", ") +
+                    `). 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).`);
+            default: {
+                const unhandled = reason;
+                throw new Error(`scenario-prefix-switch: unknown refusal reason ${String(unhandled)}`);
+            }
+        }
+    }
+}
+export async function switchLocalScenarioPrefixM42(markerPath, sources) {
+    if (existsSync(markerPath))
+        return 0;
+    const hits = [];
+    for (const s of sources) {
+        const rows = await s.rows();
+        if (rows > 0)
+            hits.push({ source: s.source, rows });
+    }
+    if (hits.length > 0)
+        throw new ScenarioPrefixSwitchRefusedError("stored_prefix", hits);
+    atomicWriteFileSync(markerPath, JSON.stringify({ migration: SCENARIO_PREFIX_MARKER_ID, markedAt: new Date().toISOString() }), { durability: "required" });
+    return sources.length;
+}
+//# sourceMappingURL=scenario-prefix-switch-m42.js.map

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,16 @@
  * 半径远大于本批;先解析文本,理由写在这里。)拒启文案里的那句 `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`   —— 主键成员:给存量行加主键列等于改它们的身份,**不出语句**,只一句话(出路走「部署匹配的构建」)。
+ * 反方向(构建可空、库里非空)不判:现网库里可能有,判了会让数量不明的库起不来。
+ *
  * ── 失败方向:读不到就拒,不跳过 ─────────────────────────────────────────────────────────────
  * information_schema 查询抛错、或整库一行都读不出来 ⇒ **拒启**。探针的语义是「我证明了库等于代码」,
  * 证不出来时放行等于把一条保护性断言静默降级成祝福([ref]:保护型缺席必须 fail-closed)。
@@ -51,12 +61,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,19 +80,27 @@ 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;
-/** 启动时真会建出来的**全部**表形(录制 → 解析)。同名表二次出现以**先到**为准(`IF NOT EXISTS` 的真语义)。 */
-export declare function expectedTableShapes(dialect: SqlDialect): Promise<Map<string, ParsedTable>>;
+/** 这一列声明的 `DEFAULT` 表达式原文;没有缺省(或值由引擎给)⇒ `undefined`;有缺省却读不出 ⇒ 抛。 */
+export declare function declaredDefault(col: ParsedColumn): string | undefined;
+/** 本构建声明这一列非空:顶层 `NOT NULL`,或主键成员。**tightened 的唯一谓词**(库里该列允许 NULL ⇒ 拒)。 */
+export declare function declaresNotNull(col: ParsedColumn): boolean;
 /**
- * 拒启码(机读)。附录 A / 拒启码表的登记名。含义 = 「本构建读不出的持久形,开始服务之前判」,一个码三只臂:本文件的列册对账与退役 schema 两道(SQL),
- * 以及 local 数据根的严格边档对账(`local-session-store.ts` 的 `LocalDataRootSchemaMismatchError`,`LocalBackend.ensureSchema()` 调;拒句同形:
- * 码开头的表头 · 逐坐标一段 · 「NEWER than this build」方向句 · 闭集出路)。
+ * 一列的「给存量行补值」类:**配方的分类表**(见文件头「第二问」;判 tightened 用 {@link declaresNotNull} 一条谓词,不按类开例外)。
+ *   · `key`   —— 主键成员(优先于其它);
+ *   · `value` —— 声明非空(顶层 `NOT NULL`)∧ 无 `DEFAULT` ∧ 不是自增 / 序列 / 生成列:值只有部署者知道;
+ *   · `self`  —— 其余:可空、或引擎自己给值(DEFAULT 的值就是声明的那个)。
+ * 关键字只在顶层算({@link maskNested}):列名、引号串、括号组里的字样不参与。
  */
-export declare const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
+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>>;
 /** 一张表的对账结论。 */
 export interface TableMismatch {
     readonly table: string;
@@ -86,19 +108,24 @@ export interface TableMismatch {
     readonly missing: readonly ParsedColumn[];
     /** 库有、代码没有(库比代码**新** —— 滚动窗里的旧副本)。 */
     readonly ghost: readonly string[];
+    /** 列在库里、构建声明非空({@link declaresNotNull})而库里允许 NULL(库比代码**旧**:缺列时部署者把它加成了可空,还没补值收紧;或手工放宽过)。 */
+    readonly tightened: readonly ParsedColumn[];
 }
-/** 对账(纯函数:期望 × 实况 → 不符表清单)。 */
-export declare function diffSchema(expected: Map<string, ParsedTable>, live: Map<string, Set<string>>): TableMismatch[];
+/** 对账(纯函数:期望 × 实况 → 不符表清单)。实况 = {@link readLiveColumns} 的读数(列在不在 + 可不可空,一次读)。 */
+export declare function diffSchema(expected: Map<string, ParsedTable>, live: LiveColumns): TableMismatch[];
+/** 缺一列时的配方(按 {@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[];
+export declare function describeMismatchedTables(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string[];
 /** 拒启文案(表头 + 逐表段与闭集三条出路 {@link describeMismatchedTables})。 */
 export declare function describeSchemaMismatch(dialect: SqlDialect, mismatches: readonly TableMismatch[]): string;
 /**

package/dist/plugins/schema-consistency.js

@@ -1,9 +1,9 @@
 import { recordEnsureStatements } from "./schema-ensure-legs.js";
 import { readLiveColumns } from "./schema-live-columns.js";
 import { SCHEMA_MISMATCH_WAYS_OUT } from "./schema-drift-sentence.js";
-import { StoreBootRefusalError } from "./store-contracts.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
 const QUOTES = new Set(["'", '"', "`"]);
-function stripLineComments(sql) {
+function stripComments(sql) {
     let out = "";
     for (let i = 0; i < sql.length; i++) {
         const c = sql[i];
@@ -25,6 +25,12 @@ function stripLineComments(sql) {
             out += "\n";
             continue;
         }
+        if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            out += " ";
+            i = end < 0 ? sql.length : end + 1;
+            continue;
+        }
         out += c;
     }
     return out;
@@ -56,8 +62,69 @@ function splitTopLevel(body) {
 }
 const CONSTRAINT_HEADS = new Set(["PRIMARY", "UNIQUE", "KEY", "INDEX", "CONSTRAINT", "FOREIGN", "CHECK", "FULLTEXT", "SPATIAL", "EXCLUDE"]);
 const unquote = (s) => s.replace(/^[`"](.*)[`"]$/s, "$1");
+function maskNested(s) {
+    let out = "";
+    let depth = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (QUOTES.has(c)) {
+            let j = i + 1;
+            while (j < s.length && s[j] !== c)
+                j++;
+            out += "\0".repeat(Math.min(j, s.length - 1) - i + 1);
+            i = j;
+            continue;
+        }
+        if (c === "(") {
+            out += depth === 0 ? "(" : "\0";
+            depth++;
+        }
+        else if (c === ")") {
+            depth = Math.max(0, depth - 1);
+            out += "\0";
+        }
+        else {
+            out += depth > 0 ? "\0" : c;
+        }
+    }
+    return out;
+}
+function groupEnd(s, open) {
+    let depth = 0;
+    for (let i = open; i < s.length; i++) {
+        const c = s[i];
+        if (QUOTES.has(c)) {
+            i++;
+            while (i < s.length && s[i] !== c)
+                i++;
+            continue;
+        }
+        if (c === "(")
+            depth++;
+        else if (c === ")") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function primaryKeyMembers(constraint) {
+    const at = /\bPRIMARY\s+KEY\b/i.exec(maskNested(constraint));
+    if (!at)
+        return [];
+    const open = constraint.indexOf("(", at.index);
+    if (open < 0)
+        return [];
+    const close = groupEnd(constraint, open);
+    if (close < 0)
+        return [];
+    return splitTopLevel(constraint.slice(open + 1, close))
+        .map((m) => unquote(m.trim().split(/[\s(]/, 1)[0]).toLowerCase())
+        .filter((m) => m !== "");
+}
 export function parseCreateTable(stmt) {
-    const sql = stripLineComments(stmt).trim();
+    const sql = stripComments(stmt).trim();
     const head = /^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"]?[\w$.]+[`"]?)\s*\(/i.exec(sql);
     if (!head)
         return undefined;
@@ -85,18 +152,93 @@ export function parseCreateTable(stmt) {
     }
     if (close < 0)
         return undefined;
-    const columns = [];
+    const plain = [];
+    const tableKey = new Set();
     for (const raw of splitTopLevel(sql.slice(open + 1, close))) {
         const part = raw.trim().replace(/\s+/g, " ");
         if (part === "")
             continue;
         const first = part.split(/[\s(]/, 1)[0];
-        if (CONSTRAINT_HEADS.has(first.toUpperCase()))
+        if (CONSTRAINT_HEADS.has(first.toUpperCase())) {
+            for (const member of primaryKeyMembers(part))
+                tableKey.add(member);
             continue;
-        columns.push({ name: unquote(first).toLowerCase(), ddl: part });
+        }
+        plain.push({ name: unquote(first).toLowerCase(), ddl: part, inlineKey: /\bPRIMARY\s+KEY\b/i.test(maskNested(part.slice(first.length))) });
     }
+    const columns = plain.map((c) => (c.inlineKey || tableKey.has(c.name) ? { name: c.name, ddl: c.ddl, key: true } : { name: c.name, ddl: c.ddl }));
     return { table: unquote(head[1]).toLowerCase(), columns };
 }
+function declarationOf(col) {
+    const rest = col.ddl.slice(col.ddl.split(/[\s(]/, 1)[0].length);
+    const top = maskNested(rest);
+    const notNull = /\bNOT\s+NULL\b/i.test(top);
+    const engineGives = /\b(?:AUTO_INCREMENT|GENERATED|IDENTITY|(?:BIG|SMALL)?SERIAL\d?)\b/i.test(top) || /\bAS\s*\(/i.test(top);
+    const at = /\bDEFAULT\b/i.exec(top);
+    const hasDefault = at !== null;
+    const defaultExpr = () => (!engineGives && at !== null ? defaultExpression(rest, at.index + at[0].length, col.name) : undefined);
+    return { key: col.key === true, notNull, engineGives, hasDefault, defaultExpr };
+}
+function defaultExpression(rest, from, column) {
+    let i = from;
+    while (i < rest.length && /\s/.test(rest[i]))
+        i++;
+    const start = i;
+    const c = rest[i];
+    let end = -1;
+    if (c !== undefined && QUOTES.has(c)) {
+        let j = i + 1;
+        for (;;) {
+            while (j < rest.length && rest[j] !== c)
+                j++;
+            if (j >= rest.length)
+                break;
+            if (rest[j + 1] === c) {
+                j += 2;
+                continue;
+            }
+            end = j + 1;
+            break;
+        }
+    }
+    else if (c === "(") {
+        const close = groupEnd(rest, i);
+        if (close >= 0)
+            end = close + 1;
+    }
+    else if (c !== undefined) {
+        const word = /^[+-]?[A-Za-z0-9_.$]+/.exec(rest.slice(i));
+        if (word) {
+            end = i + word[0].length;
+            if (rest[end] === "(") {
+                const close = groupEnd(rest, end);
+                end = close >= 0 ? close + 1 : -1;
+            }
+        }
+    }
+    if (end < 0 || end === start)
+        throw new Error(`cannot read the DEFAULT expression of column ${column}: ${rest.trim()}`);
+    return rest.slice(start, end);
+}
+export function declaredDefault(col) {
+    return declarationOf(col).defaultExpr();
+}
+export function declaresNotNull(col) {
+    const d = declarationOf(col);
+    return d.key || d.notNull;
+}
+export function columnFill(col) {
+    const d = declarationOf(col);
+    if (d.key)
+        return "key";
+    return d.notNull && !d.engineGives && !d.hasDefault ? "value" : "self";
+}
+function nullableForm(ddl) {
+    const at = /(?:\bCONSTRAINT\s+\S+\s+)?\bNOT\s+NULL\b/i.exec(maskNested(ddl));
+    if (!at)
+        return ddl;
+    return (ddl.slice(0, at.index) + " " + ddl.slice(at.index + at[0].length)).replace(/\s+/g, " ").trim();
+}
 export async function expectedTableShapes(dialect) {
     const shapes = new Map();
     for (const stmt of await recordEnsureStatements(dialect)) {
@@ -106,7 +248,6 @@ export async function expectedTableShapes(dialect) {
     }
     return shapes;
 }
-export const SCHEMA_MISMATCH_ERROR_CODE = "config.schema_mismatch";
 export function diffSchema(expected, live) {
     const out = [];
     for (const [table, shape] of expected) {
@@ -115,19 +256,78 @@ export function diffSchema(expected, live) {
             continue;
         const missing = shape.columns.filter((c) => !cols.has(c.name));
         const known = new Set(shape.columns.map((c) => c.name));
-        const ghost = [...cols].filter((c) => !known.has(c)).sort();
-        if (missing.length > 0 || ghost.length > 0)
-            out.push({ table, missing, ghost });
+        const ghost = [...cols.keys()].filter((c) => !known.has(c)).sort();
+        const tightened = shape.columns.filter((c) => cols.get(c.name)?.nullable === true && declaresNotNull(c));
+        if (missing.length > 0 || ghost.length > 0 || tightened.length > 0)
+            out.push({ table, missing, ghost, tightened });
     }
     return out;
 }
-export function describeMismatchedTables(mismatches) {
+function tightenLines(dialect, table, c) {
+    switch (dialect) {
+        case "pg":
+            return [`    ALTER TABLE ${table} ALTER COLUMN ${columnRef(c)} SET NOT NULL;`];
+        case "mysql":
+            return [`    SET SESSION sql_mode = CONCAT_WS(',', @@SESSION.sql_mode, 'STRICT_ALL_TABLES');`, `    ALTER TABLE ${table} MODIFY COLUMN ${c.ddl};`];
+        default: {
+            const unreachable = dialect;
+            throw new Error(`unknown SQL dialect ${String(unreachable)}`);
+        }
+    }
+}
+const columnRef = (c) => c.ddl.split(/[\s(]/, 1)[0];
+function backfillComment(table, column) {
+    return `    -- rows already in ${table} need a value for ${column} that this build cannot choose: UPDATE ${table} SET ${column} = … WHERE ${column} IS NULL;`;
+}
+export function missingColumnLines(dialect, table, c) {
+    const fill = columnFill(c);
+    switch (fill) {
+        case "self":
+            return [`    ALTER TABLE ${table} ADD COLUMN ${c.ddl};`];
+        case "value":
+            return [`    ALTER TABLE ${table} ADD COLUMN ${nullableForm(c.ddl)};`, backfillComment(table, columnRef(c)), ...tightenLines(dialect, table, c)];
+        case "key":
+            return [`    table ${table}: column ${c.name} is part of the primary key — adding it to rows already in ${table} changes their identity; this build has no statement for it.`];
+        default: {
+            const unreachable = fill;
+            throw new Error(`unknown column fill ${String(unreachable)}`);
+        }
+    }
+}
+function tightenedColumnLines(dialect, table, c) {
+    const fill = columnFill(c);
+    switch (fill) {
+        case "key":
+            return [`    table ${table}: column ${c.name} is part of the primary key and allows NULL in the database — rows already in ${table} may hold NULL in their key; this build has no statement for it.`];
+        case "value":
+            return [backfillComment(table, columnRef(c)), ...tightenLines(dialect, table, c)];
+        case "self": {
+            if (!declaresNotNull(c))
+                throw new Error(`schema mismatch for ${table}.${c.name}: a column this build declares nullable cannot be tightened`);
+            const defaultExpr = declaredDefault(c);
+            const ref = columnRef(c);
+            return defaultExpr === undefined
+                ? tightenLines(dialect, table, c)
+                : [`    UPDATE ${table} SET ${ref} = ${defaultExpr} WHERE ${ref} IS NULL;`, ...tightenLines(dialect, table, c)];
+        }
+        default: {
+            const unreachable = fill;
+            throw new Error(`unknown column fill ${String(unreachable)}`);
+        }
+    }
+}
+export function describeMismatchedTables(dialect, mismatches) {
     const lines = [];
     for (const m of mismatches) {
         if (m.missing.length > 0) {
             lines.push(`  table ${m.table}: MISSING column(s) ${m.missing.map((c) => c.name).join(", ")} — the database is OLDER than this build.`);
             for (const c of m.missing)
-                lines.push(`    ALTER TABLE ${m.table} ADD COLUMN ${c.ddl};`);
+                lines.push(...missingColumnLines(dialect, m.table, c));
+        }
+        if (m.tightened.length > 0) {
+            lines.push(`  table ${m.table}: column(s) ${m.tightened.map((c) => c.name).join(", ")} allow NULL in the database, but this build declares them NOT NULL — the database is OLDER than this build.`);
+            for (const c of m.tightened)
+                lines.push(...tightenedColumnLines(dialect, m.table, c));
         }
         if (m.ghost.length > 0) {
             lines.push(`  table ${m.table}: UNKNOWN column(s) ${m.ghost.join(", ")} — the database is NEWER than this build (a rolling window where an old replica reached an upgraded database).`);
@@ -143,7 +343,7 @@ export function describeSchemaMismatch(dialect, mismatches) {
         "Schema policy: the code is the single source of truth, and the column check that produced this refusal never alters a database —",
         "so a drifted database is a deployment-order problem, not something the process may quietly work around.",
         "",
-        ...describeMismatchedTables(mismatches),
+        ...describeMismatchedTables(dialect, mismatches),
     ];
     return lines.join("\n");
 }