@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/schema-consistency.js

@@ -1,9 +1,10 @@
 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 { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, SchemaMismatchRefusedError, StoreBootRefusalError } from "./store-contracts.js";
+import { stopThenStartAction } from "./stop-then-start-sentence.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 +26,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 +63,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 +153,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)) {
@@ -114,19 +257,189 @@ 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 claimedColumnsOf(change) {
+    switch (change.kind) {
+        case "drop":
+            return change.columns;
+        case "rename":
+            return [...change.from, change.to];
+        case "add":
+            return [change.column];
+        case "rebuild":
+            return undefined;
+        default: {
+            const unhandled = change;
+            throw new Error(`unknown pending shape change ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+const WHOLE_TABLE = "*";
+function assertSingleOwnerPerShape(sources) {
+    const owners = new Map();
+    for (const s of sources) {
+        for (const change of s.shapeChanges ?? []) {
+            const table = owners.get(change.table) ?? new Map();
+            owners.set(change.table, table);
+            const columns = claimedColumnsOf(change);
+            const clashes = columns === undefined ? [...table.values()] : [table.get(WHOLE_TABLE), ...columns.map((c) => table.get(c))];
+            const clash = clashes.find((id) => id !== undefined && id !== s.id);
+            if (clash !== undefined)
+                throw new Error(`pending shape: table ${change.table} is changed by both ${clash} and ${s.id} on the same ${columns === undefined ? "table" : "column"} — one shape change has one migration`);
+            for (const c of columns ?? [WHOLE_TABLE])
+                table.set(c, s.id);
+        }
+    }
+}
+function renamedColumn(dialect, old, declared) {
+    switch (dialect) {
+        case "mysql":
+            return declared();
+        case "pg":
+            return old;
+        default: {
+            const unhandled = dialect;
+            throw new Error(`unknown SQL dialect ${String(unhandled)}`);
+        }
+    }
+}
+export function projectPendingShape(expected, live, sources, dialect) {
+    assertSingleOwnerPerShape(sources);
+    const out = new Map([...live].map(([t, cols]) => [t, new Map(cols)]));
+    const declaredNullable = (table, column) => {
+        const col = expected.get(table)?.columns.find((c) => c.name === column);
+        if (col === undefined)
+            throw new Error(`pending shape: ${table}.${column} is not declared by this build's schema — a migration can only bring a column the build declares`);
+        return { nullable: !declaresNotNull(col) };
+    };
+    const applied = new Set();
+    for (const s of sources) {
+        for (const change of s.shapeChanges ?? []) {
+            const before = live.get(change.table);
+            const after = out.get(change.table);
+            if (before === undefined || after === undefined)
+                continue;
+            switch (change.kind) {
+                case "drop": {
+                    const present = change.columns.filter((c) => before.has(c));
+                    for (const c of present)
+                        after.delete(c);
+                    if (present.length > 0)
+                        applied.add(s.id);
+                    break;
+                }
+                case "rename": {
+                    const present = change.from.filter((c) => before.has(c));
+                    if (before.has(change.to) || present.length !== 1)
+                        break;
+                    const [from] = present;
+                    after.set(change.to, renamedColumn(dialect, before.get(from), () => declaredNullable(change.table, change.to)));
+                    after.delete(from);
+                    applied.add(s.id);
+                    break;
+                }
+                case "add": {
+                    if (before.has(change.column))
+                        break;
+                    const gate = change.whilePresent;
+                    if (gate !== undefined && !gate.anyOf.some((c) => live.get(gate.table)?.has(c) === true))
+                        break;
+                    after.set(change.column, declaredNullable(change.table, change.column));
+                    applied.add(s.id);
+                    break;
+                }
+                case "rebuild": {
+                    if (!before.has(change.whilePresent))
+                        break;
+                    const shape = expected.get(change.table);
+                    if (shape === undefined)
+                        throw new Error(`pending shape: ${change.table} is rebuilt by ${s.id} but this build declares no such table`);
+                    if (shape.columns.some((c) => !change.supplies.includes(c.name) && !before.has(c.name)))
+                        break;
+                    out.set(change.table, new Map(shape.columns.map((c) => [c.name, { nullable: !declaresNotNull(c) }])));
+                    applied.add(s.id);
+                    break;
+                }
+                default: {
+                    const unhandled = change;
+                    throw new Error(`unknown pending shape change ${JSON.stringify(unhandled)}`);
+                }
+            }
+        }
+    }
+    return { projected: out, appliedBy: sources.filter((s) => applied.has(s.id)).map((s) => s.id) };
+}
+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).`);
@@ -136,34 +449,91 @@ export function describeMismatchedTables(mismatches) {
     lines.push("", ...SCHEMA_MISMATCH_WAYS_OUT);
     return lines;
 }
-export function describeSchemaMismatch(dialect, mismatches) {
+function needsStatements(mismatches) {
+    return mismatches.some((m) => m.missing.length > 0 || m.tightened.length > 0);
+}
+export async function describeUpgradeChecklist(mismatches) {
+    if (!needsStatements(mismatches))
+        return [];
+    const { stopThenStartMigrations } = await import("./one-time-migrations.js");
+    const stops = stopThenStartMigrations();
+    const steps = [["Run every statement printed below, each recipe in the order it is printed (a printed comment line marks a value only you can choose) — all tables at once, before anything else (this build never alters a database for you)."]];
+    if (stops.length > 0) {
+        steps.push([
+            "Stop-then-start one-time migrations: this build runs them itself on its first boot (no statement from you), and each refuses to start — writing nothing — while any run on this database has",
+            "heartbeated within REAP_RUN_STALE_SEC. A database that has already been through one of them is not asked again.",
+            ...stops.map((m) => `  - ${m.id}: ${m.reason}`),
+            stopThenStartAction(),
+        ]);
+    }
+    steps.push(["Start this version; the one-time migrations above (if any are still owed) run on that boot."]);
+    return [
+        "Upgrade checklist — everything this build needs from you on this database, in this order (one start lists all of it; do not fix one table and retry):",
+        ...steps.flatMap((lines, i) => lines.map((l, k) => (k === 0 ? `  ${i + 1}. ${l}` : `     ${l}`))),
+    ];
+}
+export function describeSchemaMismatch(dialect, mismatches, checklist = []) {
     const lines = [
         `${SCHEMA_MISMATCH_ERROR_CODE}: the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} database does not match this build's schema — refusing to start.`,
         "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),
