@sema-agent/server 7.150.0 → 7.152.0

package/dist/plugins/snapshot-bucket-presence.js

@@ -1,5 +1,6 @@
 import { buildDisplaySafeUrl } from "../trace/redact.js";
-import { MinioBlobBackend } from "./blob-backend.js";
+import { MinioBlobBackend, sessionBlobKeyPrefixOf } from "./blob-backend.js";
+import { workspaceSnapshotPrefixOf } from "../workspace-space.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
@@ -10,6 +11,8 @@ export const SNAPSHOT_BUCKET_ROLES = {
         defaultName: SESSION_SNAPSHOT_BUCKET_DEFAULT,
         consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)",
         createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment",
+        probeOp: "boot-probe/session:LIST",
+        probePrefix: (store) => sessionBlobKeyPrefixOf(store, "legacy-blobs"),
     },
     workspace: {
         noun: "workspace snapshot bucket",
@@ -17,6 +20,8 @@ export const SNAPSHOT_BUCKET_ROLES = {
         defaultName: WORKSPACE_SNAPSHOT_BUCKET_DEFAULT,
         consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing",
         createHint: "",
+        probeOp: "boot-probe/workspace:LIST",
+        probePrefix: (store) => `${workspaceSnapshotPrefixOf(store)}/`,
     },
 };
 export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
