@sema-agent/server 7.138.0 → 7.139.0

package/dist/plugins/one-time-migrations.js

@@ -8,7 +8,7 @@ import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn, readOpaqueJsonValueColumn, } from "./sql-json-column.js";
 import { incarnationFromCell, sessionFaceFromRow } from "../session-incarnation.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR, StoreBootRefusalError } from "./store-contracts.js";
 import { PERMISSION_RULE_TABLE, purgeUndurableScopeRows } from "./permission-rule-store-sql.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { readJsonObjectColumn } from "./sql-json-column.js";
@@ -16,6 +16,9 @@ import { retireStoredCardWords } from "../retired-card-words.js";
 import { redactSecrets } from "../trace/redact.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, isOrphanSessionOwner, judgeDelegatedOwner } from "../delegated-session-owner.js";
 import { MAILBOX_KEYED_TABLES, mailboxKeyDeleteSql, storedMailboxKeyless } from "./mailbox-store-sql.js";
+import { SESSION_META_PLACEMENT_COLUMNS, backfillWriterStatement, countOrphanBindingsStatement, migrateDeviceBindingsStatement } from "./execution-placement-sql.js";
+import { APPROVAL_ASK_EXECUTION_LANE_COLUMN, APPROVAL_ASK_TABLE } from "./approval-ask-store-sql.js";
+import { isUnusableArchive } from "../execution-placement.js";
 const RETIRED_SESSION_RULE_BUCKETS = ["commandAllow", "commandDeny"];
 export function buildMigrationReceipts() {
     return {
@@ -45,6 +48,13 @@ export function buildMigrationReceipts() {
         parkedApprovalCardsBackfilled: 0,
         parkedApprovalCardRowsUnreadable: [],
         parkedApprovalCardRowsTooLong: [],
+        executionPlacementColumnsAdded: 0,
+        deviceBindingsMoved: 0,
+        deviceBindingsOrphaned: 0,
+        deviceBindingTablesDropped: 0,
+        executionPlacementsBackfilled: 0,
+        askExecutionLanesBackfilled: 0,
+        executionPlacementSessionsUnreadable: [],
     };
 }
 function completedReport(r) {
@@ -83,7 +93,14 @@ function changedAnything(r) {
         r.mailboxRejectedKeyRowsRemoved > 0 ||
         r.parkedApprovalCardsBackfilled > 0 ||
         r.parkedApprovalCardRowsUnreadable.length > 0 ||
-        r.parkedApprovalCardRowsTooLong.length > 0);
+        r.parkedApprovalCardRowsTooLong.length > 0 ||
+        r.executionPlacementColumnsAdded > 0 ||
+        r.deviceBindingsMoved > 0 ||
+        r.deviceBindingsOrphaned > 0 ||
+        r.deviceBindingTablesDropped > 0 ||
+        r.executionPlacementsBackfilled > 0 ||
+        r.askExecutionLanesBackfilled > 0 ||
+        r.executionPlacementSessionsUnreadable.length > 0);
 }
 function readingsSnapshot(r) {
     return {
@@ -95,6 +112,7 @@ function readingsSnapshot(r) {
         sessionRuleRowsWithUnreadableDeny: [...r.sessionRuleRowsWithUnreadableDeny],
         parkedApprovalCardRowsUnreadable: [...r.parkedApprovalCardRowsUnreadable],
         parkedApprovalCardRowsTooLong: [...r.parkedApprovalCardRowsTooLong],
+        executionPlacementSessionsUnreadable: [...r.executionPlacementSessionsUnreadable],
     };
 }
 function receiptSentence(r) {
@@ -408,7 +426,7 @@ export const ONE_TIME_MIGRATIONS = [
             "`test/one-time-migrations.test.ts` 的 S-491 组与 `test/one-time-migrations-db-integration.test.ts` 的 M26 格。" +
             "**不随本条删**:键的铸点 `breakerKeyOf` / `routeDigestOf`(常设的键形)与新表 `breaker_state`",
         afterRemoval: "没有新的臂(如实):跳过了带本条的版本直接升的库,退役表 `circuit_breaker` 留在库里、没有读者也没有写者(断路器只读写 `breaker_state`)—— " +
-            "出路 = 升级时先过一次带本条的版本,或手工 `DROP TABLE circuit_breaker`(建议性状态,删表安全)",
+            "出路 = 升级时先过一次带本条的版本(它起服删掉退役表);不先过也无害 —— 退役表没有读者也没有写者,留在库里只占空间(建议性状态,无数据价值)",
         reportKeys: ["retiredBreakerTablesDropped"],
     },
     {
@@ -466,7 +484,7 @@ export const ONE_TIME_MIGRATIONS = [
             "改后句:「this session's stored request still carries a request key this version retired and nothing rewrites it any more; it is not replayed — the task stays suspended until someone cancels it and resubmits it as a new task (promptLean in place of promptProfile)」);" +
             "同族注释(每个半句只归本条或 M28 条之一,不重复改;标〔另一条的〕的几处住在另一条迁移的文件 / 头注段里,那条已先删则宿主已不在,跳过):`src/http/checkpoint-ctx.ts`:「两条出路(运维在一次性迁移的窗内重启本服务 ⇒ 起服改写存体、同一请求可再发;否则作为新任务重提,仍停驻的先取消)」改成「出路(作为新任务重提,仍停驻的先取消)」、「**窗的日期不手写**」起到「删法见登记表 M30 的」止整段删、「存体里的旧键由一次性迁移在起服时原地改写」改成「存体里的旧键没有迁移改写」、「(M30,`stored-request-prompt-profile-m30.ts`,行改写经本模块的 {@link rewriteStoredBodyKeys})。改写不到的残留行」改成「仍带旧键的残留行」、「;存体由 M30 起服改写」删、「与 {@link rewriteStoredBodyKeys}」删、「(存量行非凭据顶层体键的改写,凭据位与读法记号原样随行)」删;`src/http/wire-types.ts`:「由一次性迁移 M30 在起服时按同一张映射原地改写」改成「没有迁移改写」、「(`stored-request-prompt-profile-m30.ts`;M30 · 窗口见 `plugins/one-time-migrations.ts` 登记表)」删;`src/spec-fields.ts`:「由一次性迁移 M30 在起服时改写成 `promptLean`(`stored-request-prompt-profile-m30.ts`),」改成「不改写,」;`src/boot/stage-06-runners.ts`:「M30(存体里的退役请求键 `promptProfile` 原地改写)同在这里、」删、「(同一只 ctx 行改写店腿;不要封签器),同样早于任何续跑入口。」删;`src/plugins/checkpoint-store-sql.ts`:「、M30(退役请求键改写)」删;`src/plugins/one-time-migrations.ts`:〔另一条的〕「M30 用同一只;」删;`src/checkpoint-ctx-seal-m28.ts`:〔另一条的〕「(M30 用同一只)」删;`test/task-agents-876.test.ts`:「体由一次性迁移 M30 在起服时原地改写」改成「体没有迁移改写」;`test/allow-list-reading-park-refusal.test.ts`:「一次性迁移 M30 没改写到的残留」改成「没有迁移改写的残留」;`test/api-error-text-freeze.test.ts`:「一次性迁移 M30 没改写到的残留」改成「没有迁移改写的残留」、「洞 = 窗的最后一天(绝对日期)」起到「不手写。」止整段删;" +
             "`http/stored-body-replay.ts` 里 `RETIRED_KEY_REWRITE_MIGRATION` 的 JSDoc 随表删;" +
-            "`http/stored-body-replay.ts` 的 `RETIRED_KEY_REWRITE_MIGRATION`(`satisfies Record<RetiredRequestKey, string>`:M30 删后 `promptProfile` 仍是退役键,这张表只能整张删)、" +
+            "`http/stored-body-replay.ts` 的 `RETIRED_KEY_REWRITE_MIGRATION`(`satisfies Record<ReplayRefusedRetiredKey, string>`:M30 删后 `promptProfile` 仍是退役键,这张表只能整张删)、" +
             "判据里 `rewriteWindowEnd: migrationWindowEnd(…)` 那一项与 `migrationWindowEnd` 的引入行;`plugins/one-time-migrations.ts` 导出的 `migrationWindowEnd` 在无别的读者时一起删;" +
             "冻结表 `test/api-error-text-freeze.test.ts` 的 `FROZEN_RESULT_BODY_TEMPLATE` 里那一行搬回字面表(删完半句后拒句是整句字面);" +
             "`test/stored-request-prompt-profile-m30.test.ts` 的起服改写组、登记行组、「M28 登记行」组(M28 没先删时它还在:它读本文件顶部的引入与 COMMENTS 表,与登记行组同命)、「M30 起服接线」组(它钉的就是被删的那处调用与起服 info 行)与「M30 的混跑与回滚」组;「M30 的混跑与回滚」组随删:它读登记表头注 M30 段(随本行一起删)与 MIGRATION 7.137.0 节第 4 条(已发布的历史文字,留着不动);doc-claims ㊵ 的「嵌入方一段分清两只迁移的窗」格同样读本行的窗末日,随删(它与 M28 行共读,哪一行先删就先删这一格);「窗关后的残留」组保留,但它里面 (d) 读登记行的 `m30Row()` 用处(期望里的 `rewriteWindowEnd`)与 (d′) 整格随删,`m30Row` 助手随之删;" +
@@ -480,6 +498,39 @@ export const ONE_TIME_MIGRATIONS = [
             "(判据 `retired_request_key`,`http/stored-body-replay.ts`)、行字节不动 —— 出路 = 作为新任务重提(`promptLean` 代替 `promptProfile`;仍停驻的先取消),或升级时先过一次带本条的版本并在窗内起服",
         reportKeys: [],
     },
+    {
+        id: "M31",
+        introducedIn: "7.139.0",
+        releasedOn: "2026-10-29",
+        removableAfter: "2026-11-28",
+        removal: "删 `src/memory-sync-client.ts` 里的 `relocateSyncCursorsM31` / `SyncCursorRelocationM31Report` / `m31Window` / `scopeOfLegacyCursor` / `LEGACY_PEER_SEGMENT` / `LEGACY_ROOT_CURSOR_FILE`、" +
+            "`createMemorySyncRunner` 里的 `relocated` 旗标与 `round` 开头对 `relocateSyncCursorsM31` 的那一处调用(连同它上面那一行注释、info `memory_sync_cursor_relocated` 与 warn `memory_sync_cursor_not_relocated` 两行日志)、" +
+            "文件头注的 ⑤ 段与 `ONE_TIME_MIGRATIONS` / `migrationWindowOpen` / `OneTimeMigrationWindow` 的引入行;本文件头注的 M31 段;" +
+            "`test/memory-sync-client.test.ts` 里标题以 `🔴 M31:` 或 `M31 ` 起头的格、对 `relocateSyncCursorsM31` 的引入与常量 `LEGACY_PEER_DIR`,常量 `CURSOR_FILE` 的行注改成「没有读者」(用它的格随删后无人用它 ⇒ 常量一起删)",
+        afterRemoval: "没有新的臂(如实):跳过了带本条的版本直接升的数据根,升级前的游标还在 `sync-cursors/central/` 与 `sync-cursor-central.json`,没有读者 ⇒ 那几层以空基线首轮同步" +
+            "(两边都改过的条目按冲突上报,上一轮之后在一侧删掉的条目从另一侧回来)。出路 = 升级时先过一次带本条的版本并在窗内跑一轮同步,或升级前在旧版上跑完一轮同步、再删掉这些文件",
+        reportKeys: [],
+    },
+    {
+        id: "M32",
+        introducedIn: "7.139.0",
+        releasedOn: "2026-10-29",
+        removableAfter: "2026-11-28",
+        removal: "删 migrateStepsOn 的 M32 步(`switchExecutionPlacement`、步骤表 `EXECUTION_PLACEMENT_SWITCH_STEPS`、回填前提表 `EXECUTION_PLACEMENT_BACKFILL_NEEDS`、" +
+            "`readSwitchShape` / `switchStarted` / `switchComplete` / `refuseOnSwitchFence` / `refuseOnAmbiguousBackfill` / `sessionRowsAwaitingBackfill` / `bindingRootKey`、" +
+            "`RETIRED_DEVICE_BINDING_TABLE` / `PARKED_DEVICE_BINDING_TABLE` / `FENCE_ROOTS_SHOWN`、`ExecutionPlacementSwitchRefusedError` / `EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE` / `ExecutionPlacementSwitchRefusalReason`)" +
+            "与 DDL 前探针(`assertExecutionPlacementSwitchAdmissible` / `assertExecutionPlacementSwitchAdmissibleOnPool`,`store-backend.ts` 的 `withRetiredSchemaProbe` 里调它的那一行);" +
+            "`runSqlOneTimeMigrations` 的第三参 `ExecutionPlacementSwitchInput`(若再无别的条目用它)与它在两只 SQL 后端 / 测试夹具上的实参;local 腿(`LocalBackend.runOneTimeMigrations` 里的 `backfillLocalExecutionPlacements` 与 `FileRunStore.sessionIdsWithRuns`);" +
+            "`execution-placement-sql.ts` 的 `backfillWriterStatement` / `migrateDeviceBindingsStatement` / `countOrphanBindingsStatement`;报告、日志行与 `NO_SQL_MIGRATIONS` 的 `executionPlacementColumnsAdded` / `deviceBindingsMoved` / " +
+            "`deviceBindingsOrphaned` / `deviceBindingTablesDropped` / `executionPlacementsBackfilled` / `executionPlacementSessionsUnreadable` 与 `device_bindings_orphaned` / `execution_placement_session_unreadable` 两行 warn;`test/execution-placement-switch-db-integration.test.ts` 整份与 `test/one-time-migrations.test.ts` 的 M32 组。" +
+            "**local 腿的回填席与它的点名词一并删**:`LocalSessionStore` 的 `executionPlacementBackfill`(属性与构造里的那一臂)、`execution-placement.ts` 的 `LocalPlacementBackfillSeat` / `UnusableArchive` / `UnusableArchiveWord`(含它的 `storage` 词 —— 读存档文件时抛了别的故障、`errno` 随带,该词只有回填点名用)/ `isUnusableArchive`、" +
+            "`ExecutionPlacementSessionUnreadable`;`local-session-store.ts` 里 `placementRead` 并回 `readExecutionPlacement`、`metaRead` 的 unusable 臂与 `forkingOf` 的 `storage` 臂改成就地上抛 `probe.fault`(`archiveFaultWord` / `unusableArchiveOf` 随词删,探针只留「不在」与已知在而用不了的读法);" +
+            "`test/execution-placement-switch-local.test.ts` 与 `test/execution-placement-local-boot-unreadable-e2e.test.ts` 整份。" +
+            "**不随本条删**:执行放置八列、会话店的执行席、设备店的首绑 / 换绑两只写(常设的数据形)",
+        afterRemoval: "起服对账一族的跳版库拒启臂接住:删码同版把 `device_session` / `device_session_retired` 两张表加进退役 schema 判据(`schema-consistency.ts` 的跳版库探针,先于建表)⇒ " +
+            "跳过了带本条的版本直接升的库响亮拒启,出路 = 先在带本条的版本起服一次让切换走完,再升;缺执行放置列的库由列集对账缺列拒启(`config.schema_mismatch`,拒句给 ALTER),同一出路",
+        reportKeys: ["executionPlacementColumnsAdded", "deviceBindingsMoved", "deviceBindingsOrphaned", "deviceBindingTablesDropped", "executionPlacementsBackfilled", "askExecutionLanesBackfilled", "executionPlacementSessionsUnreadable"],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;
@@ -521,6 +572,10 @@ export const NO_SQL_MIGRATIONS = {
     parkedApprovalCardsBackfilled: 0,
     parkedApprovalCardRowsUnreadable: [],
     parkedApprovalCardRowsTooLong: [],
+    executionPlacementColumnsAdded: 0,
+    deviceBindingsMoved: 0,
+    deviceBindingsOrphaned: 0,
+    deviceBindingTablesDropped: 0,
 };
 function mysqlDb(conn) {
     return {
@@ -566,8 +621,8 @@ async function columnExists(db, dialect, table, column) {
     const sql = `SELECT 1 AS present FROM information_schema.columns WHERE table_schema = ${scope} AND table_name = '${table}' AND column_name = '${column}'`;
     return (await db.rows(sql)).length > 0;
 }
-export async function runSqlOneTimeMigrations(dialect, pool) {
-    return dialect === "tidb" ? withMysqlLock(pool, (db) => migrateOn(db, "tidb")) : withPgLock(pool, (db) => migrateOn(db, "pg"));
+export async function runSqlOneTimeMigrations(dialect, pool, input) {
+    return dialect === "tidb" ? withMysqlLock(pool, (db) => migrateOn(db, "tidb", input)) : withPgLock(pool, (db) => migrateOn(db, "pg", input));
 }
 async function withMysqlLock(pool, run) {
     const conn = await pool.getConnection();
@@ -597,17 +652,17 @@ async function withPgLock(pool, run) {
         client.release();
     }
 }
-async function migrateOn(db, dialect) {
+async function migrateOn(db, dialect, input) {
     const receipts = buildMigrationReceipts();
     try {
-        await migrateStepsOn(db, dialect, receipts);
+        await migrateStepsOn(db, dialect, receipts, input);
     }
     catch (e) {
         throw changedAnything(receipts) ? new OneTimeMigrationInterruptedError(e, readingsSnapshot(receipts)) : e;
     }
     return completedReport(receipts);
 }
-async function migrateStepsOn(db, dialect, receipts) {
+async function migrateStepsOn(db, dialect, receipts, input) {
     receipts.holderDeathCodeRowsBackfilled += await db.exec(dialect === "tidb"
         ? "UPDATE task_run SET error_code = ? WHERE status = 'failed' AND error_code IS NULL AND error = ?"
         : "UPDATE task_run SET error_code = $1 WHERE status = 'failed' AND error_code IS NULL AND error = $2", [RUN_HOLDER_DEATH_CODES.stalled, RUN_STALLED_ERROR]);
@@ -628,6 +683,289 @@ async function migrateStepsOn(db, dialect, receipts) {
     if (await tableExists(db, dialect, RETIRED_BREAKER_TABLE))
         await dropRetiredBreakerTable(db, dialect, receipts);
     await dropRejectedMailboxKeys(db, dialect, receipts);
+    await switchExecutionPlacement(db, dialect, receipts, input);
+}
+const RETIRED_DEVICE_BINDING_TABLE = "device_session";
+const PARKED_DEVICE_BINDING_TABLE = "device_session_retired";
+const BINDING_COLUMNS = "root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev";
+const FENCE_ROOTS_SHOWN = 20;
+export const EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE = "config.execution_placement_switch_refused";
+export class ExecutionPlacementSwitchRefusedError extends StoreBootRefusalError {
+    reason;
+    code = EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE;
+    constructor(reason, detail) {
+        super(`${EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE} (reason: ${reason}): ${detail}`);
+        this.reason = reason;
+        this.name = "ExecutionPlacementSwitchRefusedError";
+    }
+}
+async function readSwitchShape(db, dialect) {
+    const sessionMeta = await tableExists(db, dialect, "session_meta");
+    const placementColumns = new Set();
+    if (sessionMeta)
+        for (const c of SESSION_META_PLACEMENT_COLUMNS)
+            if (await columnExists(db, dialect, "session_meta", c.name))
+                placementColumns.add(c.name);
+    return {
+        sessionMeta,
+        placementColumns,
+        bindingTable: await tableExists(db, dialect, RETIRED_DEVICE_BINDING_TABLE),
+        parkedTable: await tableExists(db, dialect, PARKED_DEVICE_BINDING_TABLE),
+        taskRun: sessionMeta && (await tableExists(db, dialect, "task_run")),
+        ...(await askTableShape(db, dialect)),
+    };
+}
+async function askTableShape(db, dialect) {
+    const askTable = await tableExists(db, dialect, APPROVAL_ASK_TABLE);
+    return { askTable, askLaneColumn: askTable && (await columnExists(db, dialect, APPROVAL_ASK_TABLE, "execution_lane")) };
+}
+function switchStarted(s) {
+    return s.placementColumns.has("execution_role") || s.parkedTable;
+}
+const SWITCH_COMPLETION_COLUMN = "fork_key";
+function switchComplete(s) {
+    return s.placementColumns.size === SESSION_META_PLACEMENT_COLUMNS.length && (!s.askTable || s.askLaneColumn) && !s.bindingTable && !s.parkedTable;
+}
+function askLaneBackfillSql(dialect) {
+    return dialect === "tidb"
+        ? `UPDATE ${APPROVAL_ASK_TABLE} a LEFT JOIN session_meta sm ON sm.session_id = a.session_id AND sm.placement_kind IS NULL SET a.execution_lane = COALESCE(sm.execution_lane, ?) WHERE a.execution_lane = ''`
+        : `UPDATE ${APPROVAL_ASK_TABLE} a SET execution_lane = COALESCE((SELECT sm.execution_lane FROM session_meta sm WHERE sm.session_id = a.session_id AND sm.placement_kind IS NULL), $1) WHERE a.execution_lane = ''`;
+}
+async function parkedRelationNamesWithRetiredPrefix(db) {
+    const rows = await db.rows(`SELECT i.relname AS name FROM pg_index x JOIN pg_class i ON i.oid = x.indexrelid JOIN pg_class t ON t.oid = x.indrelid WHERE t.relname = '${PARKED_DEVICE_BINDING_TABLE}' AND t.relnamespace = current_schema()::regnamespace AND i.relname LIKE '${RETIRED_DEVICE_BINDING_TABLE}\\_%'`);
+    return rows.map((r) => String(r["name"])).filter((name) => name.startsWith(`${RETIRED_DEVICE_BINDING_TABLE}_`) && !name.startsWith(PARKED_DEVICE_BINDING_TABLE));
+}
+const bindingRootKey = (dialect, alias) => (dialect === "tidb" ? `CONVERT(${alias}.root_session_id USING utf8mb4) COLLATE utf8mb4_bin` : `${alias}.root_session_id`);
+async function refuseOnSwitchFence(read, dialect, shape) {
+    if (!switchStarted(shape) || !shape.bindingTable)
+        return;
+    const rows = await read(`SELECT ${bindingRootKey(dialect, "ds")} AS root FROM ${RETIRED_DEVICE_BINDING_TABLE} ds LIMIT ${FENCE_ROOTS_SHOWN + 1}`);
+    if (rows.length === 0)
+        return;
+    const roots = rows.slice(0, FENCE_ROOTS_SHOWN).map((r) => (Buffer.isBuffer(r["root"]) ? r["root"].toString("utf8") : String(r["root"])));
+    const more = rows.length > FENCE_ROOTS_SHOWN ? ` (and more — the table holds over ${FENCE_ROOTS_SHOWN} rows)` : "";
+    const rename = dialect === "tidb" ? `RENAME TABLE ${RETIRED_DEVICE_BINDING_TABLE} TO ${PARKED_DEVICE_BINDING_TABLE};` : `ALTER TABLE ${RETIRED_DEVICE_BINDING_TABLE} RENAME TO ${PARKED_DEVICE_BINDING_TABLE};`;
+    const adopt = shape.parkedTable
+        ? `DELETE FROM ${PARKED_DEVICE_BINDING_TABLE} WHERE root_session_id IN (SELECT root_session_id FROM ${RETIRED_DEVICE_BINDING_TABLE}); INSERT INTO ${PARKED_DEVICE_BINDING_TABLE} (${BINDING_COLUMNS}) SELECT ${BINDING_COLUMNS} FROM ${RETIRED_DEVICE_BINDING_TABLE}; DELETE FROM ${RETIRED_DEVICE_BINDING_TABLE};`
+        : rename;
+    throw new ExecutionPlacementSwitchRefusedError("fence", `the switch of session↔device bindings onto the root session rows has started on this database, yet the retired binding table ${RETIRED_DEVICE_BINDING_TABLE} holds rows again — ` +
+        `an earlier server version still writing it after the switch began, or rows written by hand. This server cannot tell whether they are newer than the placements ` +
+        `already on the session rows and refuses to pick: nothing was changed (this check runs before any DDL). Root sessions in that table: ${roots.join(", ")}${more}. ` +
+        `Stop every earlier-version replica first, then choose one: adopt those rows (they overwrite the device placement of their root sessions on the next start): \`${adopt}\` — ` +
+        `or discard them (the session rows keep what they hold): \`DELETE FROM ${RETIRED_DEVICE_BINDING_TABLE};\` — then start this version again; its own migration removes the emptied table on that start`);
+}
+async function sessionRowsAwaitingBackfill(read, dialect, shape) {
+    if (!shape.sessionMeta || !shape.taskRun)
+        return false;
+    const bindingSource = shape.parkedTable ? PARKED_DEVICE_BINDING_TABLE : shape.bindingTable ? RETIRED_DEVICE_BINDING_TABLE : undefined;
+    const sql = "SELECT 1 AS hit FROM session_meta sm WHERE sm.placement_kind IS NULL" +
+        (shape.placementColumns.has("execution_role") ? " AND sm.execution_role IS NULL" : "") +
+        " AND EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id)" +
+        (bindingSource !== undefined ? ` AND NOT EXISTS (SELECT 1 FROM ${bindingSource} ds WHERE ${bindingRootKey(dialect, "ds")} = sm.session_id)` : "") +
+        " LIMIT 1";
+    return (await read(sql)).length > 0;
+}
+async function askRowsAwaitingLane(read, _dialect, shape) {
+    if (!shape.askTable)
+        return false;
+    return (await read(`SELECT 1 AS hit FROM ${APPROVAL_ASK_TABLE}${shape.askLaneColumn ? " WHERE execution_lane = ''" : ""} LIMIT 1`)).length > 0;
+}
+const EXECUTION_PLACEMENT_BACKFILL_NEEDS = [
+    { what: "session rows that have runs but no execution placement (they would be placed on the only declared lane)", holds: sessionRowsAwaitingBackfill },
+    { what: "approval ask rows that do not record the execution lane they were raised on (they would record their root session's lane, or the only declared lane)", holds: askRowsAwaitingLane },
+];
+async function refuseOnAmbiguousBackfill(read, dialect, shape, lanes) {
+    if (!shape.sessionMeta || switchComplete(shape) || lanes.length === 1)
+        return;
+    const pending = [];
+    for (const need of EXECUTION_PLACEMENT_BACKFILL_NEEDS)
+        if (await need.holds(read, dialect, shape))
+            pending.push(need.what);
+    if (pending.length === 0)
+        return;
+    throw new ExecutionPlacementSwitchRefusedError("backfill_ambiguous", `this database still holds rows the switch must place on an execution lane (${pending.join("; ")}), and the deployment declares ${lanes.length === 0 ? "no lane" : `${lanes.length} lanes (${lanes.join(", ")})`} — ` +
+        "with more than one lane there is no single right answer, and this server will not guess one. Nothing was changed (this check runs before any DDL). " +
+        "Start this version once with a single declared lane (REMOTE_EXEC set to one lane) so the switch completes, then declare the additional lanes");
+}
+export async function assertExecutionPlacementSwitchAdmissible(read, dialect, input) {
+    const shape = await readSwitchShape({ rows: (sql) => read(sql) }, dialect);
+    if (!shape.sessionMeta)
+        return;
+    await refuseOnSwitchFence(read, dialect, shape);
+    await refuseOnAmbiguousBackfill(read, dialect, shape, input.lanes);
+}
+export async function assertExecutionPlacementSwitchAdmissibleOnPool(dialect, pool, input) {
+    if (dialect === "tidb") {
+        const conn = await pool.getConnection();
+        try {
+            await assertExecutionPlacementSwitchAdmissible(async (sql) => (await conn.query(sql))[0], "tidb", input);
+        }
+        finally {
+            conn.release();
+        }
+        return;
+    }
+    const client = await pool.connect();
+    try {
+        await assertExecutionPlacementSwitchAdmissible(async (sql) => (await client.query(sql)).rows, "pg", input);
+    }
+    finally {
+        client.release();
+    }
+}
+const EXECUTION_PLACEMENT_SWITCH_STEPS = [
+    {
+        id: "⓪ drop the empty retired binding table",
+        run: async ({ db, receipts, shape }) => {
+            const s = await shape();
+            if (!switchStarted(s) || !s.bindingTable)
+                return;
+            await execUntil(db, `DROP TABLE ${RETIRED_DEVICE_BINDING_TABLE}`, async () => !(await shape()).bindingTable);
+            receipts.deviceBindingTablesDropped += 1;
+        },
+    },
+    {
+        id: "① park the retired binding table",
+        run: async ({ db, dialect, shape }) => {
+            const s = await shape();
+            if (!s.bindingTable || s.placementColumns.has("execution_role"))
+                return;
+            const sql = dialect === "tidb" ? `RENAME TABLE ${RETIRED_DEVICE_BINDING_TABLE} TO ${PARKED_DEVICE_BINDING_TABLE}` : `ALTER TABLE ${RETIRED_DEVICE_BINDING_TABLE} RENAME TO ${PARKED_DEVICE_BINDING_TABLE}`;
+            await execUntil(db, sql, async () => {
+                const after = await shape();
+                return after.parkedTable && !after.bindingTable;
+            });
+        },
+    },
+    {
+        id: "①′ rename the parked table's constraints and indexes (PG)",
+        run: async ({ db, dialect, shape }) => {
+            if (dialect !== "pg" || !(await shape()).parkedTable)
+                return;
+            const stale = async () => parkedRelationNamesWithRetiredPrefix(db);
+            for (const name of await stale()) {
+                const renamed = `${PARKED_DEVICE_BINDING_TABLE}${name.slice(RETIRED_DEVICE_BINDING_TABLE.length)}`;
+                await execUntil(db, `ALTER INDEX "${name}" RENAME TO "${renamed}"`, async () => !(await stale()).includes(name));
+            }
+        },
+    },
+    {
+        id: "② add the execution placement columns",
+        run: async ({ db, dialect, receipts, shape }) => {
+            for (const column of SESSION_META_PLACEMENT_COLUMNS) {
+                if (column.name === SWITCH_COMPLETION_COLUMN)
+                    continue;
+                if ((await shape()).placementColumns.has(column.name))
+                    continue;
+                await execUntil(db, `ALTER TABLE session_meta ADD COLUMN ${column[dialect]}`, async () => (await shape()).placementColumns.has(column.name));
+                receipts.executionPlacementColumnsAdded += 1;
+            }
+            const ask = await shape();
+            if (ask.askTable && !ask.askLaneColumn) {
+                await execUntil(db, `ALTER TABLE ${APPROVAL_ASK_TABLE} ADD COLUMN ${APPROVAL_ASK_EXECUTION_LANE_COLUMN[dialect === "tidb" ? "mysql" : "pg"]}`, async () => (await shape()).askLaneColumn);
+                receipts.executionPlacementColumnsAdded += 1;
+            }
+        },
+    },
+    {
+        id: "③ move the bindings onto the root session rows",
+        run: async ({ db, dialect, receipts, shape }) => {
+            if (!(await shape()).parkedTable)
+                return;
+            const orphans = countOrphanBindingsStatement(dialect, PARKED_DEVICE_BINDING_TABLE);
+            receipts.deviceBindingsOrphaned += Number((await db.rows(orphans.text, orphans.values))[0]?.["orphans"] ?? 0);
+            const move = migrateDeviceBindingsStatement(dialect, PARKED_DEVICE_BINDING_TABLE);
+            receipts.deviceBindingsMoved += await db.exec(move.text, move.values);
+        },
+    },
+    {
+        id: "④ backfill placements of sessions with runs",
+        run: async ({ db, dialect, input, receipts, shape }) => {
+            const s = await shape();
+            if (input.lanes.length !== 1) {
+                await refuseOnAmbiguousBackfill((sql) => db.rows(sql), dialect, s, input.lanes);
+                return;
+            }
+            const lane = input.lanes[0];
+            const backfill = backfillWriterStatement(dialect, lane, new Date());
+            receipts.executionPlacementsBackfilled += await db.exec(backfill.text, backfill.values);
+        },
+    },
+    {
+        id: "④b backfill the execution lane of approval ask rows",
+        run: async ({ db, dialect, input, receipts, shape }) => {
+            const s = await shape();
+            if (!s.askTable || !s.askLaneColumn)
+                return;
+            if (input.lanes.length !== 1) {
+                await refuseOnAmbiguousBackfill((sql) => db.rows(sql), dialect, s, input.lanes);
+                return;
+            }
+            receipts.askExecutionLanesBackfilled += await db.exec(askLaneBackfillSql(dialect), [input.lanes[0]]);
+        },
+    },
+    {
+        id: "⑤ drop the parked binding table",
+        run: async ({ db, receipts, shape }) => {
+            if (!(await shape()).parkedTable)
+                return;
+            await execUntil(db, `DROP TABLE ${PARKED_DEVICE_BINDING_TABLE}`, async () => !(await shape()).parkedTable);
+            receipts.deviceBindingTablesDropped += 1;
+        },
+    },
+    {
+        id: "⑥ add the completion marker column",
+        run: async ({ db, dialect, receipts, shape }) => {
+            if ((await shape()).placementColumns.has(SWITCH_COMPLETION_COLUMN))
+                return;
+            const marker = SESSION_META_PLACEMENT_COLUMNS.find((c) => c.name === SWITCH_COMPLETION_COLUMN);
+            await execUntil(db, `ALTER TABLE session_meta ADD COLUMN ${marker[dialect]}`, async () => (await shape()).placementColumns.has(SWITCH_COMPLETION_COLUMN));
+            receipts.executionPlacementColumnsAdded += 1;
+        },
+    },
+];
+export async function switchExecutionPlacement(db, dialect, receipts, input) {
+    const shape = () => readSwitchShape(db, dialect);
+    const start = await shape();
+    if (!start.sessionMeta || switchComplete(start))
+        return;
+    await refuseOnSwitchFence((sql) => db.rows(sql), dialect, start);
+    for (const step of EXECUTION_PLACEMENT_SWITCH_STEPS)
+        await step.run({ db, dialect, input, receipts, shape });
+}
+export async function backfillLocalExecutionPlacements(sessionIds, seat, input) {
+    const absent = [];
+    const unreadable = [];
+    for (const root of sessionIds) {
+        const reading = await seat.read(root);
+        if (reading === undefined)
+            continue;
+        if (isUnusableArchive(reading))
+            unreadable.push({ sessionId: root, fault: reading.word, ...(reading.errno !== undefined ? { errno: reading.errno } : {}) });
+        else if (reading.cell.role === "absent")
+            absent.push({ root, occupant: reading.occupant });
+    }
+    if (absent.length === 0)
+        return { backfilled: 0, unreadable };
+    if (input.lanes.length !== 1) {
+        throw new ExecutionPlacementSwitchRefusedError("backfill_ambiguous", `the local data root holds sessions that have runs but no execution placement (${absent.length}), and the deployment declares ${input.lanes.length === 0 ? "no lane" : `${input.lanes.length} lanes (${input.lanes.join(", ")})`} — ` +
+            "with more than one lane there is no single right answer, and this server will not guess one. Nothing was changed. " +
+            "Start this version once with a single declared lane (REMOTE_EXEC set to one lane), then declare the additional lanes");
+    }
+    const lane = input.lanes[0];
+    let placed = 0;
+    for (const { root, occupant } of absent) {
+        if ((await seat.place(root, occupant, { role: "writer", lane })).outcome === "placed")
+            placed += 1;
+    }
+    return { backfilled: placed, unreadable };
+}
+export function backfillLocalAskExecutionLanes(store, input) {
+    return store.backfillExecutionLanes(input.lanes, (pending) => {
+        throw new ExecutionPlacementSwitchRefusedError("backfill_ambiguous", `the local approval ask journal holds asks that do not record the execution lane they were raised on (${pending}), and the deployment declares ${input.lanes.length === 0 ? "no lane" : `${input.lanes.length} lanes (${input.lanes.join(", ")})`} — ` +
+            "with more than one lane there is no single right answer, and this server will not guess one. Nothing was changed. " +
+            "Start this version once with a single declared lane (REMOTE_EXEC set to one lane), then declare the additional lanes");
+    });
 }
 const MAILBOX_KEY_SCAN_PAGE = 1000;
 async function dropRejectedMailboxKeys(db, dialect, receipts) {
@@ -1257,6 +1595,13 @@ function readingFields(r) {
         parkedApprovalCardsBackfilled: r.parkedApprovalCardsBackfilled,
         parkedApprovalCardRowsUnreadable: r.parkedApprovalCardRowsUnreadable.length,
         parkedApprovalCardRowsTooLong: r.parkedApprovalCardRowsTooLong.length,
+        executionPlacementColumnsAdded: r.executionPlacementColumnsAdded,
+        deviceBindingsMoved: r.deviceBindingsMoved,
+        deviceBindingsOrphaned: r.deviceBindingsOrphaned,
+        deviceBindingTablesDropped: r.deviceBindingTablesDropped,
+        executionPlacementsBackfilled: r.executionPlacementsBackfilled,
+        askExecutionLanesBackfilled: r.askExecutionLanesBackfilled,
+        executionPlacementSessionsUnreadable: r.executionPlacementSessionsUnreadable.length,
     };
 }
 export function logOneTimeMigrations(log, backend, report) {
@@ -1301,7 +1646,11 @@ export function logOneTimeMigrations(log, backend, report) {
             "delivery, reading nor session deletion would ever have touched them again; only the count is logged, never a key; M29: suspended rows " +
             "parked before the checkpoint column approval_card existed and still pending get that column — the approval card word on their gate, " +
             "derived by the same function the write path uses (the engine's checkpointIndexFacts); a row whose document cannot be read as a checkpoint " +
-            "is left NULL and counted, named by a parked_approval_card_row_unreadable line, and so is a row whose card word is longer than the column can hold, named by a parked_approval_card_row_too_long line). Each step " +
+            "is left NULL and counted, named by a parked_approval_card_row_unreadable line, and so is a row whose card word is longer than the column can hold, named by a parked_approval_card_row_too_long line; " +
+            "M32: session↔device bindings moved from the retired table device_session onto the root session rows (the table is first renamed device_session_retired, " +
+            "the eight execution placement columns are added to session_meta, every binding overwrites the device placement of its root session row — a binding whose " +
+            "root session row is gone is dropped and counted, named by a device_bindings_orphaned line — and the renamed table is dropped), and session rows that have " +
+            "runs but no execution placement placed on the only declared lane; once the switch is complete this step does nothing). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",
@@ -1309,6 +1658,27 @@ export function logOneTimeMigrations(log, backend, report) {
     logReceiptRows(log, backend, report);
 }
 function logReceiptRows(log, backend, r) {
+    if (r.deviceBindingsOrphaned > 0) {
+        log.warn("device_bindings_orphaned", {
+            backend,
+            count: r.deviceBindingsOrphaned,
+            note: "session↔device bindings whose root session row no longer exists (or is a delegated child row) were dropped while moving bindings onto the root session rows — no session can run on them; nothing else changed",
+        });
+    }
+    for (const row of r.executionPlacementSessionsUnreadable) {
+        log.warn("execution_placement_session_unreadable", {
+            backend,
+            sessionId: row.sessionId,
+            fault: row.fault,
+            ...(row.errno !== undefined ? { errno: row.errno } : {}),
+            note: "a local session that has runs (and either no session-metadata cell — it was written before the cell existed and has not been read since — or a fork-created cell) has an archive the server cannot read, " +
+                "so its execution placement could not be backfilled. The session was skipped and nothing was written or changed: boot is not blocked, and every request that needs the " +
+                "session keeps answering the archive's own fault (fault names it: corrupt_session = the session header cannot be read; invalid_session = the stored log's structure is broken; " +
+                "storage = reading the archive file itself failed — errno names it, e.g. EACCES = no permission, EIO = disk I/O error, ERR_STRING_TOO_LONG = the file is too large to read) until the " +
+                "archive file under the data root's sessions directory is readable again — restored from a kept copy, or (storage) its permissions or disk repaired; the next boot then backfills its placement as for any other session. " +
+                "(Removing the archive file ends the warning but places nothing: the session then no longer exists on this server — except a fork-created session, whose cell stays and reads as a fork that has not landed: retry the same fork, or delete the session.) The session is named on every boot until then",
+        });
+    }
     for (const row of r.parkedApprovalCardRowsUnreadable) {
         log.warn("parked_approval_card_row_unreadable", {
             backend,

package/dist/plugins/outcome-ledger-sql.d.ts

@@ -85,8 +85,8 @@ export declare function coreOutcomeToLedgerRow(o: CoreTaskOutcome): TaskOutcome;
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT, INT→INTEGER, inline KEY→separate CREATE INDEX.
  * The table is DISJOINT from every other store's tables, so this self-contained set is safe (no shadowing).
  *
- * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, schema changes are
- * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
+ * SCHEMA POLICY: see the header of pg-pool.ts — the code is the single source of truth, there is no in-place
+ * migration, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_OUTCOME_LEDGER_SCHEMA: string[];
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgOutcomeLedgerSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -73,7 +73,7 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 [ref] 的
  * `assertToolResultProvenanceSchema` 先例)。
  *
- * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
+ * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:代码是唯一真源,存量库缺列由部署者按拒启句打印的 ALTER 自己执行)。于是一台**没跟上**就升
  * 上来的部署,`CREATE TABLE IF NOT EXISTS` 对存量 `permission_rule_approval` 是空操作 —— 本车新加的
  * `command` / `edited_json` 两列不在,而 `get` / `create` / `cas` 三条语句**无条件**引用它们。
  * 后果不是「少一个新功能」,是**整条审批记录面**在那台机器上是坏的:
@@ -81,16 +81,16 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  *    `rule_store_error` —— 裁决照常 200,服务看起来完全健康;
  *  · CC 导入的 prepare 连 pending 记录都落不下;
  *  · 而 `/v1/capabilities` 的 `permissionRules` 仍然报 true ⇒ 本仓「says yes ⟺ route works」整句为假。
- * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
+ * 没有这道断言,运维得不到**任何**「这次升级必须先给表加列」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
  * 只判「五列在不在」(command / edited_json / offers_json 三列 TEXT 族 + version / selected_offer 两列
  * INT),不判宽度(TEXT 族无截断轴,INT 无宽度轴)。
  *
- * 🔴 **只有可证的缺列才给破坏性指路**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
+ * 🔴 **只有可证的缺列才给「缺列」的拒因**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
  * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
- * 每一种都会让这条读抛错,而把它们诊断成「去 DROP TABLE」是一条**会真的毁掉审计记录**的建议(比它要
- * 挡的缺陷更贵)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
+ * 每一种都会让这条读抛错,而把它们诊断成「缺列」是一条比它要挡的缺陷更贵的诊断(当年这句拒因还带着
+ * 一条会真的毁掉审计记录的指路;现在的出路是闭集三条,没有销毁性的一条)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
  * 终形判据 = **方言的缺列错误码**,一行一方言的闭集(见 {@link isMissingColumnError});其余错误
  * **原样 rethrow**,一个字都不加工。真库两条腿各自跑过这条路径(db-integration 的存量表格),所以
  * 这张码表不是抄手册抄来的,是实测钉住的。
@@ -111,7 +111,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
  * 那条头注写了这道门为什么必须是拒启而不是 warn:本仓不发 `ALTER TABLE`,`CREATE TABLE IF NOT EXISTS`
  * 对存量表是空操作,而新列被**无条件**引用)。
  *
- * 病:一台没删表就升上来的部署,`permission_rule_ticket` 上没有 `redeemed_outcome` 列,而 A7 的三态
+ * 病:一台没跟上就升上来的部署,`permission_rule_ticket` 上没有 `redeemed_outcome` 列,而 A7 的三态
  * 协议(`settle` / `peek` / `reclaim`)三条语句全都引用它。后果不是"少一个新功能":
  *  · `POST /v1/rules/local-import/redeem` 的落定那一跳撞 unknown column ⇒ 票停在 CLAIMED 永不结算,
  *    属主的重放只能拿到 409,一次人的确认就此卡死到票过期;
@@ -119,12 +119,11 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
  *    的同意**被报成没发生。
  * 所以判据放在启动期、拒启,而不是等第一位用户去踩。
  *
- * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给破坏性指路(其余错误原样 rethrow ——
- * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成"去 DROP TABLE"是一条比缺陷更贵的建议)。
+ * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给「缺列」的拒因(其余错误原样 rethrow ——
+ * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成「缺列」是一条比缺陷更贵的诊断)。出路是**闭集三条**
+ * (与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
  *
- * 🔴 破坏性指路的代价在本表上**比审批表小得多**,文案照实说:票是分钟级 TTL 的治理瞬态(过期即死),
- * 删表最多让**正在预览、还没按确认**的那几个人重走一次 prepare;持久规则在 `permission_rule` 里,
- * 一行都不动。
+ * 文案照实说本表的分量:票是分钟级 TTL 的治理瞬态(过期即死),持久规则在 `permission_rule` 里,一行都不动。
  */
 export declare function assertPermissionRuleTicketSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
@@ -440,10 +439,9 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
  * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
  *
- * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
- * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
- * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
- * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
+ * 索引到货:两方言的存量库都由幂等加索引原语(`ensureIndexes`)在启动时补建 —— PG 侧是独立的 `CREATE INDEX`,
+ * MySQL 协议侧先探测、缺才发在线 `ALTER TABLE … ADD INDEX`(中央 schema 的索引列表含 `PERMISSION_RULE_INDEXES`)。
+ * 补建完成之前(或某个副本还没起过新版),这条腿在存量库上仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
 /**