+        ...(checklist.length > 0 ? [...checklist, ""] : []),
+        ...describeMismatchedTables(dialect, mismatches),
     ];
     return lines.join("\n");
 }
-export async function assertSchemaMatchesCode(read, dialect) {
+export async function statementBearing(expected, live, dialect) {
+    const { ONE_TIME_MIGRATIONS } = await import("./one-time-migrations.js");
+    return diffSchema(expected, projectPendingShape(expected, live, ONE_TIME_MIGRATIONS, dialect).projected)
+        .map((m) => ({ ...m, ghost: [] }))
+        .filter((m) => m.missing.length > 0 || m.tightened.length > 0);
+}
+export async function describeUpgradeBody(dialect, mismatches) {
+    const checklist = await describeUpgradeChecklist(mismatches);
+    return [...(checklist.length > 0 ? [...checklist, ""] : []), ...describeMismatchedTables(dialect, mismatches)];
+}
+export const DRIFT_TAIL_DEADLINE_MS = 10_000;
+export async function describeUpgradeDriftTail(read, dialect, deadlineMs = DRIFT_TAIL_DEADLINE_MS) {
+    let mismatches;
+    let timer;
+    try {
+        const work = (async () => statementBearing(await expectedTableShapes(dialect), await readLiveColumns(read, dialect), dialect))();
+        work.catch(() => undefined);
+        const expired = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`no answer within ${deadlineMs} ms`)), deadlineMs);
+            timer.unref?.();
+        });
+        mismatches = await Promise.race([work, expired]);
+    }
+    catch (err) {
+        return `\n\nThe column check could not be read here (${err instanceof Error ? err.message : String(err)}), so any ALTER this database still owes is not listed in this refusal — the column check at boot lists them.`;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (mismatches.length === 0)
+        return "";
+    return `\n\nThis database also does not match this build's schema — the statements below are the ones the column check prints at boot:\n${(await describeUpgradeBody(dialect, mismatches)).join("\n")}`;
+}
+export async function assertSchemaMatchesCode(read, dialect, pending) {
     const expected = await expectedTableShapes(dialect);
     let live;
     try {
         live = await readLiveColumns(read, dialect);
     }
     catch (err) {
-        throw new Error(`${SCHEMA_MISMATCH_ERROR_CODE}: could not read information_schema.columns to verify the ${dialect} schema — refusing to start ` +
+        throw new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: could not read information_schema.columns to verify the ${dialect} schema — refusing to start ` +
             `(an unverifiable schema is treated as a mismatch, not as a pass): ${err instanceof Error ? err.message : String(err)}`, { cause: err });
     }
     if (live.size === 0) {
-        throw new Error(`${SCHEMA_MISMATCH_ERROR_CODE}: information_schema.columns returned no rows anywhere on this ${dialect} connection's schema path — refusing to start. ` +
+        throw new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: information_schema.columns returned no rows anywhere on this ${dialect} connection's schema path — refusing to start. ` +
             `Either the connection points at an empty/foreign schema, or the account cannot see its own catalog; both make the ` +
             `"database matches the code" check unprovable, and an unprovable protective check never passes.`);
     }
-    const mismatches = diffSchema(expected, live);
+    const mismatches = diffSchema(expected, projectPendingShape(expected, live, pending, dialect).projected);
     if (mismatches.length > 0)
-        throw new Error(describeSchemaMismatch(dialect, mismatches));
+        throw new SchemaMismatchRefusedError(describeSchemaMismatch(dialect, mismatches, await describeUpgradeChecklist(mismatches)));
 }
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT = { table: "checkpoint", column: "pending_steer" };

