@sema-agent/server 7.137.0 → 7.139.0

package/dist/plugins/mailbox-store-sql.d.ts

@@ -1,13 +1,13 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { MailboxAckResult, MailboxAppendMessage, MailboxLease, MailboxStore } from "@sema-agent/core";
+import type { MailboxAckResult, MailboxAppendMessage, MailboxDecision, MailboxDecisionOutcome, MailboxLease, MailboxStore } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 import type { MailboxRecipientLifecycle, MailboxRecipientTombstone } from "./mailbox-recipient-lifecycle.js";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
 /** [ref] 收件人墓碑表(预删除态的**唯一**真源;形与理由见 `mailbox-recipient-lifecycle.ts` 模块头)。
- *  🔴 为什么是**新表**而不是给 `mailbox` 加两列:加列走的是本仓「删库重建、不开 ALTER seam」那条政策
- *  (存量库首跑必红);而 `CREATE TABLE IF NOT EXISTS` 一张新表在存量库上零破坏、零运维动作。语义上也更干净
+ *  🔴 为什么是**新表**而不是给 `mailbox` 加两列:加列走的是本仓「启动 DDL 不开 ALTER seam」那条政策
+ *  (存量库缺列起服列册对账拒启、要运维先手工 `ALTER`);而 `CREATE TABLE IF NOT EXISTS` 一张新表在存量库上零破坏、零运维动作。语义上也更干净
  *  —— `mailbox` 行是**盒**事实(next_seq / lease),墓碑是**收件人**事实,两者的生命周期本来就不同
  *  (`drop` 同时终结两者 —— 墓碑随箱亡,理由全文见 `mailbox-recipient-lifecycle.ts` 模块头)。 */
 export declare const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
@@ -69,6 +69,12 @@ export declare class TiDBMailboxStore implements MailboxStore, MailboxRecipientL
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
+    /**
+     * core 7.57.0 #972b —— 一条记录的留置决定从 `expect`(缺席 = 从未 held)移到 `next`:比较并设置,对每一次别的移动与 `ack` 原子
+     * (锁序与 ack / drop / reap 同为「盒行 → 消息行」,当前读);**不受租约围栏**(人从哪个终端答都行)。坏调用(词不在闭集 / seq 不是正整数 /
+     * 决定律不许的边)先于键判官与任何副作用以 `mailbox.invalid_decision_move` 拒(core 的唯一验证器 `assertMailboxDecisionMove`);判官拒的键没有箱 ⇒ gone。
+     */
+    moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;
@@ -93,6 +99,8 @@ export declare class PgMailboxStore implements MailboxStore, MailboxRecipientLif
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
+    /** core 7.57.0 #972b 留置决定的比较并设置(TiDB 孪生同注:验证先于一切、锁序盒行 → 消息行、不受租约围栏、判官拒的键 ⇒ gone)。 */
+    moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/plugins/mailbox-store-sql.js

@@ -1,5 +1,5 @@
 import { isUtf8 } from "node:buffer";
-import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, readMailboxPeerMeta } from "@sema-agent/core";
+import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_RECORD_ID_MAX_CHARS, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, assertMailboxDecisionMove, judgeMailboxAppendById, readMailboxAppend, readMailboxPeerMeta, readStoredMailboxDecision } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 import { isWellFormedUnicode } from "../principal-jwt.js";
 import { ensureIndexes } from "./ensure-index.js";