@@ -34,7 +39,8 @@ export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs, role = "s
 }
 export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
 export async function ensureSnapshotBucket(store, waitMs, logger, clock, role = "session") {
-    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
+    const roleRow = SNAPSHOT_BUCKET_ROLES[role];
+    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), keyPrefix: roleRow.probePrefix(store), ops: { list: roleRow.probeOp } });
     let verdict;
     try {
         verdict = await openWithinWait(async () => {

package/dist/plugins/sql-driver.d.ts

@@ -423,7 +423,8 @@ export declare function connectJudged<R>(db: SqlDriver, judge: (facts: SqlEngine
  * (`getConnection` → 守卫租约上执行 → 归还,被守卫销毁的不归还)。语句契约不变:参数原样到连接,结果是 mysql2 的 `[rows, fields]` 元组,`{ sql, timeout }` 对象形
  * 一并支持(原样交给连接);池的其余成员(`end` / `execute` / `on` …)原样转给底池,返回底池自身的方法(`on` 之类)返回本包装体 —— 链式调用不会逃出守卫。
  * 生产池(`createTidbPool`)恒是它;mysql2 自己的 `pool.query` 对只读类错误(1290 / 1792 / 1836)的销毁收在同一张表里({@link isConnectionUnusableError}),不丢。
- * 不覆盖 `pool.execute`(预备语句:今天只有任务附件店一处,语句是小定长行,碰不到语句墙)。
+ * 不覆盖 `pool.execute`(预备语句:今天只有任务附件店一处,语句是小定长行,碰不到语句墙)—— 它与其余原样转给底池的成员一样,只给拒绝打驱动出身记号。
+ * **驱动出身记号**(`error-origin.ts` 的 `driver` 一词)是这只池座的第二件事:借连接、守卫租约上的语句与事务动词、原样转给底池的承诺,它们的拒绝都打记号(只记,不改对象、不记日志、不改控制流)。
  */
 export declare function createCloseAwarePool(pool: MySqlPool): MySqlPool;
 /** MySQL-protocol driver (TiDB / MySQL / MariaDB — `dialect` is the SQL TEXT axis, `facts.engine` the

package/dist/plugins/sql-driver.js

@@ -3,6 +3,8 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
 import { writeLogText } from "../observability/logger.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
+import { markErrorOrigin } from "./error-origin.js";
+import { storeBoundaryFault } from "../terminal.js";
 export class SqlStatementDeadlineExceeded extends Error {
     deadlineMs;
     constructor(deadlineMs) {
@@ -245,7 +247,8 @@ async function initMySqlSession(c) {
             await c.query("SET SESSION tidb_txn_mode = 'pessimistic'");
         }
         catch (err) {
-            throw refuseSession(`this TiDB session is in "${txnMode}" transaction mode and SET SESSION tidb_txn_mode='pessimistic' was rejected (${err.message})`);
+            storeBoundaryFault(err, "sql-driver.initMySqlSession");
+            throw refuseSession(`this TiDB session is in "${txnMode}" transaction mode and SET SESSION tidb_txn_mode='pessimistic' was rejected`);
         }
         txnMode = await mysqlVar(c, "SELECT @@tidb_txn_mode AS v");
         if (txnMode !== "pessimistic") {
@@ -342,6 +345,7 @@ function leaseOf(raw) {
                 return await run();
             }
             catch (err) {
+                markErrorOrigin(err, "driver");
                 if (isConnectionUnusableError(err)) {
                     destroy();
                     BROKEN_LEASES.set(lease, { error: err });
@@ -375,7 +379,9 @@ function leaseOf(raw) {
     return lease;
 }
 export function createCloseAwarePool(pool) {
-    const lend = async () => leaseOf(await pool.getConnection());
+    const lend = async () => leaseOf(await pool.getConnection().catch((err) => {
+        throw markErrorOrigin(err, "driver");
+    }));
     const query = async (...args) => {
         const c = await lend();
         try {
@@ -396,12 +402,21 @@ export function createCloseAwarePool(pool) {
                 return member;
             return (...args) => {
                 const result = member.apply(target, args);
-                return result === target ? wrapper : result;
+                if (result === target)
+                    return wrapper;
+                return isThenable(result)
+                    ? result.then(undefined, (err) => {
+                        throw markErrorOrigin(err, "driver");
+                    })
+                    : result;
             };
         },
     });
     return wrapper;
 }
+function isThenable(v) {
+    return v !== null && (typeof v === "object" || typeof v === "function") && typeof v.then === "function";
+}
 export function mysqlDriver(pool) {
     const session = poolSession(pool);
     return {

package/dist/plugins/sql-errors.d.ts

@@ -109,7 +109,13 @@ export declare function isDeadlockError(dialect: SqlDialect, err: unknown): bool
 /** 引擎仲裁之后整段重来的**唯一**上界(全仓每一条「撞死锁就重来」的腿共用这一个数)。8 = 锁形并发套的并发度:缺行首写的 N 路竞争每轮至多多走一轮([ref] 读数 1 成 7 死锁)。 */
 export declare const DEADLOCK_RETRY_LIMIT = 8;
 /**
- * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError};用尽 / 其它错误原样抛。
+ * 语句源在一只**别人开的**事务里输了仲裁(例:文件历史的 scope 哨兵在锁读那一刻物理消失)—— 它不许自己回滚重开那只事务(段首的锁与判会随之丢掉),
+ * 只抛这一只;{@link retryOnDeadlock} 把它与死锁同读,从事务主人的段首整段重来(落定段、店自己的图事务同一条)。
+ */
+export declare class SqlArbitrationLostError extends Error {
+}
+/**
+ * 「引擎判了死锁 ⇒ 整段重来」的**唯一**写法:有界({@link DEADLOCK_RETRY_LIMIT}),判据 {@link isDeadlockError} ∪ {@link SqlArbitrationLostError};用尽 / 其它错误原样抛。
  * `attempt` 必须整段重做语义等价(读-判-写全在里面的一只事务,或一条幂等语句)。`alsoArbitrated`:店自己认的另一种仲裁产物(例:缺行首写撞主键 ——
  * 并发的另一只首写赢了,重读即走更新腿),与死锁同族、同一个上界。锁等待超时不在任何一族里(延迟信号,见 {@link isDeadlockError} 的注):它照抛。
  */
@@ -241,17 +247,16 @@ export declare function isDeploymentFaultError(err: unknown): boolean;
  */
 export declare function databaseAnswerCodesOf(dialect: SqlDialect, err: unknown): string | undefined;
 /**
- * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
- * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。
- * `row` = 哪一张表的哪一格、为谁写(进句子与运维日志);`wall` = 拒它的那堵墙({@link rowTooLargeWallOf} 的读数;提交腿按它选 413 的出路);
- * `dbMessage` = 引擎自己的那句(TiDB 的句子带着上限与这一行的实际字节数),截到 200 字符。
+ * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以驱动错上抛。
+ * `row` = 哪一张表的哪一格、为谁写(进句子);`wall` = 拒它的那堵墙({@link rowTooLargeWallOf} 的读数;提交腿按它选 413 的出路)。
+ * 句子是本仓的固定句,**不带**库的原句(店的出口只带原码 + 稳定句);库的那句(TiDB 的句子带上限与这一行的实际字节数)挂在 `cause` 上 ——
+ * 它出店时由店边界(`terminal.ts` 的 `storeBoundaryFault`:带词法内码的 typed 错原样过,`cause` 链上的驱动错就地换成边界形)记进 `at=store` 那一行、换成边界形。
  * 提交腿把它答成 413 `request.payload_too_large`(`http/submit-ctx.ts`);停驻那一拍它经引擎的错误座落进运维日志。
  */
 export declare class StoreRowTooLargeError extends Error {
     readonly row: string;
     readonly wall: RowTooLargeWall;
     readonly code: "store.row_too_large";
-    readonly dbMessage: string;
     constructor(row: string, cause: unknown, wall: RowTooLargeWall);
 }
 /** 店写口的翻译:{@link rowTooLargeWallOf} 认得出 ⇒ {@link StoreRowTooLargeError}(带那堵墙);其余原样交回(调用方 `throw` 它)。 */

package/dist/plugins/sql-errors.js

@@ -55,13 +55,15 @@ export function isDeadlockError(dialect, err) {
     return keyOf(err, "errno") === MYSQL_ER_LOCK_DEADLOCK_ERRNO || keyOf(err, "code") === MYSQL_ER_LOCK_DEADLOCK_CODE;
 }
 export const DEADLOCK_RETRY_LIMIT = 8;
+export class SqlArbitrationLostError extends Error {
+}
 export async function retryOnDeadlock(dialect, attempt, alsoArbitrated) {
     for (let tries = 0;; tries++) {
         try {
             return await attempt();
         }
         catch (err) {
-            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || alsoArbitrated?.(err) === true))
+            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || err instanceof SqlArbitrationLostError || alsoArbitrated?.(err) === true))
                 continue;
             throw err;
         }
@@ -214,16 +216,13 @@ export class StoreRowTooLargeError extends Error {
     row;
     wall;
     code = "store.row_too_large";
-    dbMessage;
     constructor(row, cause, wall) {
-        const dbMessage = (cause instanceof Error ? cause.message : String(cause)).replace(/[\u0000-\u001f\u007f]+/g, " ").slice(0, 200);
-        super(`${row} was refused by the database: the row is larger than the database stores in one row (${dbMessage}). ` +
+        super(`${row} was refused by the database: the row is larger than the database stores in one row. ` +
             "Shrink what the request carries inline (images / userAttachments), or raise the database's single-row limit " +
-            "(TiDB: performance.txn-entry-size-limit, or the tidb_txn_entry_size_limit variable on TiDB 7.6+; MySQL / MariaDB: max_allowed_packet)");
+            "(TiDB: performance.txn-entry-size-limit, or the tidb_txn_entry_size_limit variable on TiDB 7.6+; MySQL / MariaDB: max_allowed_packet)", { cause });
         this.row = row;
         this.wall = wall;
         this.name = "StoreRowTooLargeError";
-        this.dbMessage = dbMessage;
     }
 }
 export function rowTooLargeOrSelf(dialect, err, row) {

package/dist/plugins/sql-json-column.d.ts

@@ -347,7 +347,7 @@ export declare const readNonNullJsonValueColumn: JsonColumnReader<unknown>;
  * **一只 JSON 数组**的承载形读者(内容判据归各列自己的既有属主,这里只判承载形)。
  *
  * 🔴 为什么在属主里而不是各店各写一遍([ref] 车③a 把车② 的店内私有形上收):今天有三个消费方
- * (checkpoint 的 `rule_suggestions` / `pending_steer_queue`、memory-engine 的 `embedding`),判据逐字
+ * (checkpoint 的 `pending_steer_queue`、image-index 的 `bands`、memory-engine 的 `embedding`),判据逐字
  * 相同,而「这一格是不是一只数组」恰好是坏体四形的落点 —— 三份拷贝迟早有一份忘了判 `null` 字面。
  */
 export declare const readJsonArrayColumn: JsonColumnReader<unknown[]>;

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

@@ -2,13 +2,14 @@
  * 「停-迁-起」那一段的**唯一属主**。
  *
  * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
- * 起服时由守卫判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`one-time-migrations.ts` 的 `readOlderReplicaEvidence`):
+ * 起服时由守卫段判 —— 库上有「不知道这条迁移的副本还在服务」的证据 ⇒ 拒启、一字节不写。证据只有一种读法(`stop-then-start.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})。
+ * 起服准入(`serving-requirement.ts`:库上记着本构建没有的能力 ⇒ 拒启)的拒句同属这一族,也在这里({@link servingRequirementUnmetSentence});
+ * 起服拒句升级清单里「这只库要求本构建没有的能力」一步的句子同在这里({@link unmetRequirementChecklistStep})。
  *
- * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
+ * 叶子模块:零 import(守卫段、各条的拒句、M42 的拒句文件、起服准入与列册对账都静态 import 它,不成环)。
  */
 /** 证据里一只登记过、却没有这条迁移能力的持有者(归因用:点名它是谁)。 */
 export interface OlderReplicaHolder {
@@ -47,9 +48,14 @@ export declare function stopThenStartAction(after?: string): string;
 /** 起服准入里一行本构建没有的要求(`state` = 判读的态,词表外的词读作 `in_force`;`word` = 库里存的原词)。 */
 export interface UnmetServingRequirement {
     readonly migration: string;
-    readonly state: "pending" | "in_force";
+    readonly state: "in_force";
     readonly word: string;
 }
+/**
+ * 起服拒句**升级清单**里的那一步(排在 `ALTER` 一步之前;多行,第一行是步骤首句):这只库要求本构建没有的能力 —— 照清单补完语句也不会让本构建能在这里服务。
+ * `unmet` 空 ⇒ 调用方不出这一步。`unreadable` 在 ⇒ 读要求表抛了:照出这一步并如实说没读到(多停一次,不漏停)。
+ */
+export declare function unmetRequirementChecklistStep(unmet: readonly UnmetServingRequirement[], unreadable?: string): 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

@@ -15,11 +15,9 @@ export function stopThenStartAction(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} (in force: a build that has it was admitted on this database and may have changed data for it)`
                 : `${r.migration} (state "${r.word}", which this build does not know — read as in force)`;
         default: {
             const unhandled = r.state;
@@ -27,17 +25,23 @@ function requirementClause(r) {
         }
     }
 }
+const rollbackDelete = (migration) => `DELETE FROM serving_requirement WHERE migration_id = '${migration}';`;
+export function unmetRequirementChecklistStep(unmet, unreadable) {
+    if (unreadable !== undefined) {
+        return [`Whether this database requires a capability this build lacks could not be read (${unreadable}); read serving_requirement before going on — a row this build does not have means it must not serve here.`];
+    }
+    return [
+        `This database requires every serving replica to have ${unmet.map(requirementClause).join(", ")}; this build does not, and must not serve on it — the statements below do not make it safe.`,
+        `Start a build that has ${unmet.map((r) => r.migration).join(", ")} instead. Only to roll back on purpose, after handling the data of that migration: ${unmet.map((r) => rollbackDelete(r.migration)).join(" ")}`,
+    ];
+}
 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);
+        case "capability_missing":
             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(" ")}`));
-        }
+                `Start a build that has ${unmet.map((r) => r.migration).join(", ")}. ` +
+                `Only to roll back on purpose, after handling the data of that migration: ${unmet.map((r) => rollbackDelete(r.migration)).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. ' +

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

@@ -0,0 +1,109 @@
+/**
+ * **停-迁-起**(SQL 两方言;常设,不带窗)—— 一次性迁移登记表里每一条停-迁-起行的声明型、它唯一的判官、守卫段与证据读法。
+ *
+ * ## 它回答哪一问(只这一问)
+ * 「一只**已在服务**、不认迁移 M 的副本,在 M 之后写下的那一笔不兼容写,由谁挡?」—— 答案是一格闭集 {@link StopThenStartFence}(围栏类):
+ *  · `structural` —— 库挡:M 的第一笔改动是 DDL(就地改名 / 删退役列 / 按建表语句重建),更早副本点名旧对象的每一句不兼容写当场失败(先围后搬);
+ *  · `per-write` —— 写句挡:从 `fencedSince` 起的构建,点名的那几句写在同一句 / 同一事务里读起服要求行;`fencedSince` 严格早于 M 的引入版
+ *    (逐写围栏只对带这段代码的构建生效,所以必须早至少一版装入);
+ *  · `accepted` —— 没有人挡:`residual` 一句写明残余(MIGRATION 原样引),停光旧副本是唯一的补偿。
+ * 类取「从第一笔不兼容写起就成立」的那一种:晚于任何一笔搬运的 DDL 围栏不使本条成 `structural`;`per-write` 与 `structural` 同时成立 ⇒ 取 `structural`。
+ * **围栏类没有起服期的分臂**:三类在起服时同一只序 —— 守卫段读证据(有 ⇒ 拒)、各条在自己的第一笔不兼容写之前记一行起服要求(`serving-requirement.ts`)。
+ * 类只决定放行判据({@link judgeStopThenStart})、残余的披露与作者该选哪一形。
+ *
+ * ## 一份声明、一只判官
+ * 登记表(`one-time-migrations.ts` 的 `ONE_TIME_MIGRATIONS`)每一行**显式**写 `stopThenStart: StopThenStartRow | null`(缺键 = tsc 红,形门再红一次);
+ * `null` 只说「本条不声明停-迁-起」(不拒启、不进升级清单的停-迁-起一步),**不是**混跑安全的证明。判官只答「这份声明合不合本类的放行判据」;
+ * 读者两处:形门(全表,非空 ⇒ 红)与起服({@link assertStopThenStartDeclarations}:SQL 一次性迁移段**取连接之前**判本构建的每一条停-迁-起行,非空 ⇒ 抛构建缺陷,一句库语句都没发)。
+ *
+ * ## 守卫段在一切写之前
+ * {@link guardOwedStopThenStart} 在 SQL 一次性迁移段的锁内、准入复核之后、第一步迁移之前跑(`runSqlOneTimeMigrations`):按登记序逐条问「这只库还欠不欠」,
+ * 欠的读证据,任一有证据 ⇒ 抛那一条自己的拒(码与句是那一条的)—— 迁移段一字节没写,各拒句里的「Nothing was changed」由构造成立。迁移步里不再读证据。
+ *
+ * ## 证据读法(常设)
+ * {@link readOlderReplicaEvidence}:判活窗内心跳过的 `running` run(谓词 = run 店的 `runningHeartbeatPredicate` 的 `live` 一侧,与死亡判决同一只构造、同一个窗),
+ * 按持有者分组,减去登记为知道 M 的持有者(`replica-registration.ts`)。早于副本登记的副本不登记,只经它们持有的 run 心跳可见;没登记的持有者照算(保守)——
+ * 回滚到早于副本登记的构建、跳过公开序列的嵌入方、登记行过了留存视界的长寿进程会一直可能存在,所以这一读法不是过渡、没有删除日期。
+ * 它是观察谓词,不是存活证明:空闲的(零 `running` run)副本看不见;刚停的副本留下的 run 在窗内仍算(拒句给「全停之后何时再起」)。
+ * 「库上的副本够不够新」(服务下限)就是这一读法读空,不另立读口、不加版本常量。
+ *
+ * local 车道:数据根独占(起服锁只许一个进程)⇒ 没有混跑窗,守卫段与证据读法只在 SQL 腿。
+ */
+import type { StoreBootRefusalError } from "./store-contracts.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
+import type { SqlDialect } from "./sql-driver.js";
+import type { PendingShapeChange } from "./schema-consistency.js";
+import type { OlderReplicaEvidence } from "./stop-then-start-sentence.js";
+import { type ReplicaCapability } from "./replica-registration.js";
+/** 已在服务、不认本条的副本在本条之后那一笔不兼容写由谁挡(闭集;停-迁-起行必填)。 */
+export type StopThenStartFence = 
+/** 库挡:`fencedBy` 是本行 `shapeChanges` 里的一项(`rename` / `drop` / `rebuild`,不许 `add`),且是本条的第一笔改动。 */
+{
+    readonly kind: "structural";
+    readonly fencedBy: PendingShapeChange;
+}
+/** 写句挡:从 `fencedSince`(x.y.z,严格早于本行 `introducedIn`)起的构建,`statements` 点名的那几句写读起服要求行,`(本条, in_force)` 在 ⇒ 不写、响亮。 */
+ | {
+    readonly kind: "per-write";
+    readonly fencedSince: string;
+    readonly statements: string;
+}
+/** 没人挡:`residual` 一句写明残余(MIGRATION 原样引);停光旧副本是唯一的补偿。 */
+ | {
+    readonly kind: "accepted";
+    readonly residual: string;
+};
+/**
+ * 一条停-迁-起迁移的登记格(登记表里只写引用,判据与拒句的码在本条的迁移步旁边):
+ *  · `reason` —— 一句英文:更早版本的副本在迁移之后还会写什么、写了会怎样(= 为什么不能两版滚动;升级清单原样列给运维);
+ *  · `owedOn` —— **这只库还欠不欠本条**的唯一读法(只读、无参语句):守卫段先问它(不欠 ⇒ 不读证据),升级清单的停-迁-起一步只列它答「欠」的行;
+ *  · `refuse` —— 有证据时本条的拒(本条自己的码与句;`read` = 锁连接上的无参读口,拒句尾的库况 / 本条的计数从它读);守卫段调它,迁移步里不再读证据;
+ *  · `fence` —— 围栏类({@link StopThenStartFence})。
+ */
+export interface StopThenStartRow {
+    readonly reason: string;
+    readonly owedOn: (read: SchemaProbeRead, dialect: SqlDialect) => Promise<boolean>;
+    readonly refuse: (evidence: OlderReplicaEvidence, read: SchemaProbeRead, dialect: SqlDialect) => Promise<StoreBootRefusalError>;
+    readonly fence: StopThenStartFence;
+}
+/** 一条停-迁-起行连同判官要读的两格(登记表行的 `id` / `introducedIn` / `shapeChanges`;一次性迁移文件的 `stopThenStartMigrations()` 交出这一形)。 */
+export interface StopThenStartEntry extends StopThenStartRow {
+    readonly id: string;
+    readonly introducedIn: string;
+    readonly shapeChanges?: readonly PendingShapeChange[];
+}
+/** 停-迁-起证据读法的判活窗输入:= 本部署的 `REAP_RUN_STALE_SEC`(收割器判「这条 run 的持有者还活着」用的同一个窗)。 */
+export interface LiveRunWindowInput {
+    readonly liveRunWindowMs: number;
+}
+/** 证据读法要的读口(一次性迁移段的锁连接;只读)。 */
+export interface EvidenceDb {
+    rows(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
+}
+/**
+ * **唯一判官**:这份停-迁-起声明自相矛盾的清单(空 = 放行)。三类各自的放行判据(穷尽 `switch`,加第四类不处理 = tsc 红),外加三类共同的两条
+ * (名在能力名单里 —— 守卫读证据 ⇔ 名在名单里;缘由句不空)。纯函数。
+ */
+export declare function judgeStopThenStart(entry: StopThenStartEntry): readonly string[];
+/**
+ * **停-迁-起证据的唯一读法**(守卫段与 M43 的启用判同读;拒句与读数的句子属主 = `stop-then-start-sentence.ts`):判活窗内心跳过的 `running` run
+ * (run 店的 {@link runningHeartbeatPredicate} `live` 一侧 —— 收割器判活的同一只构造、同一个窗),按持有者(`task_run.instance_id`,建行铸、认领接管)分组,
+ * **减去登记为知道 `migrationId` 的持有者**(`knowsCapability`,与起服准入同一只判据)—— 剩下的 run 就是证据:持有者没有登记行(早于副本登记的副本、`NULL` 身份、
+ * 自传身份的嵌入方)或登记了而能力名单里没有这条迁移,照算(保守)。登记一半只作归因(点名持有者),**不判活**。
+ * 本进程此刻还在迁移段里、一条 run 都没起过 ⇒ 证据里只有别的进程。`task_run` 不在 ⇒ `undefined`。
+ * `migrationId` 在型上就要在能力名单里(`ReplicaCapability`):一条迁移读证据 ⇔ 它的名在名单里。
+ */
+export declare function readOlderReplicaEvidence(db: EvidenceDb, dialect: SqlDialect, input: LiveRunWindowInput, migrationId: ReplicaCapability): Promise<OlderReplicaEvidence | undefined>;
+/**
+ * 起服时的判官读者:本构建的每一条停-迁-起声明过 {@link judgeStopThenStart},任一条自相矛盾 ⇒ 抛(构建缺陷)。纯函数;唯一调用点 = SQL 一次性迁移段的入口
+ * (`runSqlOneTimeMigrations`),**在取连接之前** —— 抛出时这一次起服对库一句语句都没发(段头的登记、准入、取锁都还没开始)。
+ */
+export declare function assertStopThenStartDeclarations(entries: readonly StopThenStartEntry[]): void;
+/**
+ * **守卫段**(一次性迁移段的锁内、准入复核之后、第一步迁移之前;锁连接上;`entries` 已由调用方在取连接之前过了 {@link assertStopThenStartDeclarations}):
+ * 按登记序逐条 —— 不欠 ⇒ 跳过(不读证据);欠 ⇒ 读证据,有 ⇒ 抛那一条自己的拒({@link StopThenStartRow.refuse})。拒 ⇒ 迁移段一字节没写。
+ * 放行之后,各条在它**自己的**第一笔不兼容写之前记一行起服要求(`serving-requirement.ts` 的 `recordServingRequirement`;三类同记)—— 不在这里记:
+ * 本条若在本次起服里不欠,就没有那一笔写,也就不记。
+ */
+export declare function guardOwedStopThenStart(db: EvidenceDb, dialect: SqlDialect, input: LiveRunWindowInput, entries: readonly StopThenStartEntry[]): Promise<void>;
+//# sourceMappingURL=stop-then-start.d.ts.map

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

@@ -0,0 +1,104 @@
+import { REPLICA_CAPABILITIES, knowsCapability, readReplicaRegistrations } from "./replica-registration.js";
+import { compareReleaseTriples, releaseTriple } from "./release-version.js";
+import { runningHeartbeatPredicate } from "./run-store-sql.js";
+const isCapability = (id) => REPLICA_CAPABILITIES.includes(id);
+const sameChange = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function judgeStopThenStart(entry) {
+    const faults = [];
+    if (!isCapability(entry.id))
+        faults.push(`${entry.id} is not in REPLICA_CAPABILITIES (a stop-then-start migration reads evidence only under a capability name)`);
+    if (entry.reason.trim() === "")
+        faults.push(`${entry.id}: reason is empty`);
+    const fence = entry.fence;
+    switch (fence.kind) {
+        case "structural":
+            if (!(entry.shapeChanges ?? []).some((c) => sameChange(c, fence.fencedBy)))
+                faults.push(`${entry.id}: structural fencedBy is not one of the row's shapeChanges`);
+            if (fence.fencedBy.kind === "add")
+                faults.push(`${entry.id}: structural fencedBy is an "add" (adding a column fences no earlier writer)`);
+            break;
+        case "per-write": {
+            const since = releaseTriple(fence.fencedSince);
+            const introduced = releaseTriple(entry.introducedIn);
+            if (since === undefined)
+                faults.push(`${entry.id}: per-write fencedSince "${fence.fencedSince}" is not x.y.z`);
+            if (introduced === undefined)
+                faults.push(`${entry.id}: introducedIn "${entry.introducedIn}" is not x.y.z`);
+            if (since !== undefined && introduced !== undefined && compareReleaseTriples(since, introduced) >= 0) {
+                faults.push(`${entry.id}: per-write fencedSince ${fence.fencedSince} is not earlier than introducedIn ${entry.introducedIn} (the fencing writes must ship at least one release before the migration)`);
+            }
+            if (fence.statements.trim() === "")
+                faults.push(`${entry.id}: per-write statements is empty`);
+            break;
+        }
+        case "accepted":
+            if (fence.residual.trim() === "")
+                faults.push(`${entry.id}: accepted residual is empty`);
+            break;
+        default: {
+            const unhandled = fence;
+            faults.push(`${entry.id}: unknown fence kind ${String(unhandled.kind)}`);
+        }
+    }
+    return faults;
+}
+export async function readOlderReplicaEvidence(db, dialect, input, migrationId) {
+    const scope = dialect === "mysql" ? "DATABASE()" : "current_schema()";
+    if ((await db.rows(`SELECT 1 AS present FROM information_schema.tables WHERE table_schema = ${scope} AND table_name = 'task_run'`)).length === 0)
+        return undefined;
+    const live = runningHeartbeatPredicate(dialect, "live", { nowMs: Date.now(), windowMs: input.liveRunWindowMs }, 1);
+    const groups = (await db.rows(`SELECT instance_id, COUNT(*) AS n, MAX(updated_at) AS newest FROM task_run WHERE ${live.sql} GROUP BY instance_id`, [live.param]))
+        .map((r) => ({ holder: typeof r["instance_id"] === "string" ? r["instance_id"] : undefined, runs: Number(r["n"] ?? 0), newest: r["newest"] }))
+        .filter((g) => g.runs > 0);
+    if (groups.length === 0)
+        return undefined;
+    const registered = await readReplicaRegistrations({ query: async (sql, params) => ({ rows: await db.rows(sql, params), affected: 0 }) }, dialect, groups.flatMap((g) => (g.holder === undefined ? [] : [g.holder])));
+    let unregisteredRuns = 0;
+    let newestMs = Number.NaN;
+    const registeredWithout = [];
+    for (const g of groups) {
+        const r = g.holder === undefined ? undefined : registered.get(g.holder);
+        if (r !== undefined && knowsCapability(r.capabilities, migrationId))
+            continue;
+        if (r === undefined)
+            unregisteredRuns += g.runs;
+        else
+            registeredWithout.push({ instanceId: r.instanceId, releaseLine: r.releaseLine, hostName: r.hostName, pid: r.pid, runs: g.runs });
+        const cell = g.newest instanceof Date ? g.newest : new Date(String(g.newest));
+        if (!Number.isNaN(cell.getTime()) && !(cell.getTime() <= newestMs))
+            newestMs = cell.getTime();
+    }
+    const liveRuns = unregisteredRuns + registeredWithout.reduce((n, h) => n + h.runs, 0);
+    if (liveRuns === 0)
+        return undefined;
+    const now = Date.now();
+    const restartAtMs = (Number.isNaN(newestMs) ? now : newestMs) + input.liveRunWindowMs;
+    return {
+        migration: migrationId,
+        liveRuns,
+        windowSec: Math.round(input.liveRunWindowMs / 1000),
+        restartAfter: new Date(restartAtMs).toISOString(),
+        after: `${new Date(restartAtMs).toISOString()} (${Math.max(0, Math.ceil((restartAtMs - now) / 1000))}s from now)`,
+        unregisteredRuns,
+        registeredWithout: registeredWithout.sort((a, b) => a.instanceId.localeCompare(b.instanceId)),
+    };
+}
+export function assertStopThenStartDeclarations(entries) {
+    const faults = entries.flatMap((e) => judgeStopThenStart(e));
+    if (faults.length > 0) {
+        throw new Error(`stop-then-start: this build declares a stop-then-start migration that contradicts its fence class (a build defect; refused before any statement reached the database): ${faults.join("; ")}`);
+    }
+}
+export async function guardOwedStopThenStart(db, dialect, input, entries) {
+    const read = (sql) => db.rows(sql);
+    for (const entry of entries) {
+        if (!(await entry.owedOn(read, dialect)))
+            continue;
+        if (!isCapability(entry.id))
+            throw new Error(`stop-then-start: ${entry.id} is not in REPLICA_CAPABILITIES`);
+        const evidence = await readOlderReplicaEvidence(db, dialect, input, entry.id);
+        if (evidence !== undefined)
+            throw await entry.refuse(evidence, read, dialect);
+    }
+}
+//# sourceMappingURL=stop-then-start.js.map