package/dist/plugins/schema-drift-sentence.d.ts

@@ -1,4 +1,5 @@
 import type { SqlDialect } from "./sql-driver.js";
+import { SchemaMismatchRefusedError } from "./store-contracts.js";
 /** 「库比构建旧」那一条出路的两个可变件:旧在哪(括注)、部署者要自己做的那件事。其余字一个不变。 */
 export interface OlderWayOut {
     /** 括注:库旧在哪(例:`missing columns`)。 */
@@ -11,17 +12,20 @@ export interface OlderWayOut {
  * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据。
  */
 export declare function schemaWaysOut(older: OlderWayOut): readonly string[];
-/** 缺列方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。 */
+/**
+ * 旧方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。「旧」= 缺列,或声明非空而库里仍允许 NULL 的列;
+ * 打印的是语句集,不只是 ADD COLUMN:要值列的值只有部署者知道(回填那一步以注释行给出),所以这一条把「值归部署者」和「打印的语句全部生效之前拒启不松」写明。
+ */
 export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
 /** 探针读口:一条 SQL → `{ rows }`(各 `assert*Schema` 的 `query` 形)。 */
 export type ProbeQuery = (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>;
+/** 单表探针的拒启(缺列、键宽不够)的出口:`body` 是码之后的整句,码在这里领头 —— 各探针不自己拼码。 */
+export declare function schemaMismatchRefusal(body: string): SchemaMismatchRefusedError;
 /**
- * 单表探针抓到可证缺列后,拒因里「哪几列缺、该跑哪几条 ALTER」+ 闭集出路这一整段(多行文本,不含探针自己的首句与底层错误)。
- *
- * 读不出库的列册(权限 / 超时)或对账看不到探针点名的表有缺列(探针与建表语句互相矛盾)⇒ **响亮**地说「ALTER 没能打印」及原因,
- * 出路仍是同一份闭集(旧一条改成「按建表语句自己加」)—— 绝不退回销毁性指路,也不悄悄吞掉这一段。
+ * 单表探针抓到可证缺列后的**整条拒启**(唯一铸点;`throw await probedMissingColumnRefusal(…)`):探针自己的首句 `lead`(这张表缺什么、缺了会在哪里坏;不带码、不带换行收尾)
+ * + 底层驱动错误 `underlying`(运维要看见是哪条探针读撞的)+ {@link describeProbedTableDrift} 的逐表段与闭集出路,码领头({@link schemaMismatchRefusal})。
  */
-export declare function describeProbedTableDrift(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[]): Promise<string>;
+export declare function probedMissingColumnRefusal(query: ProbeQuery, dialect: SqlDialect, tables: readonly string[], lead: string, underlying: unknown): Promise<SchemaMismatchRefusedError>;
 //# sourceMappingURL=schema-drift-sentence.d.ts.map

package/dist/plugins/schema-drift-sentence.js

@@ -1,4 +1,5 @@
 import { readLiveColumns } from "./schema-live-columns.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, SchemaMismatchRefusedError } from "./store-contracts.js";
 export function schemaWaysOut(older) {
     return [
         "  Ways out (these three and no others):",
@@ -8,19 +9,26 @@ export function schemaWaysOut(older) {
     ];
 }
 export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
-    when: "missing columns",
-    action: "run the ALTER TABLE … ADD COLUMN statements printed above yourself",
+    when: "missing columns, or columns that allow NULL where this build declares NOT NULL",
+    action: "run the statements printed above yourself (where a column needs a value this build cannot choose for rows already in the table, the printed comment says so and that value is yours; this refusal stays until every printed statement has taken effect)",
 });
-export async function describeProbedTableDrift(query, dialect, tables) {
+export function schemaMismatchRefusal(body) {
+    return new SchemaMismatchRefusedError(`${SCHEMA_MISMATCH_ERROR_CODE}: ${body}`);
+}
+export async function probedMissingColumnRefusal(query, dialect, tables, lead, underlying) {
+    return schemaMismatchRefusal(`${lead}\n` +
+        `Underlying probe error: ${underlying instanceof Error ? underlying.message : String(underlying)}\n\n` +
+        (await describeProbedTableDrift(query, dialect, tables)));
+}
+async function describeProbedTableDrift(query, dialect, tables) {
     const d = dialect === "pg" ? "pg" : "mysql";
     const read = async (sql) => (await query(sql)).rows;
     let why;
     try {
         const sc = await import("./schema-consistency.js");
-        const diff = sc.diffSchema(await sc.expectedTableShapes(d), await readLiveColumns(read, d));
-        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [] }));
-        if (missingOnly.length > 0)
-            return sc.describeMismatchedTables(missingOnly).join("\n");
+        const diff = await sc.statementBearing(await sc.expectedTableShapes(d), await readLiveColumns(read, d), d);
+        if (diff.some((m) => tables.includes(m.table) && m.missing.length > 0))
+            return (await sc.describeUpgradeBody(d, diff)).join("\n");
         why = "this build's table definitions list no column that the database lacks on that table, so the probe and the definitions disagree";
     }
     catch (err) {

package/dist/plugins/schema-ensure-legs.d.ts

@@ -2,6 +2,15 @@ import type { PgQueryFn } from "./pg-query.js";
 import type { SqlDialect } from "./sql-driver.js";
 /** advisory lock 语句 —— 与 schema 无关,录制时跳过(但要答成功,否则 ensure* 走降级告警路径)。 */
 export declare const LOCK_RE: RegExp;
+/**
+ * [ref] `ensureIndex` 的**索引在场**探针(MySQL 臂)。答「在场」——因为**新建库**上这批索引本来就随
+ * `CREATE TABLE` 的内联 `KEY` 一起到货,而基线按定义 =「启动时对一个新库真会执行的东西」。答"零行"会让
+ * 录制里凭空多出 68 条**新建库上永不发生**的 `ALTER TABLE … ADD INDEX`,基线就成了一份撒谎的产物。
+ * ⚠️ 这条特判**只**放行索引探针:任何别的 `information_schema` 探针照旧答零行 ⇒ 残留的「探列→ALTER」
+ * seam 仍会真的发出 ALTER 并被基线生成器的 `SeamViolation`(`scripts/dump-schema.ts`)当场抓住
+ * (SCHEMA POLICY 的那半一个字没松)。
+ */
+export declare const INDEX_PROBE_RE: RegExp;
 /**
  * **「一个新库对 ensure 探针怎么答」的唯一属主**(合并复审 车HB 后收口:此前生成器录制器、`test/ensure-schema.test.ts`
  * 的假池、`test/schema-baseline-generated.test.ts` ③c 的假驱动各抄一份,[ref] 加了索引探针 + PG 锁改 `got === true`

package/dist/plugins/schema-ensure-legs.js

@@ -14,7 +14,7 @@ import { ensureTiDBUsageWindowSchema, ensurePgUsageWindowSchema } from "../store
 import { ensureTiDBTaskListSchema, ensurePgTaskListSchema } from "./task-list-store-sql.js";
 import { ensureTiDBDeviceSchema, ensurePgDeviceSchema } from "./device-store-sql.js";
 export const LOCK_RE = /GET_LOCK|RELEASE_LOCK|pg_(try_)?advisory/i;
-const INDEX_PROBE_RE = /FROM information_schema\.statistics\b/i;
+export const INDEX_PROBE_RE = /^\s*SHOW\s+INDEX\s+FROM\b/i;
 const PG_INDEX_VALID_RE = /FROM pg_index i WHERE i\.indexrelid = to_regclass/i;
 function newDatabaseSessionMetaKeyCollation() {
     const stmt = SCHEMA_STATEMENTS.find((s) => s.includes("CREATE TABLE IF NOT EXISTS session_meta ("));

package/dist/plugins/schema-indexes.js

@@ -7,6 +7,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "task_active", name: "idx_task_active_task", columns: ["task_id"] },
     { table: "checkpoint", name: "idx_checkpoint_status_deadline", columns: ["status", "deadline"] },
     { table: "checkpoint", name: "idx_checkpoint_session_status", columns: ["session_id", "status"] },
+    { table: "checkpoint", name: "idx_checkpoint_host_session_status", columns: ["host_session_id", "status"] },
     { table: "resume_anchor", name: "idx_resume_anchor_session", columns: ["session_id"] },
     { table: "approval_nonce", name: "idx_approval_nonce_expires", columns: ["expires_at_ms"] },
     { table: "user_input_acceptance", name: "idx_user_input_acceptance_session", columns: ["session_id", "state", "accepted_at_ms"] },
@@ -17,6 +18,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "snapshot_blob", name: "idx_snapshot_blob_created", columns: ["created_at"] },
     { table: "file_history_version", name: "idx_file_history_version_blob", columns: ["blob_hash"] },
     { table: "file_history_boundary_file", name: "idx_file_history_bf_key", columns: ["scope", "key_hash"] },
+    { table: "file_history_boundary", name: "uq_file_history_boundary_seq", columns: ["scope", "publish_seq"], unique: true },
     { table: "file_history_blob", name: "idx_file_history_blob_created", columns: ["created_at"] },
     { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
     { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
@@ -24,6 +26,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "workflow_park_decision", name: "idx_wfparkdec_host", columns: ["host_session_id"] },
     { table: "workflow_park_decision", name: "idx_wfparkdec_run", columns: ["run_id"] },
     { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
+    { table: "workflow_completion_inbox", name: "uq_wfinbox_seq", columns: ["seq"], unique: true },
     { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
     { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },
     { table: "shared_memory_store", name: "idx_shared_memory_store_scope", columns: ["scope_key", "store_id"] },

package/dist/plugins/schema-live-columns.d.ts

@@ -1,20 +1,29 @@
 /**
- * 库里**实际**的列集 —— 唯一读者([ref] 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
+ * 库里**实际**的列册 —— 唯一读者([ref] 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
  * 缺这条索引的列」也读它)。叶子模块:不值依赖任何模块(列册探针那边经录制驱动 / 建表腿值依赖 `ensure-index.ts`,读者若住在那边,
  * `ensure-index.ts` 读它就是一个运行时环)。方言词是 `ensure-index.ts` 的闭集(类型边,擦除)。
+ *
+ * 一个读者、一次读:同一张目录视图的同一批行同时回答「哪些列在」(键)与「它允许 NULL 吗」(值)。两方言的「读哪张表 / 哪个 schema」
+ * (MySQL 协议 = 连接上的库;PG = `search_path` 次序里的首次命中)只在这里写一遍;只问列在不在的读者(索引补建、退役 schema 判)用 `Map.has`,不看值。
  */
 import type { SqlDialect } from "./sql-driver.js";
 /** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
 export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/** 库里一列的实况。`nullable` = 目录的 `is_nullable` 是 `YES`(两个目录都是 `YES` / `NO` 的闭集;读数里没有 `n` 或不是 `YES` ⇒ 不算可空,只有目录明说可空的列才被判)。 */
+export interface LiveColumn {
+    readonly nullable: boolean;
+}
+/** 库里实际的列册:表名 → (列名 → 实况)。读者交出的是只读视图(消费方只问 `has` / `get`)。 */
+export type LiveColumns = ReadonlyMap<string, ReadonlyMap<string, LiveColumn>>;
 /**
- * 库里实际的列集(表名 → 列名集合)。
+ * 库里实际的列册(表名 → 列名 → { nullable })。
  *
  * 🔴 **PG 侧读的是「查询真正会解析到的那个关系」,不是 `current_schema()`**(codex 对抗复审本轮 [medium]
  * 采纳):店里的 SQL 全是**不限定 schema** 的裸表名,它按 `search_path` **逐个** schema 解析,命中第一个;
  * 而 `current_schema()` 只是路径的第一段。两者不等的部署是真的存在(角色的 `search_path` 配了多段),那时
  * 只读第一段会让探针对「表其实住在路径后段、而且缺列」这一形**完全沉默**。⇒ 按 `current_schemas(false)`
- * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表。MySQL 协议没有这个概念(库 = 连接上的
- * `DATABASE()`),那条臂一个字不变。
+ * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表(列在不在、可不可空对同一张表说话)。MySQL 协议没有这个概念(库 = 连接上的
+ * `DATABASE()`),那条臂只有选择列多一格。
  */
-export declare function readLiveColumns(read: SchemaProbeRead, dialect: SqlDialect): Promise<Map<string, Set<string>>>;
+export declare function readLiveColumns(read: SchemaProbeRead, dialect: SqlDialect): Promise<LiveColumns>;
 //# sourceMappingURL=schema-live-columns.d.ts.map