@@ -25,15 +25,36 @@ export const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
 export function mailboxKeyProblem(what, v) {
     if (what === "scope" && (v === undefined || v === ""))
         return "MailboxStore: refusing a message without a scope (an empty scope addresses no box)";
+    const unaddressable = byteExactIdentityProblem(what, v);
+    if (unaddressable !== undefined)
+        return unaddressable;
+    if (Buffer.byteLength(v, "utf8") > MAILBOX_KEY_MAX_UTF8_BYTES) {
+        return `MailboxStore: ${what} exceeds the ${MAILBOX_KEY_MAX_UTF8_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
+    }
+    return undefined;
+}
+function byteExactIdentityProblem(what, v) {
     if (!isWellFormedUnicode(v))
         return `MailboxStore: ${what} is not well-formed Unicode (lone surrogate) (refusing — the driver would store it as U+FFFD and alias a different key)`;
     if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f))
         return `MailboxStore: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`;
-    if (Buffer.byteLength(v, "utf8") > MAILBOX_KEY_MAX_UTF8_BYTES) {
-        return `MailboxStore: ${what} exceeds the ${MAILBOX_KEY_MAX_UTF8_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
-    }
     return undefined;
 }
+function appendSnapshot(msg) {
+    const rec = readMailboxAppend(msg);
+    if (rec.id !== undefined) {
+        const problem = byteExactIdentityProblem("record id", rec.id);
+        if (problem !== undefined)
+            throw new Error(problem);
+    }
+    return rec;
+}
+function replayedSeq(held, scope, handle, logger, asStored) {
+    return judgeMailboxAppendById(rowsToMessages(held, scope, handle, logger), asStored);
+}
+function asUtf8Stored(v) {
+    return Buffer.from(v, "utf8").toString("utf8");
+}
 function assertMailboxKey(what, v) {
     const problem = mailboxKeyProblem(what, v);
     if (problem !== undefined)
@@ -130,6 +151,7 @@ function rowsToMessages(rows, scope, handle, logger) {
         };
         const hopChain = read("hop_chain", () => decodeHopChain(r.hop_chain, r.seq));
         const peerMeta = read("peer_meta", () => decodePeerMeta(r.peer_meta, r.seq));
+        const decision = decisionOfColumn(r.decision);
         out.push({
             seq: Number(r.seq),
             ...(r.from_id !== null && r.from_id !== undefined ? { from: bufToStr(r.from_id) } : {}),
@@ -137,10 +159,21 @@ function rowsToMessages(rows, scope, handle, logger) {
             sentAt: Number(r.sent_at_ms),
             ...(hopChain !== undefined ? { hopChain } : {}),
             ...(peerMeta !== undefined ? { peerMeta } : {}),
+            ...(decision !== undefined ? { decision } : {}),
+            ...(r.record_id !== null && r.record_id !== undefined ? { id: String(r.record_id) } : {}),
         });
     }
     return out;
 }
+function decisionOfColumn(raw) {
+    return raw === null || raw === undefined ? undefined : readStoredMailboxDecision(bufToStr(raw));
+}
+function decisionMoveVerdict(rows, expect) {
+    if (rows.length === 0)
+        return { ok: false, current: "gone" };
+    const current = decisionOfColumn(rows[0].decision);
+    return current === expect ? "write" : { ok: false, current: current ?? "unset" };
+}
 export async function ensureTiDBMailboxSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
@@ -166,8 +199,15 @@ export async function ensureTiDBMailboxSchema(pool) {
     -- peer_meta(S-90;core fc52b4d4 design/385 片2b):drain 点权威判断读的 typed peer 记录,JSON 文本;
     -- NULL = 缺席(**有语义**:pre-385/foreign 记录,drain 永不回溯准入;与空对象绝不互折)。写入面先过 core
     -- readMailboxPeerMeta(坏值带码拒于任何副作用前)+ PEER_META_MAX_BYTES 守卫关掉静默截断类。
-    -- 新列按 2026-07-26 schema policy 直接折进 CREATE(不开 ALTER seam,存量库删库重建)。
+    -- 新列直接折进 CREATE(启动 DDL 不开 ALTER seam);存量库缺列 ⇒ 起服列册对账拒启并给出可粘贴的 ALTER 语句,由运维在升级前执行。
     peer_meta TEXT NULL,
+    -- decision(core 7.57.0 #972b):收件人设置留置的这条记录的**决定**(七词闭集 MAILBOX_DECISIONS);NULL = 从未 held。
+    -- 只经 moveDecision 的比较并设置移动,从不随 append 写;随记录生随记录亡(ack / reap / drop 删行即删它)—— 决定是记录自己的字段。
+    decision VARCHAR(16) NULL,
+    -- record_id(core 7.59.0):生产者铸的记录身份;NULL = 没说身份(每次 append 都是一条新记录)。盒持有一条这身份的记录时,append 经引擎的
+    -- judgeMailboxAppendById 判(同记录 ⇒ 答它的 seq、零写;不同 ⇒ mailbox.duplicate_record_id),判在 append 的盒行锁之内 —— 盒行 FOR UPDATE 串行了
+    -- 同一只盒的全部 append,「(scope, handle, id) 在持有行里至多一行」由它成立;ack / reap / drop 删行即还身份。宽 = 引擎的 MAILBOX_RECORD_ID_MAX_CHARS(列宽读那只常量,不抄数)。
+    record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) NULL,
     PRIMARY KEY (scope_key, handle, seq),
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
@@ -204,6 +244,8 @@ export async function ensurePgMailboxSchema(q) {
     sent_at_ms BIGINT NOT NULL,
     hop_chain TEXT COLLATE "C", -- core 5.17.0 design/176(TiDB twin 同注:NULL = 缺席且有语义)
     peer_meta TEXT COLLATE "C", -- S-90 core fc52b4d4 design/385 片2b(TiDB twin 同注:typed peer 记录 JSON;NULL = 缺席且有语义)
+    decision VARCHAR(16) COLLATE "C", -- core 7.57.0 #972b(TiDB twin 同注:留置决定,NULL = 从未 held;只经 moveDecision 移动,随记录亡)
+    record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) COLLATE "C", -- core 7.59.0(TiDB twin 同注:生产者铸的记录身份,NULL = 没说身份;盒行锁之内经引擎判,随记录亡)
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
@@ -242,8 +284,9 @@ export class TiDBMailboxStore {
     async append(scope, handle, msg) {
         assertMailboxKey("scope", scope);
         assertMailboxKey("handle", handle);
-        const hopChain = encodeHopChain(msg.hopChain);
-        const peerMeta = encodePeerMeta(msg.peerMeta);
+        const rec = appendSnapshot(msg);
+        const hopChain = encodeHopChain(rec.hopChain);
+        const peerMeta = encodePeerMeta(rec.peerMeta);
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
             let [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
@@ -254,9 +297,15 @@ export class TiDBMailboxStore {
             const [tomb] = await c.query(`SELECT 1 FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]);
             if (tomb.length > 0)
                 throw tombstonedRecipientError(scope, handle);
+            if (rec.id !== undefined) {
+                const [held] = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND record_id = ? FOR UPDATE`, [scope, handle, rec.id]);
+                const replay = replayedSeq(held, scope, handle, this.logger, { ...rec, content: asUtf8Stored(rec.content), ...(rec.from !== undefined ? { from: asUtf8Stored(rec.from) } : {}) });
+                if (replay !== undefined)
+                    return replay;
+            }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = ? WHERE scope_key = ? AND handle = ?`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, msg.from ?? null, msg.content, msg.sentAt, hopChain, peerMeta]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta, record_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [scope, handle, seq, rec.from ?? null, rec.content, rec.sentAt, hopChain, peerMeta, rec.id ?? null]);
             return seq;
         });
     }
@@ -274,7 +323,7 @@ export class TiDBMailboxStore {
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")} FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -295,6 +344,22 @@ export class TiDBMailboxStore {
             return { acked: true };
         });
     }
+    async moveDecision(scope, handle, seq, expect, next) {
+        assertMailboxDecisionMove(seq, expect, next);
+        if (keyless(scope, handle))
+            return { ok: false, current: "gone" };
+        return this.tx(async (c) => {
+            const [boxes] = await c.query(`SELECT 1 FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]);
+            if (boxes.length === 0)
+                return { ok: false, current: "gone" };
+            const [rows] = await c.query(`SELECT decision FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND seq = ? FOR UPDATE`, [scope, handle, seq]);
+            const verdict = decisionMoveVerdict(rows, expect);
+            if (verdict !== "write")
+                return verdict;
+            await c.query(`UPDATE ${MAILBOX_MSG_TABLE} SET decision = ? WHERE scope_key = ? AND handle = ? AND seq = ?`, [next, scope, handle, seq]);
+            return { ok: true };
+        });
+    }
     async releaseLease(scope, handle, owner) {
         if (keyless(scope, handle, owner))
             return;
@@ -384,11 +449,12 @@ export class PgMailboxStore {
     async append(scope, handle, msg) {
         assertMailboxKey("scope", scope);
         assertMailboxKey("handle", handle);
-        if (msg.from !== undefined && pgHasUnstorable(msg.from))
+        const rec = appendSnapshot(msg);
+        if (rec.from !== undefined && pgHasUnstorable(rec.from))
             throw new PgUnstorableError("mailbox from");
-        const content = pgSanitizeText(msg.content);
-        const hopChain = encodeHopChain(msg.hopChain);
-        const peerMeta = encodePeerMeta(msg.peerMeta);
+        const content = pgSanitizeText(rec.content);
+        const hopChain = encodeHopChain(rec.hopChain);
+        const peerMeta = encodePeerMeta(rec.peerMeta);
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                 scope,
@@ -407,9 +473,15 @@ export class PgMailboxStore {
             const { rows: tomb } = await c.query(`SELECT 1 FROM ${MAILBOX_TOMBSTONE_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (tomb.length > 0)
                 throw tombstonedRecipientError(scope, handle);
+            if (rec.id !== undefined) {
+                const { rows: held } = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("pg", "hop_chain")}, ${jsonColumnText("pg", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND record_id = $3 FOR UPDATE`, [scope, handle, rec.id]);
+                const replay = replayedSeq(held, scope, handle, this.logger, { ...rec, content });
+                if (replay !== undefined)
+                    return replay;
+            }
             const seq = Number(rows[0].next_seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET next_seq = $1 WHERE scope_key = $2 AND handle = $3`, [seq + 1, scope, handle]);
-            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [scope, handle, seq, msg.from ?? null, content, msg.sentAt, hopChain, peerMeta]);
+            await c.query(`INSERT INTO ${MAILBOX_MSG_TABLE} (scope_key, handle, seq, from_id, content, sent_at_ms, hop_chain, peer_meta, record_id) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [scope, handle, seq, rec.from ?? null, content, rec.sentAt, hopChain, peerMeta, rec.id ?? null]);
             return seq;
         });
     }
