@sema-agent/server 7.148.0 → 7.150.0

package/dist/plugins/schema-consistency.js

@@ -1,7 +1,8 @@
 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 stripComments(sql) {
     let out = "";
@@ -263,6 +264,117 @@ export function diffSchema(expected, live) {
     }
     return out;
 }
+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":
@@ -337,34 +449,104 @@ export function describeMismatchedTables(dialect, 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(read, dialect, mismatches) {
+    if (!needsStatements(mismatches))
+        return [];
+    const { stopThenStartMigrations } = await import("./one-time-migrations.js");
+    const owed = [];
+    for (const m of stopThenStartMigrations()) {
+        let owes;
+        try {
+            owes = await m.owedOn(read, dialect);
+        }
+        catch (err) {
+            owed.push(`  - ${m.id}: ${m.reason} (whether this database still owes it could not be read — ${err instanceof Error ? err.message : String(err)} — so it is listed)`);
+            continue;
+        }
+        if (owes)
+            owed.push(`  - ${m.id}: ${m.reason}`);
+    }
+    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 (owed.length > 0) {
+        steps.push([
+            "Stop-then-start one-time migrations this database still owes: this build runs them itself on its first boot (no statement from you), and each refuses to start — writing nothing — while a run on this database has",
+            "heartbeated within REAP_RUN_STALE_SEC held by a replica not registered as knowing that migration (a replica of a release that predates replica registration never is).",
+            ...owed,
+            stopThenStartAction(),
+        ]);
+    }
+    steps.push([owed.length > 0 ? "Start this version; the stop-then-start migrations above run on that boot." : "Start this version."]);
+    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.",
         "",
+        ...(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(read, dialect, mismatches) {
+    const checklist = await describeUpgradeChecklist(read, dialect, 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 timer;
+    try {
+        const work = (async () => {
+            const mismatches = await statementBearing(await expectedTableShapes(dialect), await readLiveColumns(read, dialect), dialect);
+            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(read, dialect, mismatches)).join("\n")}`;
+        })();
+        work.catch(() => undefined);
+        const expired = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`no answer within ${deadlineMs} ms`)), deadlineMs);
+            timer.unref?.();
+        });
+        return 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);
+    }
+}
+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(read, dialect, 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`)。 */
@@ -20,11 +21,11 @@ export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
 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):",
@@ -11,16 +12,23 @@ export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
     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: [], tightened: [] }));
-        if (missingOnly.length > 0)
-            return sc.describeMismatchedTables(d, 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(read, 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/serving-requirement.d.ts

@@ -0,0 +1,49 @@
+/**
+ * **起服准入**(SQL 两方言;常设)—— 「这只库要求每一只服务者有哪些能力」一张表,与本构建的能力名单比:库上记着本构建没有的能力 ⇒ 拒启,本构建不迁移、不服务。
+ *
+ * ## 律
+ *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 两词闭集
+ *    {@link SERVING_REQUIREMENT_STATES}:`pending`(要求方已认领、还没做任何不兼容写)/ `in_force`(不兼容写已开始或已完成)。两态都要求;读出词表外的词 ⇒ 当作 `in_force`,拒句点名那一行。
+ *  · 判据 = `knows(本构建, M)`(`knowsCapability`,与停-迁-起证据读法同一只谓词);发布线不进判据(同版本串的构建可以能力不同)。
+ *  · 两次读,同一判据:SQL 一次性迁移段头、取迁移锁之前读一次(锁外预读);取到迁移锁之后、第一步迁移之前在锁连接上再读一次(锁内复核)——
+ *    在本进程等锁时握着锁的那一只若写下了要求,锁内复核读得到。拒 ⇒ 本构建不迁移;库上只留本进程的登记行(段头第一步)。
+ *  · 表不在(跳过了 `ensureSchema()` 的嵌入方)⇒ 拒:证不出「没有要求」不是「没有要求」。
+ *  · 本构建不写本表(没有写者;写者随之后的停-迁-起迁移来)—— 表空 ⇒ 准入恒过。装早一版:从本版起的每一只构建都读它,之后写下的要求挡得住它们重启开服。
+ *
+ * ## 射程(如实)
+ * 挡的是**起服者**:已在服务的副本不再读本表;准入与开服之间的停顿也不在它的射程里。早于本表那一版的构建不读本表。
+ */
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { type ReplicaRegistration } from "./replica-registration.js";
+import { type UnmetServingRequirement } from "./stop-then-start-sentence.js";
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+/** 表名。 */
+export declare const SERVING_REQUIREMENT_TABLE = "serving_requirement";
+/** 要求行的状态词(闭集)。 */
+export declare const SERVING_REQUIREMENT_STATES: readonly ["pending", "in_force"];
+export type ServingRequirementState = (typeof SERVING_REQUIREMENT_STATES)[number];
+/** 拒启码(确定的拒启表态;继承 {@link StoreBootRefusalError}:开库等待窗不重试、降级臂不吞)。 */
+export declare const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
+/** 拒因闭集:库要求的能力本构建没有 / 准入读的表不在库里(证不出)。 */
+export type ServingRequirementRefusalReason = "capability_missing" | "table_absent";
+/** 建表句(两方言;幂等)。中央建表语句读它(`tidb-pool.ts` / `pg-pool.ts`)。 */
+export declare function servingRequirementDdl(dialect: SqlDialect): string;
+/** 起服准入拒。 */
+export declare class ServingRequirementUnmetError extends StoreBootRefusalError {
+    readonly reason: ServingRequirementRefusalReason;
+    /** `capability_missing`:本构建没有的那几行(按能力名排序);`table_absent`:空。 */
+    readonly unmet: readonly UnmetServingRequirement[];
+    /** `table_absent`:不在库里的那几张表;`capability_missing`:空。 */
+    readonly absentTables: readonly string[];
+    readonly code = "config.serving_requirement_unmet";
+    constructor(reason: ServingRequirementRefusalReason, 
+    /** `capability_missing`:本构建没有的那几行(按能力名排序);`table_absent`:空。 */
+    unmet: readonly UnmetServingRequirement[], 
+    /** `table_absent`:不在库里的那几张表;`capability_missing`:空。 */
+    absentTables: readonly string[], releaseLine: string);
+}
+/** 准入读的两张表(本表与段头写的登记表)都在库里;不在 ⇒ 拒(`table_absent`),点名公开序列。 */
+export declare function assertReplicaTablesPresent(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration): Promise<void>;
+/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。纯读;两方言同一句(无占位符)。 */
+export declare function assertServingRequirementsMet(db: SqlExec, me: ReplicaRegistration): Promise<void>;
+//# sourceMappingURL=serving-requirement.d.ts.map

package/dist/plugins/serving-requirement.js

@@ -0,0 +1,53 @@
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { REPLICA_REGISTRATION_TABLE, knowsCapability } from "./replica-registration.js";
+import { servingRequirementUnmetSentence } from "./stop-then-start-sentence.js";
+export const SERVING_REQUIREMENT_TABLE = "serving_requirement";
+export const SERVING_REQUIREMENT_STATES = ["pending", "in_force"];
+export const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
+export function servingRequirementDdl(dialect) {
+    return dialect === "mysql"
+        ? `CREATE TABLE IF NOT EXISTS ${SERVING_REQUIREMENT_TABLE} (migration_id VARCHAR(16) NOT NULL PRIMARY KEY, state VARCHAR(16) NOT NULL, required_at_ms BIGINT NOT NULL) COLLATE utf8mb4_bin`
+        : `CREATE TABLE IF NOT EXISTS ${SERVING_REQUIREMENT_TABLE} (migration_id VARCHAR(16) COLLATE "C" NOT NULL PRIMARY KEY, state VARCHAR(16) COLLATE "C" NOT NULL, required_at_ms BIGINT NOT NULL)`;
+}
+export class ServingRequirementUnmetError extends StoreBootRefusalError {
+    reason;
+    unmet;
+    absentTables;
+    code = SERVING_REQUIREMENT_UNMET_CODE;
+    constructor(reason, unmet, absentTables, releaseLine) {
+        super(servingRequirementUnmetSentence(SERVING_REQUIREMENT_UNMET_CODE, reason, unmet, absentTables, releaseLine));
+        this.reason = reason;
+        this.unmet = unmet;
+        this.absentTables = absentTables;
+        this.name = "ServingRequirementUnmetError";
+    }
+}
+export async function assertReplicaTablesPresent(db, dialect, me) {
+    const scope = dialect === "mysql" ? "DATABASE()" : "current_schema()";
+    const absent = [];
+    for (const table of [REPLICA_REGISTRATION_TABLE, SERVING_REQUIREMENT_TABLE]) {
+        const { rows } = await db.query(`SELECT 1 AS present FROM information_schema.tables WHERE table_schema = ${scope} AND table_name = '${table}'`);
+        if (rows.length === 0)
+            absent.push(table);
+    }
+    if (absent.length > 0)
+        throw new ServingRequirementUnmetError("table_absent", [], absent, me.releaseLine);
+}
+function stateOf(cell) {
+    const word = String(cell);
+    return SERVING_REQUIREMENT_STATES.includes(word) ? { state: word, word } : { state: "in_force", word };
+}
+export async function assertServingRequirementsMet(db, me) {
+    const { rows } = await db.query(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`);
+    const unmet = [];
+    for (const r of rows) {
+        const migration = String(r["migration_id"]);
+        if (knowsCapability(me.capabilities, migration))
+            continue;
+        const { state, word } = stateOf(r["state"]);
+        unmet.push({ migration, state, word });
+    }
+    if (unmet.length > 0)
+        throw new ServingRequirementUnmetError("capability_missing", unmet, [], me.releaseLine);
+}
+//# sourceMappingURL=serving-requirement.js.map

package/dist/plugins/session-placement.d.ts

@@ -37,8 +37,9 @@ import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementReco
 import type { ForkPlacement } from "./session-fork.js";
 /**
  * 三只持久会话店(SQL 两孪生 + local 后端)的**会话耐久声明**(core `SessionStore.durability`:未 placed 的会话活不活过进程重启)——
- * **单源**:三处声明(两孪生类上的顶层 `durability`、`LocalBackend` 交给店的顶层 `durability`)与委派分区的 {@link SESSION_PLACEMENTS}
- * 引用的都是这一只常量,源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
+ * **单源**:两孪生类上的顶层 `durability` 与委派分区的 {@link SESSION_PLACEMENTS} 引用的都是这一只常量;local 后端交给两半店(会话店顶层、
+ * 检查点店)的声明由 `local-store-declaration.ts` 的读者定,它的「店型的设计声明」一臂就是这一只常量(运维声明易失 / 店落在调用方自己那块易失盘上 ⇒ `process-local`)。
+ * 源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
  *
  * 为什么必须声明:core 的静态装配对**缺席**折 `"process-local"`(它不能替没表态的店猜),接线清单 `session.store` 与起服自检读的就是它 ——
  * 不声明 ⇒ 一个真持久的 SQL 部署读成「重启即丢」,没有任何一处报错。依据同下面分区声明那一段:两孪生的会话史落在 `session_meta` + `session_event` 两张真表,
@@ -47,8 +48,8 @@ import type { ForkPlacement } from "./session-fork.js";
  */
 export declare const SESSION_DURABILITY: "durable";
 /**
- * 三只持久会话店的 placement **声明**(core `SessionStore.placements`):两支 SQL 孪生(类上的字段)与 local 后端
- * (`LocalBackend` 装配 `LocalSessionStore` 时交进去 —— 值与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`,类上的字段)。local 后端装配 `LocalSessionStore` 时交进去的分区声明与它同形,
+ * 耐久取 local 店的那一份声明(`local-store-declaration.ts`;设计声明一臂与这里同值,与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
  *
  * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
  * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在

package/dist/plugins/shell-sentinel-owner-m48.d.ts

@@ -1,3 +1,4 @@
+import type { SqlDialect } from "./sql-driver.js";
 /**
  * 一次性迁移 **M48** 的唯一属主(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表;随 M48 删整个文件)。
  *
@@ -13,8 +14,29 @@
  * 改写面 = 曾放那一格的读面读属主的那几处:SQL `session_meta` / `task_run` / `leader_run` 的 `owner` 列;local 会话元数据边档那一格的 `owner`、
  * `FileRunStore` 的 run 行 `owner`(local 没有 leader run 店)。不改的(如实):规则行(存在哨兵键下的规则此前也不对无主体任务生效,改键 = 放宽,不做)、
  * 收件箱条目 / 问账行 / 检查点 scope(这些读面从没放过那一格)。
+ *
+ * **有身份边界的部署不改写,但不零信号**:部署形读数取自**起服的那一个进程**的配置,而改写落在整只库 / 数据根上、不可逆 ⇒ 同一只库 / 根被身份配置不同的进程打开
+ * (`run-local` 不带服务凭据 / 桥、嵌入方先于验签器装配的起服序列、连着共享库的临时进程)时,一样身份键都不带的那个进程先起,会替有边界的服务进程把行改成无主(边界是任一身份来源在的并 —— 改写只在一样都没有时发生)。
+ * 有边界的进程自己只看见「零改写」,不数一数就不知道库里还留着多少行 ⇒ 那一臂对**同一批改写面**用**同一个比较**数一遍(不写,不改),读数 {@link ShellSentinelOwnerRowsRetained}
+ * 逐面列非零的计数,起服日志一行 warn(`shell_sentinel_rows_retained`)。比较只有一份:SQL 的 {@link shellSentinelOwnerWhereM48}(改写的 `UPDATE` 与计数的 `SELECT COUNT(*)` 共用),
+ * local 的 {@link isShellSentinelOwnerM48}(会话元数据格与 run 行的改写和计数共用)。
  */
 export declare const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
 /** SQL 腿改写 `owner` 列的表(曾放那一格的读面读属主的表;local 腿的对应面见文件头)。 */
 export declare const SHELL_SENTINEL_OWNER_TABLES_M48: readonly ["session_meta", "task_run", "leader_run"];
+/** 改写面的词(留存读数与日志的逐面计数键):SQL = 表名;local 腿借同一组词 —— `session_meta` = 会话元数据格、`task_run` = run 行(local 没有 leader run 店 ⇒ 不出 `leader_run`)。 */
+export type ShellSentinelOwnerSurfaceM48 = (typeof SHELL_SENTINEL_OWNER_TABLES_M48)[number];
+/** 留存读数的一只:有身份边界的部署上,这一面还留着多少行哨兵属主(只列非零的面)。 */
+export interface ShellSentinelOwnerRowsRetained {
+    readonly surface: ShellSentinelOwnerSurfaceM48;
+    readonly rows: number;
+}
+/**
+ * SQL 腿「这一行是哨兵属主」的比较(**唯一一份**;改写的 `UPDATE … SET owner = NULL WHERE <此>` 与留存计数的 `SELECT COUNT(*) … WHERE <此>` 共用,绑定参数同为 {@link SHELL_SENTINEL_OWNER_M48})。
+ * 值**逐字节**比:MySQL 协议的 `utf8mb4_bin` 是 PAD SPACE(`'a' = 'a '`),普通等值会把只差尾空格的另一位属主(合法主体名)也当哨兵 ——
+ * 与 M17 / M18 的 CAS 同一写法 `CAST(… AS BINARY)`;PG `text` 等值本就逐字节。
+ */
+export declare function shellSentinelOwnerWhereM48(dialect: SqlDialect): string;
+/** local 腿「这一行 / 格的属主是哨兵」的比较(**唯一一份**;会话元数据格与 run 行的改写、留存计数共用 —— 严格相等,与 SQL 腿的逐字节比同义)。 */
+export declare function isShellSentinelOwnerM48(owner: string | null | undefined): boolean;
 //# sourceMappingURL=shell-sentinel-owner-m48.d.ts.map

package/dist/plugins/shell-sentinel-owner-m48.js

@@ -1,3 +1,9 @@
 export const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
 export const SHELL_SENTINEL_OWNER_TABLES_M48 = ["session_meta", "task_run", "leader_run"];
+export function shellSentinelOwnerWhereM48(dialect) {
+    return dialect === "mysql" ? "CAST(owner AS BINARY) = CAST(? AS BINARY)" : "owner = $1";
+}
+export function isShellSentinelOwnerM48(owner) {
+    return owner === SHELL_SENTINEL_OWNER_M48;
+}
 //# sourceMappingURL=shell-sentinel-owner-m48.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * 「停-迁-起」那一段的**唯一属主**。
+ *
+ * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
+ * 起服时由守卫判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`one-time-migrations.ts` 的 `readOlderReplicaEvidence`):
+ * 判活窗内(`REAP_RUN_STALE_SEC`,收割器判 run 持有者还活着的同一个窗)心跳过的 `running` run,持有者没有登记为知道这条迁移(`replica-registration.ts`)。
+ * 四只守卫(M40 · M41 · M42 · M51)的拒句和起服列册对账的升级清单**说同一件事**:先停光更早版本的副本、等满判活窗、再起本版。
+ * 这件事的句子只在这里写一遍:证据一段({@link olderReplicaEvidenceSentence})与动作一段({@link stopThenStartAction});各守卫只讲「为什么这一条要停」。
+ * 起服准入(`serving-requirement.ts`:库上记着本构建没有的能力 ⇒ 拒启)的拒句同属这一族,也在这里({@link servingRequirementUnmetSentence})。
+ *
+ * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
+ */
+/** 证据里一只登记过、却没有这条迁移能力的持有者(归因用:点名它是谁)。 */
+export interface OlderReplicaHolder {
+    readonly instanceId: string;
+    readonly releaseLine: string;
+    readonly hostName: string;
+    readonly pid: number;
+    /** 它持有的、判活窗内心跳过的 `running` run 数。 */
+    readonly runs: number;
+}
+/**
+ * 停-迁-起守卫的证据(纯数据):判活窗内心跳过、持有者没有登记为知道 {@link migration} 的 `running` run。
+ * 登记为知道它的持有者的 run 不在这里(它们不是旧形写者);登记只作归因,不判活。
+ */
+export interface OlderReplicaEvidence {
+    readonly migration: string;
+    /** 算进证据的 run 总数(= {@link unregisteredRuns} + 各 {@link registeredWithout} 的 `runs`)。 */
+    readonly liveRuns: number;
+    readonly windowSec: number;
+    /** 全停之后可以再起的最早时刻(ISO;= 最新心跳 + 判活窗;读不出最新心跳 ⇒ 现在 + 窗,上界)。 */
+    readonly restartAfter: string;
+    /** 同一时刻的人读形(带「离现在还有几秒」)。 */
+    readonly after: string;
+    /** 持有者没有登记行(或没有持有者)的 run 数。 */
+    readonly unregisteredRuns: number;
+    /** 登记了而能力名单里没有这条迁移的持有者,逐只点名。 */
+    readonly registeredWithout: readonly OlderReplicaHolder[];
+}
+/** 证据一段(各守卫拒句与 M43 的读数共用;句子不含时刻 —— 时刻在动作段)。 */
+export declare function olderReplicaEvidenceSentence(e: OlderReplicaEvidence): string;
+/**
+ * 动作段:停光 → 等窗 → 再起。`after` = 全停之后可以再起的最早时刻(守卫读到的最新心跳 + 判活窗,人读形);
+ * 缺席 ⇒ 读不到具体心跳(列册对账的清单:此刻没有守卫在判),只说「等满判活窗」。
+ */
+export declare function stopThenStartAction(after?: string): string;
+/** 起服准入里一行本构建没有的要求(`state` = 判读的态,词表外的词读作 `in_force`;`word` = 库里存的原词)。 */
+export interface UnmetServingRequirement {
+    readonly migration: string;
+    readonly state: "pending" | "in_force";
+    readonly word: string;
+}
+/** 起服准入的拒句(`reason` 闭集两词;码由调用方交,本模块零 import)。 */
+export declare function servingRequirementUnmetSentence(code: string, reason: "capability_missing" | "table_absent", unmet: readonly UnmetServingRequirement[], absentTables: readonly string[], releaseLine: string): string;
+//# sourceMappingURL=stop-then-start-sentence.d.ts.map

package/dist/plugins/stop-then-start-sentence.js

@@ -0,0 +1,51 @@
+export function olderReplicaEvidenceSentence(e) {
+    const parts = [];
+    if (e.unregisteredRuns > 0)
+        parts.push(`${e.unregisteredRuns} by replicas with no registration on this database (a release that predates replica registration, or a process that skipped the start sequence)`);
+    for (const h of e.registeredWithout)
+        parts.push(`${h.runs} by instance ${h.instanceId} (release ${h.releaseLine}, host ${h.hostName}, pid ${h.pid}), registered without it`);
+    return (`${e.liveRuns} running run(s) on this database heartbeated within the last ${e.windowSec}s (REAP_RUN_STALE_SEC), held by replicas not registered as knowing one-time migration ${e.migration}` +
+        ` (${parts.join("; ")})`);
+}
+export function stopThenStartAction(after) {
+    return ("Stop every replica of the earlier version, then start this version (stop, migrate, start — this release cannot be rolled across replicas of both versions). " +
+        (after === undefined
+            ? "Wait out the heartbeat window (REAP_RUN_STALE_SEC) after the last replica stops, then start this version."
+            : `If every replica is already stopped, those are the runs they left behind: start this version again after ${after}`));
+}
+function requirementClause(r) {
+    switch (r.state) {
+        case "pending":
+            return `${r.migration} (pending: a newer build recorded it and has not changed any data for it yet)`;
+        case "in_force":
+            return r.word === "in_force"
+                ? `${r.migration} (in force: data has been changed for it)`
+                : `${r.migration} (state "${r.word}", which this build does not know — read as in force)`;
+        default: {
+            const unhandled = r.state;
+            throw new Error(`stop-then-start-sentence: unknown requirement state ${String(unhandled)}`);
+        }
+    }
+}
+export function servingRequirementUnmetSentence(code, reason, unmet, absentTables, releaseLine) {
+    switch (reason) {
+        case "capability_missing": {
+            const inForce = unmet.filter((r) => r.state === "in_force").map((r) => r.migration);
+            return (`${code} (reason: capability_missing): this database requires every serving replica to have ${unmet.map(requirementClause).join(", ")}; this build (release ${releaseLine}) does not. ` +
+                "No one-time migration ran and no stored data was changed (the section head only registered this replica and removed registrations of other replicas older than 90 days). " +
+                `Start a build that has ${unmet.map((r) => r.migration).join(", ")}.` +
+                (inForce.length === 0
+                    ? ""
+                    : ` Only to roll back on purpose, after handling the data of that migration: ${inForce.map((m) => `DELETE FROM serving_requirement WHERE migration_id = '${m}';`).join(" ")}`));
+        }
+        case "table_absent":
+            return (`${code} (reason: table_absent): this database has no ${absentTables.join(" / ")} table — the serving requirements recorded there cannot be read, ` +
+                'and an unreadable requirement is not "no requirement", so this build refuses to start. Nothing was written. ' +
+                "Open the store with the public sequence createStoreBackend() → ensureSchema() → runOneTimeMigrations(): ensureSchema() creates these tables.");
+        default: {
+            const unhandled = reason;
+            throw new Error(`stop-then-start-sentence: unknown refusal reason ${String(unhandled)}`);
+        }
+    }
+}
+//# sourceMappingURL=stop-then-start-sentence.js.map