@@ -424,7 +496,7 @@ export class PgMailboxStore {
             const box = boxes[0];
             if (box.lease_owner !== null && Number(box.lease_expires_at_ms) > now && String(box.lease_owner) !== owner)
                 return null;
-            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("pg", "hop_chain")}, ${jsonColumnText("pg", "peer_meta")} FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
+            const { rows: msgs } = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("pg", "hop_chain")}, ${jsonColumnText("pg", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 ORDER BY seq FOR UPDATE`, [scope, handle]);
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -445,6 +517,22 @@ export class PgMailboxStore {
             return { acked: true };
         });
     }
+    async moveDecision(scope, handle, seq, expect, next) {
+        assertMailboxDecisionMove(seq, expect, next);
+        if (keyless(scope, handle))
+            return { ok: false, current: "gone" };
+        return this.tx(async (c) => {
+            const { rows: boxes } = await c.query(`SELECT 1 FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
+            if (boxes.length === 0)
+                return { ok: false, current: "gone" };
+            const { rows } = await c.query(`SELECT decision FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND seq = $3 FOR UPDATE`, [scope, handle, seq]);
+            const verdict = decisionMoveVerdict(rows, expect);
+            if (verdict !== "write")
+                return verdict;
+            await c.query(`UPDATE ${MAILBOX_MSG_TABLE} SET decision = $1 WHERE scope_key = $2 AND handle = $3 AND seq = $4`, [next, scope, handle, seq]);
+            return { ok: true };
+        });
+    }
     async releaseLease(scope, handle, owner) {
         if (keyless(scope, handle, owner))
             return;

package/dist/plugins/memory-key-guards.d.ts

@@ -15,6 +15,10 @@ export declare const MEMORY_SLUG_COLUMN_CHARS = 512;
  *  sync_cursor/push_queue/history)。`formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
  *  **膨胀**——非 ASCII principal 编码后可超列宽,故产出处与写口两道都要判。 */
 export declare const MEMORY_SCOPE_COLUMN_CHARS = 190;
+/** memory-sync 店 `sync_cursor.peer` 列宽(两方言 VARCHAR(190) 同宽)—— 中心侧请求的 `peer` 落这一列。两个读者:中心侧验型
+ *  (`memory-sync.ts` `parseMemorySyncRequest`,超宽 400)与客户端的身份铸点(`memory-sync-client.ts` `memorySyncPeerOf`,超宽拒启:
+ *  身份就是请求的 `peer`,装不进这一列的身份每一轮都会被中心拒)。 */
+export declare const MEMORY_SYNC_PEER_COLUMN_CHARS = 190;
 export declare function assertSlugWidth(slug: string): void;
 export declare function assertMemoryScopeWidth(scope: string): void;
 /**

package/dist/plugins/memory-key-guards.js

@@ -1,5 +1,6 @@
 export const MEMORY_SLUG_COLUMN_CHARS = 512;
 export const MEMORY_SCOPE_COLUMN_CHARS = 190;
+export const MEMORY_SYNC_PEER_COLUMN_CHARS = 190;
 function widthChars(v) {
     return [...v].length;
 }

package/dist/plugins/memory-run-store.d.ts

@@ -47,7 +47,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
      *  OBSERVED, see {@link CreateRunOutcome}) and the session has no active run (the task_active unique-key claim). */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: NewRunMeta): Promise<CreateRunOutcome>;
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
-     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
+     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement reject):
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;

package/dist/plugins/memory-sync-store-pg.d.ts

@@ -1,4 +1,3 @@
-import type { MemorySyncCursor } from "@sema-agent/core";
 import type { PgQueryFn } from "./pg-query.js";
 import { type IndexSpec } from "./ensure-index.js";
 /** Table names (single source). SAME names as the TiDB twin (the two dialects never share one DB). */
@@ -31,12 +30,24 @@ export interface ClaimedPushQueueItem {
     /** The lease deadline this claim holds the row until (nowMs + claimLeaseMs). */
     leasedUntilMs: number;
 }
+/**
+ * 中心侧的同步游标 = 本服务作同步**中心**时,每个 (scope, peer) 的基线(`sync_cursors` 一行)—— 本服务自己的事实,本服务自己的型。
+ * 它**不是**引擎的 `MemorySyncCursor`:那一只是同步**客户端**的游标,引擎 7.59.0 起必带 `store`(客户端本地 File 店的物理根,`memorySyncStoreOf` 铸),
+ * 绑的是「这份基线是对着哪一只本地店取的」;中心这一侧的条目平面是部署的 DB 后端,没有本地店根可绑,游标也从不交给引擎判。
+ * 此前本文件借用了引擎那只型名(两者当时同形),引擎给它加了只属于客户端的成员之后,借用就成了两个事实共用一个名字 —— 本型收回。
+ */
+export interface CentralSyncCursor {
+    readonly scope: string;
+    readonly peer: string;
+    readonly baseRevs: Readonly<Record<string, string>>;
+    readonly updatedAtMs: number;
+}
 /** The dialect-neutral contract both twins implement (anti-drift: one shared integration suite,
  *  test/memory-sync-store-db-integration.test.ts, runs the SAME scenarios against BOTH engines). */
 export interface MemorySyncStore {
-    getCursor(scope: string, peer: string): Promise<MemorySyncCursor | undefined>;
+    getCursor(scope: string, peer: string): Promise<CentralSyncCursor | undefined>;
     /** Whole-row replace (round semantics — baseRevs is swapped as one map, never merged). */
-    putCursor(cursor: MemorySyncCursor): Promise<void>;
+    putCursor(cursor: CentralSyncCursor): Promise<void>;
     enqueue(item: PushQueueItem): Promise<void>;
     /** Lease-claim up to `limit` due rows (next_attempt_at_ms <= nowMs), oldest-due first. Claimed rows
      *  are invisible to other claimers until `complete`/`fail` or lease expiry (crash self-heal). */
@@ -66,8 +77,8 @@ export declare class PgMemorySyncStore implements MemorySyncStore {
     private readonly query;
     private readonly claimLeaseMs;
     constructor(query: PgQueryFn, opts?: PgMemorySyncStoreOptions);
-    getCursor(scope: string, peer: string): Promise<MemorySyncCursor | undefined>;
-    putCursor(cursor: MemorySyncCursor): Promise<void>;
+    getCursor(scope: string, peer: string): Promise<CentralSyncCursor | undefined>;
+    putCursor(cursor: CentralSyncCursor): Promise<void>;
     enqueue(item: PushQueueItem): Promise<void>;
     claimDue(nowMs: number, limit: number): Promise<ClaimedPushQueueItem[]>;
     complete(id: string): Promise<void>;

package/dist/plugins/memory-sync-store-tidb.d.ts

@@ -1,5 +1,5 @@
 import type { ClaimedPushQueueItem, MemoryHistoryAppendRow, MemoryHistoryRow, MemoryHistoryStore, MemorySyncStore, PushQueueItem } from "./memory-sync-store-pg.js";
-import type { MemorySyncCursor } from "@sema-agent/core";
+import { type CentralSyncCursor } from "./memory-sync-store-pg.js";
 import type { Pool } from "mysql2/promise";
 /** Table names (single source) — SAME names as PG_MEMORY_SYNC_TABLES (the two dialects never share
  *  one database). */
@@ -21,8 +21,8 @@ export declare class TiDBMemorySyncStore implements MemorySyncStore {
     private readonly pool;
     private readonly claimLeaseMs;
     constructor(pool: Pool, opts?: TiDBMemorySyncStoreOptions);
-    getCursor(scope: string, peer: string): Promise<MemorySyncCursor | undefined>;
-    putCursor(cursor: MemorySyncCursor): Promise<void>;
+    getCursor(scope: string, peer: string): Promise<CentralSyncCursor | undefined>;
+    putCursor(cursor: CentralSyncCursor): Promise<void>;
     enqueue(item: PushQueueItem): Promise<void>;
     claimDue(nowMs: number, limit: number): Promise<ClaimedPushQueueItem[]>;
     complete(id: string): Promise<void>;

package/dist/plugins/one-time-migrations.d.ts

@@ -227,9 +227,12 @@
  *  · **M25 单用户记忆项目层换键形**(7.133.0)—— 不在店里、不在起服里(与 M10 同为**窗内才存在的行为臂**,但它是改写):项目层键从 `repo:<sha256(项目根)[:24]>`
  *    (7.98.0–7.132.x)换成带主体、跨设备的 `userrepo:<属主段>/<档>.<摘要>`(文法 `project-layer-key.ts`)。退役键是路径哈希、反推不出路径 ⇒ 起服没法枚举改写;
  *    改为**每个项目第一次跑任务时**由项目层准备一步(`memory-project-layer.ts` `createMemoryProjectLayers`)把该 checkout 的 `repo:` 层经 core `migrateScope`
- *    折进新键(File 与两只 SQL 孪生同一条;id 保留、CAS,冲突留原地下次再试)。同一窗同删的另一半:同步客户端腿的旧游标文件 `sync-cursor-<peer>.json`(只按 peer 分区)
- *    第一轮收编为同步层的新游标(`memory-sync-client.ts` `adoptLegacyCursor`)。本条不写起服读数(`reportKeys` 空,与 M7 / M10 同形);折了什么由运行期 info
- *    `memory_project_layer_folded` / `memory_sync_cursor_adopted` 说。常设的另一条律(`r` 档时本 checkout 的 `p` 档折进当前档)不是迁移,不随本条删。
+ *    折进新键(File 与两只 SQL 孪生同一条;id 保留、CAS,冲突留原地下次再试)。本条不写起服读数(`reportKeys` 空,与 M7 / M10 同形);折了什么由运行期 info
+ *    `memory_project_layer_folded` 说。常设的另一条律(`r` 档时本 checkout 的 `p` 档折进当前档)不是迁移,不随本条删。
+ *    **曾属本条的另一半已退役(如实)**:同步客户端腿的旧游标文件 `sync-cursor-<peer>.json`(只按 peer 分区)的收编臂。引擎 7.59.0 起游标必带店绑定 `store`,
+ *    升级前落盘的旧文件都没有这一员,收编的形判从不认它 ⇒ 臂对任何存量文件都不可达,已整条删码(收编函数、守卫旗标、日志行一并删,零引用有钉:
+ *    `test/memory-sync-client.test.ts`)。旧文件不再被当游标;它只回答「同步层有没有一份店绑定之前的基线」—— 新路径上没有文件而它是同步层的无绑定基线 ⇒
+ *    同步层不同步、运维通告点名它(与新路径上的无绑定游标同一条律,`memory-sync-client.ts` 头注 ⑤;不是本条的迁移臂,不随本条删)。
  *  · **M26 删掉退役的共享断路器表 `circuit_breaker`**(7.133.0)—— 断路器键的路由段从 baseUrl **原串**换成路由身份的摘要(铸点与形 `breaker-key.ts`),
  *    新一代键写**新表** `breaker_state`(中央 DDL 建)。旧表 `circuit_breaker` 的行是旧键(`<provider>:<id>@<baseUrl>`,网关根原串 query 可带凭据),
  *    新代码不读不写它、它也没有 TTL 腿 ⇒ 不删就永远在共享库里。**整只删表**(`DROP TABLE IF EXISTS circuit_breaker`,不看任何一行的内容):
@@ -284,6 +287,35 @@
  *    ≤7.136.x 的读者只认 `promptProfile`,读到本条改写过的体(旧键已删、换成 `promptLean`)回到缺省形 —— 本版副本起服之后仍在续跑的 7.136.x 副本、回滚到 7.136.x 之后,
  *    被改写过的 `"classic"` 行静默回短形;也不能给旧读者留旧键(那是同一事实的两份表示,本版读者对仍带旧键的体响亮拒)⇒ 升级序是**先停光 ≤7.136.x 副本、再起第一个 7.137.0 副本**,
  *    回滚之前先决完或取消停驻的任务(随包 MIGRATION 7.137.0 第 4 条;与 M28 的混跑登记同形)。
+ *  · **M31 记忆同步游标搬到每层一只的路径**(7.139.0,引擎 7.60.0)—— 一轮的对端改由 transport 的身份(规范化的中心基址)说,游标改成每层一只
+ *    `sync-cursors/<scope 摘要>.json`(对端是游标里的一格事实,只由引擎判)。升级前的游标落在上一版的分区目录 `sync-cursors/central/<同名>` 与更早的
+ *    `sync-cursor-central.json` —— 新路径上找不到它们 ⇒ 那几层以空基线首轮跑(没人选过的重收敛:上一轮之后在一侧删掉的条目从另一侧回来)。
+ *    ⇒ **同步执行器的第一轮先把它们搬到各自那一层的路径**(只 `rename`、字节不变;编排在 `memory-sync-client.ts` `relocateSyncCursorsM31`,不在本文件的
+ *    迁移段里 —— 那一段跑在 SQL 店层,游标是 File 记忆根下的文件),搬来的游标照常交引擎判:它们绑的对端是 `"central"`,不等于任何铸出的身份 ⇒
+ *    这一层拒同步并点名两条出路(运维确认同一只中心后把游标的 `peer` 改成新身份,或删游标接受空基线重收敛)。目标路径上已有游标 ⇒ 不搬、一行 warn;
+ *    更早的那只文件读不成对象 / 没有 scope ⇒ 原地不动、一行 warn。读数不进 {@link OneTimeMigrationReport}(`reportKeys` 空),逐文件一行 info / warn。窗外不搬。
+ *  · **M32 执行放置切换**(7.139.0)—— 执行放置是根会话行上这一位住客的一格(`execution-placement.ts` 头注),根会话 ↔ 设备的绑定是这一格的 writer(device, D);
+ *    ≤7.137.x 的绑定住在单独一张表 `device_session` 里(起服无条件建它)。运行期只有会话行一种读法 ⇒ **一次性**把绑定整行搬进会话行、表退役,存量有 run 的会话
+ *    回填放置。判据只有库自己的形(读者 = 本文件的两只在场探针 `tableExists` / `columnExists`):**切换开始** ⇔ `session_meta.execution_role` 列在 ∨ 中途表
+ *    `device_session_retired` 在;**切换收尾** ⇔ 八列都在 ∧ 两张绑定表都不在(这就是「跑过了」的标记,没有账表)。
+ *    · **DDL 前只读探针**({@link assertExecutionPlacementSwitchAdmissible},与退役 schema 探针同层、同一只调用点 —— `store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE ⇒ 拒时库零写;
+ *      全新库不判):**围栏(唯一一条)** 切换开始 ∧ `device_session` 在 ∧ 有行 ⇒ 拒 `fence`(旧版副本在切换开始后还在写它,或手写行 —— 谁新谁旧本服务判不出、不替人挑;
+ *      拒句按方言给「采旧 = 改名进中途表、起服时整行覆盖」/「弃旧 = DROP」两条语句与根会话列表);**回填前提** 切换未收尾 ∧ 车道表不是一元 ∧ 回填前提表里任一员答「还有」⇒ 拒 `backfill_ambiguous`
+ *      (今天车道表恒一元 ⇒ 这一臂在声明多车道之前不可达;回填前提表是有序可扩的一张,问行车道的那一员由审批店那一侧补)。码 `config.execution_placement_switch_refused`。
+ *    · **迁移段**(本段最后一步,锁内;切换已收尾 ⇒ 零动作;否则先在锁内复判围栏,再按有序步骤表逐步收敛 —— 每步先读形再判、DDL 按后置条件 `execUntil`):
+ *      ⓪ 切换开始 ∧ `device_session` 在(围栏判过 ⇒ 空的:旧版副本在已切换库上起服建回的空表)⇒ DROP · ① `device_session` 在 ∧ 执行列不在 ⇒ 改名成中途表(先于加列)·
+ *      ② 八列里缺的逐列 ADD(列定义 = 中央 DDL 内插的同一份)· ③ 中途表整行覆盖根会话行的 device 位(`rev` 原值、`bound_at → execution_placed_at`;根会话行不在 / 是委派分区行的孤儿丢弃并计数)·
+ *      ④ 有 run、没有执行格、不是委派分区行的会话行 ⇒ writer(表唯一项)(device 车道 ⇒ writer(device, ∅) = 有 run 而设备未知;不是一元表而还有要回填的 ⇒ 与探针同一只拒)·
+ *      (问行车道回填由审批店那一侧补在 ④ 之后)· ⑤ 中途表 DROP。中断 ⇒ 下一次起服从首个未满足的后置条件续(钉:真库逐步注入中断后续跑收敛、不触围栏)。
+ *    · **local 车道**:没有绑定表、没有 `session_meta`(device 车道只在 SQL 后端)⇒ 只有 ④ 与回填前提:读本地 run 店有 run 的会话,执行席读出 absent 的 ⇒ 经同一只席 `place` 成 writer(表唯一项)
+ *      (`LocalBackend.runOneTimeMigrations`);local 没有「切换收尾」的形可读 ⇒ 窗内每次起服都判,首跑之后它只碰认领与放置之间被打断的会话(与 `place` 会落下的格同值)。
+ *      有 run、而**存档读不出**的会话 —— 会话元数据格缺(升级链上从没被再读过的老会话)而探针读不出,或 fork 创建的格而探针说不出存档在不在 ——:回填跳过它并点名
+ *      (读数 `executionPlacementSessionsUnreadable` + 一行一条 warn `execution_placement_session_unreadable`,带会话 id 与故障词〔闭集 `corrupt_session` / `invalid_session` / `storage`;
+ *      `storage` = 读存档文件时抛了别的故障:权限 / 磁盘 I/O / 超大,再带 `errno`〕),**不拒启**、一个字节没写 —— 回填只补一格放置、不动存档,读不出的存档不归它判
+ *      (这一支只收**探针对这只会话的读故障**;会话元数据边档本身读不出、问账日志压实失败等整库级故障照旧拒启);该会话的请求照旧答存档的故障,存档修好(从留存副本恢复,
+ *      或 `storage` 时权限 / 磁盘修好)后的下一次起服照常补放置;存档移走则它不再是本服务的会话(不补放置、不再点名;fork 创建的会话例外 —— 它的格还在,读作 fork 未落定,出路是同键重试那次 fork 或删除该会话)。
+ *    · **旧版在已切换库上**:≤7.137.x 起服建回空 `device_session`,随后列册对账见执行列为幽灵列拒启、零行写;再起本版 ⇒ ⓪ 删掉那张空表。回滚的唯一支持形 = 恢复切换前的备份。
+ *    读数:`executionPlacementColumnsAdded` / `deviceBindingsMoved` / `deviceBindingsOrphaned`(非零 ⇒ 另一行 warn)/ `deviceBindingTablesDropped` / `executionPlacementsBackfilled` / `executionPlacementSessionsUnreadable`(点名数组 `{ sessionId, fault, errno? }`,只 local;一行一条 warn),收据只记起服日志行。
  *
  * ## 收据账(一次起服一只,每一条迁移同一只)
  * 每一步把它**已提交**的改写 / 删除与点名读数当场记进同一只收据账({@link MigrationReceipts}):计数随每次提交累加、行随每次提交追加、形读数在那一步落定时写。走完 ⇒
@@ -301,7 +333,11 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type AllowEntryInertReason, type GateKind } from "@sema-agent/core";
+import { StoreBootRefusalError } from "./store-contracts.js";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
+import type { ExecutionLane } from "../execution-lane-caps.js";
+import { type LocalPlacementBackfillSeat, type UnusableArchiveWord } from "../execution-placement.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
     /** M6:本次给「只有句子」的死亡判决行补上机读码的 run 行数(SQL `task_run` / local `run.json`)。非零 = 这次迁移真写了存量行,必须让运维看见。 */
@@ -372,6 +408,21 @@ export interface OneTimeMigrationReport {
     /** M29:该回填、卡词却放不进列的停驻行 —— 门上的卡词超过 `approval_card` 列的容量(MySQL 协议方言 TEXT = 65,535 UTF-8 字节;PG 无上限,恒空)。引擎铸不出这样的词,
      *  只会是手改 / 外来写者写下的行;一个字节没写(列留 NULL,读面按缺列读 —— 与「无卡」同读),起服不挡。一行一条 warn 点名(会话 id + 字节数)。SQL 独有;local 恒空。 */
     readonly parkedApprovalCardRowsTooLong: readonly ParkedApprovalCardRowTooLong[];
+    /** M32:本次给 `session_meta` 补上的执行放置列数(八列里缺的那几列;新库 / 切换已收尾恒 0)。非零 = 这次真改了表形。SQL 独有;local 恒 0。 */
+    readonly executionPlacementColumnsAdded: number;
+    /** M32:本次从退役的绑定表(经中途名)整行搬进根会话行执行格的绑定数(驱动回报的受影响行数)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingsMoved: number;
+    /** M32:搬的时候指向的根会话行不在(或是委派分区行)⇒ 丢弃的绑定数(非零 ⇒ 另一行 warn 点名条数)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingsOrphaned: number;
+    /** M32:本次删掉的绑定表数(⓪ 空的退役表 / ⑤ 搬完的中途表;0–2)。SQL 独有;local 恒 0。 */
+    readonly deviceBindingTablesDropped: number;
+    /** M32:本次回填的执行放置数(有 run 行、没有执行格的会话 ⇒ writer(表唯一项))。SQL 与 local 都有。非零 = 真写了存量行。 */
+    readonly executionPlacementsBackfilled: number;
+    /** M32 ④b:本次回填了出处车道的问行数(车道未回填的问行 ⇒ 根会话放置的车道,无放置 / 无会话行 ⇒ 表唯一项)。SQL 与 local(问账日志一次压实)都有。非零 = 真写了存量行。 */
+    readonly askExecutionLanesBackfilled: number;
+    /** M32 local 腿:该回填放置、却读不出的会话 —— 有 run、存档读不出(会话头读不出 / 结构走不通 / 读存档文件时抛了别的故障:权限 / 磁盘 I/O / 超大)。一个字节没写,起服不挡:
+     *  该会话的请求照旧答存档的故障;存档修好(从留存副本恢复,或权限 / 磁盘修好)后的下一次起服照常补放置。点名行数组(会话 id + 故障词,`storage` 再带 errno),一行一条 warn,每次起服都报直到处置。SQL 独有的反面:SQL 没有这一形(行就是会话);SQL 恒空。 */
+    readonly executionPlacementSessionsUnreadable: readonly ExecutionPlacementSessionUnreadable[];
 }
 /** 退役的两只命令桶(引擎 7.51.0 起不是桶;只给 M17 点名认)。 */
 export type RetiredSessionRuleBucket = "commandAllow" | "commandDeny";
@@ -412,6 +463,16 @@ export interface ParkedApprovalCardRowUnreadable {
 export interface ParkedApprovalCardRowTooLong extends ParkedApprovalCardRowUnreadable {
     readonly bytes: number;
 }
+/**
+ * M32 local 腿被跳过的一只会话:会话 id 是点名坐标;故障词是闭集 {@link UnusableArchiveWord}(`corrupt_session` = 会话头读不出;`invalid_session` = 读得出、结构走不通;
+ * `storage` = 读的时候抛了别的故障,I/O 级 —— 权限 / 磁盘 / 超大,此时 `errno` 带那只故障的 `code`)。盘上路径与故障句不出店。
+ */
+export interface ExecutionPlacementSessionUnreadable {
+    readonly sessionId: string;
+    readonly fault: UnusableArchiveWord;
+    /** 仅 `fault === "storage"` 且那只故障带字符串 `code` 时在场(`EACCES` / `EIO` / `ERR_STRING_TOO_LONG` ……)。 */
+    readonly errno?: string;
+}
 /** 三个形读数(M9 主键 / M17 列名 / M24 scope 列)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
 type ShapeReadingKey = "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
 /**
@@ -482,8 +543,8 @@ export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow,
  * 还没有日期可写)⇒ 响亮抛,不铸一句带空日期的句子。
  */
 export declare function migrationWindowEnd(id: string): string;
-/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
-export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled">;
+/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 与 M32 的回填两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
+export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled" | "executionPlacementsBackfilled" | "askExecutionLanesBackfilled" | "executionPlacementSessionsUnreadable">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
 export interface MigrationLogSink {
     warn(msg: string, meta?: Record<string, unknown>): void;
@@ -516,7 +577,57 @@ export interface MigrationDb {
  * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了(起服对账一族 `schema-consistency.ts` 的探针口,先于建表);走公开序列
  * `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()` 的嵌入方与本服务的起服序列一样,有这一问、零动作。
  */
-export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool): Promise<OneTimeMigrationReport>;
+export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<OneTimeMigrationReport>;
+/** M32 的起服拒码(确定的拒启表态:再等也等不来另一个答案;不是线上 wire 码,与 `config.schema_mismatch` 同一族)。 */
+export declare const EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE = "config.execution_placement_switch_refused";
+/** 拒因闭集:`fence` = 切换开始之后退役绑定表里又出现了行(旧版副本 / 手工写下的);`backfill_ambiguous` = 车道表不止一项而还有要回填的存量。 */
+export type ExecutionPlacementSwitchRefusalReason = "fence" | "backfill_ambiguous";
+/**
+ * M32 的起服拒(DDL 前探针与迁移段同一只错误)。具名类型 + 机读码 + 拒因:日志消费端与测试按 `code` / `reason` 分派,不锚文案。
+ * 继承 {@link StoreBootRefusalError}:SQL 开库的等待窗不重试它(确定的拒启表态)。
+ */
+export declare class ExecutionPlacementSwitchRefusedError extends StoreBootRefusalError {
+    readonly reason: ExecutionPlacementSwitchRefusalReason;
+    readonly code = "config.execution_placement_switch_refused";
+    constructor(reason: ExecutionPlacementSwitchRefusalReason, detail: string);
+}
+/** M32 的输入:本部署声明的有序执行车道表(本版 `REMOTE_EXEC` 单值 ⇒ 一元表,`deployedExecutionLanes`)。回填只在一元表下有唯一答案。 */
+export interface ExecutionPlacementSwitchInput {
+    readonly lanes: readonly ExecutionLane[];
+}
+/**
+ * M32 的 **DDL 前只读探针**(与退役 schema 探针同层、同一只调用点:`store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE):围栏与回填前提。
+ * 拒在任何 DDL 之前 ⇒ 库零写。全新库(没有 `session_meta`)不判。纯读,不取 schema 锁(与退役 schema 探针同理)。
+ */
+export declare function assertExecutionPlacementSwitchAdmissible(read: SchemaProbeRead, dialect: "tidb" | "pg", input: ExecutionPlacementSwitchInput): Promise<void>;
+/** 探针口(入参形与本文件的迁移段入口 {@link runSqlOneTimeMigrations} 同:方言 + 它的池;借一条连接,用完即还)。 */
+export declare function assertExecutionPlacementSwitchAdmissibleOnPool(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<void>;
+/**
+ * M32(规则与理由见头注 M32 段):切换已收尾(八列在 ∧ 两张绑定表都不在)⇒ 零动作;否则先复判围栏(探针之后、锁内这一刻又有旧版副本写进行 ⇒ 同一只拒),
+ * 再按步骤表逐步收敛。跑在一次性迁移的锁里(与别的迁移步同一条连接)。导出给真库钉驱动「每步中断后续跑」。
+ */
+export declare function switchExecutionPlacement(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts, input: ExecutionPlacementSwitchInput): Promise<void>;
+/** {@link backfillLocalExecutionPlacements} 的结果:回填了几只会话 · 读不出而被跳过的会话(点名)。 */
+export interface LocalPlacementBackfill {
+    readonly backfilled: number;
+    readonly unreadable: readonly ExecutionPlacementSessionUnreadable[];
+}
+/**
+ * M32 的 **local 腿**(local 车道没有绑定表、没有 `session_meta`,只有 ④ 与回填前提):本地 run 店里有 run 的会话(`FileRunStore.sessionIdsWithRuns`),
+ * 执行席读出 absent 的 ⇒ 经**同一只席**的 `place` 写成 writer(表唯一项)(写只按住客谓词;forking / mirror / writer 与行不在的一律不碰)。
+ * 席读出「存档读不出」({@link LocalPlacementBackfillSeat}:会话头读不出 / 结构走不通 / 读的时候抛了别的故障 —— I/O 级的权限、磁盘、超大)⇒ **跳过并点名**
+ * (`unreadable`:会话 id + 故障词〔闭集 {@link UnusableArchiveWord}〕,`storage` 再带 errno;一个字节没写,不拒启):
+ * 回填不动存档、只补一格放置,读不出的存档不归它判;该会话的请求照旧答存档的故障,存档修好后的下一次起服照常补。读不出的会话不计入「还有要回填的」。
+ * 车道表不是一元而还有 absent 的 ⇒ 与 SQL 同一只拒(`backfill_ambiguous`),一个字节没写。起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前;数据根独占)。
+ */
+export declare function backfillLocalExecutionPlacements(sessionIds: Iterable<string>, seat: LocalPlacementBackfillSeat, input: ExecutionPlacementSwitchInput): Promise<LocalPlacementBackfill>;
+/**
+ * M32 ④b 的 **local 腿**:问账日志里升级前写下的问(没有出处车道)记成车道表的唯一项,一次压实重写整本账(`FileApprovalAskStore.backfillExecutionLanes`)。
+ * 车道表不是一元而还有缺车道的问 ⇒ 与 SQL 同一只拒(`backfill_ambiguous`),一个字节没写。返回回填数。起服时调(与 ④ 的 local 腿同位,任何读者之前)。
+ */
+export declare function backfillLocalAskExecutionLanes(store: {
+    backfillExecutionLanes(lanes: readonly ExecutionLane[], refuse: (pending: number) => never): number;
+}, input: ExecutionPlacementSwitchInput): number;
 /**
  * M24(7.133.0)—— workflow journal 的属主 scope 从逐行列搬进 `workflow_journal_owner` 一行,journal 行改按 `(run_id, incarnation, ordinal)` 记。规则与理由在
  * 头注 M24 段;这里只写各步为什么这样写。