@sema-agent/server 7.138.0 → 7.140.0

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

@@ -9,6 +9,7 @@ import { recordFailOpen } from "../observability/fail-open.js";
 import { durableRowIdentity, withoutCheckpointToken } from "../checkpoint-identity.js";
 import { mysqlDriver, pgDriver, dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLargeError } from "./sql-errors.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { approvalPayloadFingerprint } from "./approval-payload-fingerprint.js";
 const CTX_REWRITE_PAGE = 500;
@@ -61,13 +62,10 @@ export async function assertCheckpointColumnSchema(query, dialect) {
                 throw err;
             throw new Error(`checkpoint is missing the column ${column} — refusing to start. ` +
                 `On this table ${breaksAt} — at runtime, after a healthy-looking boot. ` +
-                "This repository ships no ALTER TABLE migrations, so the table must be recreated: run " +
-                "`DROP TABLE checkpoint;` on the " +
-                (dialect === "pg" ? "PostgreSQL" : "MySQL-protocol") +
-                " backend and restart — the schema is recreated at boot. The cost is bounded but real: the table holds IN-FLIGHT " +
-                "durable parks (suspended approvals/reviews awaiting a decision) — those cards are lost and their runs must be " +
-                "re-triggered; `checkpoint_ctx`, run rows and every other persistent face are untouched. " +
-                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+                "The table holds IN-FLIGHT durable parks (suspended approvals/reviews awaiting a decision), so the way forward is an in-place " +
+                "ALTER that keeps them; `checkpoint_ctx`, run rows and every other persistent face are untouched.\n" +
+                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                (await describeProbedTableDrift(query, dialect, ["checkpoint"])));
         }
     }
 }
@@ -345,8 +343,8 @@ export class SqlCheckpointStore {
         this.logger = logger;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     json(value, label) {
         return dialectProtocolJsonEncoder(this.db.dialect)(value, label);
@@ -355,7 +353,7 @@ export class SqlCheckpointStore {
         return isDupKeyError(this.db.dialect, e);
     }
     ph(n) {
-        return this.db.dialect === "tidb" ? "?" : `$${n}`;
+        return this.db.dialect === "mysql" ? "?" : `$${n}`;
     }
     pendingRowQuery(select, sessionId, scope, binding) {
         const params = [sessionId];
@@ -426,8 +424,8 @@ export class SqlCheckpointStore {
         }
     }
     async get(token) {
-        const { rows } = await this.db.query(this.q(`SELECT version, status, ${jsonColumnText("tidb", "checkpoint")}, ${jsonColumnText("tidb", "outcome")}, reopen_reason, rev, ` +
-            `${jsonColumnText("tidb", "pending_steer_queue")}, ${jsonColumnText("tidb", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT version, status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
+        const { rows } = await this.db.query(this.q(`SELECT version, status, ${jsonColumnText("mysql", "checkpoint")}, ${jsonColumnText("mysql", "outcome")}, reopen_reason, rev, ` +
+            `${jsonColumnText("mysql", "pending_steer_queue")}, ${jsonColumnText("mysql", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = ?`, `SELECT version, status, ${jsonColumnText("pg", "checkpoint")}, ${jsonColumnText("pg", "outcome")}, reopen_reason, rev, ` +
             `${jsonColumnText("pg", "pending_steer_queue")}, ${jsonColumnText("pg", "execution_outcome")}, execution_at_ms FROM checkpoint WHERE token = $1`), [token]);
         const r = rows[0];
         if (!r)
@@ -482,7 +480,7 @@ export class SqlCheckpointStore {
     }
     async recordExecutionOutcome(token, scope, gate) {
         for (let attempt = 0; attempt < EXECUTION_RECORD_CAS_ATTEMPTS; attempt++) {
-            const { rows } = await this.db.query(this.q(`SELECT scope, status, ${jsonColumnText("tidb", "execution_outcome")} FROM checkpoint WHERE token = ?`, `SELECT scope, status, ${jsonColumnText("pg", "execution_outcome")} FROM checkpoint WHERE token = $1`), [token]);
+            const { rows } = await this.db.query(this.q(`SELECT scope, status, ${jsonColumnText("mysql", "execution_outcome")} FROM checkpoint WHERE token = ?`, `SELECT scope, status, ${jsonColumnText("pg", "execution_outcome")} FROM checkpoint WHERE token = $1`), [token]);
             const row = rows[0];
             const facts = row === undefined
                 ? undefined
@@ -506,7 +504,7 @@ export class SqlCheckpointStore {
     async setPendingSteer(token, scope, steer) {
         const clean = validatePendingSteer(steer);
         for (let attempt = 0; attempt < STEER_CAS_ATTEMPTS; attempt++) {
-            const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("tidb", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = ? AND scope = ?`, `SELECT status, ${jsonColumnText("pg", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = $1 AND scope = $2`), [token, scope]);
+            const { rows } = await this.db.query(this.q(`SELECT status, ${jsonColumnText("mysql", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = ? AND scope = ?`, `SELECT status, ${jsonColumnText("pg", "pending_steer_queue")}, pending_steer_rev FROM checkpoint WHERE token = $1 AND scope = $2`), [token, scope]);
             const row = rows[0];
             if (!row || row.status !== "pending")
                 return false;
@@ -539,12 +537,12 @@ export class SqlCheckpointStore {
     }
     async reapExpired(cutoff) {
         const res = await this.db.query(this.q("UPDATE checkpoint SET status = 'expired', decided_at_ms = ? " +
-            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND COALESCE(${CHECKPOINT_FACET_SQL.tidb}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
+            `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= ? AND COALESCE(${CHECKPOINT_FACET_SQL.mysql}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= ?))`, "UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 " +
             `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND COALESCE(${CHECKPOINT_FACET_SQL.pg}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
     async listExpiredApprovalGates(cutoff, limit = 100) {
-        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.tidb} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit]);
+        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit]);
         return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
     }
     async listPending(scope) {
@@ -593,7 +591,7 @@ export class SqlCheckpointStore {
         return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
     }
     async readParkedSkillCardFacts(token) {
-        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "checkpoint")} FROM checkpoint WHERE token = ? AND status = 'pending'`, `SELECT ${jsonColumnText("pg", "checkpoint")} FROM checkpoint WHERE token = $1 AND status = 'pending'`), [token]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "checkpoint")} FROM checkpoint WHERE token = ? AND status = 'pending'`, `SELECT ${jsonColumnText("pg", "checkpoint")} FROM checkpoint WHERE token = $1 AND status = 'pending'`), [token]);
         const r = rows[0];
         if (r === undefined)
             return {};
@@ -616,7 +614,7 @@ export class SqlCheckpointStore {
         }
     }
     async listByScope(scope) {
-        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500`, `SELECT ${jsonColumnText("pg", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500`), [scope]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = ? ORDER BY created_at_ms ASC LIMIT 500`, `SELECT ${jsonColumnText("pg", "checkpoint")}, status FROM checkpoint WHERE status = 'pending' AND scope = $1 ORDER BY created_at_ms ASC LIMIT 500`), [scope]);
         const out = [];
         for (const r of rows) {
             const cp = refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(r.checkpoint, `in the ${scope} scheduler view`));
@@ -635,7 +633,7 @@ export class SqlCheckpointStore {
         return rows[0] ? String(rows[0].token) : null;
     }
     async findCheckpointCandidatesForAsk(scope, sessionId, toolCallId, sinceMs) {
-        const { rows } = await this.db.query(this.q(`SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("tidb", "checkpoint")} FROM checkpoint ` +
+        const { rows } = await this.db.query(this.q(`SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("mysql", "checkpoint")} FROM checkpoint ` +
             "WHERE scope=? AND session_id=? AND created_at_ms>=? AND (tool_call_id=? OR tool_call_id IS NULL) ORDER BY created_at_ms ASC", `SELECT token, status, created_at_ms, tool_call_id, bound_input_hash, version, ${jsonColumnText("pg", "checkpoint")} FROM checkpoint ` +
             "WHERE scope=$1 AND session_id=$2 AND created_at_ms>=$3 AND (tool_call_id=$4 OR tool_call_id IS NULL) ORDER BY created_at_ms ASC"), [scope, sessionId, sinceMs, toolCallId]);
         const out = [];
@@ -673,7 +671,7 @@ export class SqlCheckpointStore {
         return out;
     }
     async findDecidedApprovalsForBinding(sessionId, boundCallId) {
-        const { rows } = await this.db.query(this.q(`SELECT scope, bound_input_hash, ${jsonColumnText("tidb", "outcome")}, ${jsonColumnText("tidb", "execution_outcome")} FROM checkpoint ` +
+        const { rows } = await this.db.query(this.q(`SELECT scope, bound_input_hash, ${jsonColumnText("mysql", "outcome")}, ${jsonColumnText("mysql", "execution_outcome")} FROM checkpoint ` +
             `WHERE session_id=? AND tool_call_id=? AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`, `SELECT scope, bound_input_hash, ${jsonColumnText("pg", "outcome")}, ${jsonColumnText("pg", "execution_outcome")} FROM checkpoint ` +
             `WHERE session_id=$1 AND tool_call_id=$2 AND status='resolved' AND decided_at_ms IS NOT NULL ORDER BY decided_at_ms DESC LIMIT ${DECIDED_REPLAY_SCAN_CAP}`), [sessionId, boundCallId]);
         return rows.map((r) => {
@@ -735,14 +733,14 @@ export class SqlCheckpointStore {
         }
     }
     async getCtx(sessionId) {
-        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
+        const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
     async rewriteCtxRows(rewrite) {
         const out = { scanned: 0, rewritten: 0, valuesRewritten: 0, unreadable: 0, tooLarge: 0 };
         let after = "";
         for (;;) {
-            const { rows } = await this.db.query(this.q(`SELECT session_id, ${jsonColumnText("tidb", "ctx")} FROM checkpoint_ctx WHERE session_id > ? ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`, `SELECT session_id, ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id > $1 ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`), [after]);
+            const { rows } = await this.db.query(this.q(`SELECT session_id, ${jsonColumnText("mysql", "ctx")} FROM checkpoint_ctx WHERE session_id > ? ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`, `SELECT session_id, ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id > $1 ORDER BY session_id LIMIT ${CTX_REWRITE_PAGE}`), [after]);
             for (const row of rows) {
                 const sessionId = String(row.session_id);
                 after = sessionId;
@@ -791,7 +789,7 @@ export class SqlCheckpointStore {
     }
     async deleteBySession(sessionId, owner) {
         const ownerGuard = this.q("EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = ? AND sm.owner <=> ?)", "EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = $1 AND sm.owner IS NOT DISTINCT FROM $2)");
-        const params = this.db.dialect === "tidb" ? [sessionId, sessionId, owner] : [sessionId, owner];
+        const params = this.db.dialect === "mysql" ? [sessionId, sessionId, owner] : [sessionId, owner];
         const res = await this.db.query(this.q(`DELETE FROM checkpoint WHERE session_id = ? AND ${ownerGuard}`, `DELETE FROM checkpoint WHERE session_id = $1 AND ${ownerGuard}`), params);
         await this.db.query(this.q(`DELETE FROM checkpoint_ctx WHERE session_id = ? AND ${ownerGuard}`, `DELETE FROM checkpoint_ctx WHERE session_id = $1 AND ${ownerGuard}`), params);
         return res.affected;

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

@@ -1,14 +1,16 @@
 /**
- * device lane 四表持久层(design/device-executor-lane-v2 §6)—— `DeviceStore` 双方言实现
+ * device lane 三表持久层(design/device-executor-lane-v2 §6)—— `DeviceStore` 双方言实现
  * (`TiDBDeviceStore` / `PgDeviceStore`,SINGLE-FILE DUAL-DIALECT,[ref] A12 形:一个
  * `SqlDeviceStore` 接 `SqlDriver`,两个薄 ctor 子类落方言绑定)。语义真源 = `../device-store.js`
  * (类型 + 闭集 + InMemory 参照实现),准入链 = `../device-enrollment.js`。
  *
- * 四张表:
+ * 三张表:
  *   · `devices`              —— 设备注册簿 + presence 投影(单设备单活连 ⇒ 1:1,省一次 join,§6 注①)
  *   · `device_enroll_tokens` —— 一次性 enrollment 凭据(明文一现,落库只有 sha256)
- *   · `device_sessions`      —— **根会话**↔设备绑定(resume 路由真源,§4.5)
  *   · `device_audit`         —— 安全轴事件审计(§4.8 标「审计行」的 8 个 event)
+ * **根会话 ↔ 设备绑定不在本店的表里**:它是根会话行(`session_meta`)上这一位住客的执行格 writer(device, D)(列与语句的唯一属主 =
+ * `execution-placement-sql.ts`;规则在 `../execution-placement.ts` 头注)。读只经会话店的执行席 `seat.read(root)`;本店只有两只写 ——
+ * 首绑 {@link SqlDeviceStore.placeDeviceExecution} 与换绑 {@link SqlDeviceStore.rebindDeviceExecution},各是一只事务,锁序全局一条:设备行 → 根 `session_meta` → `task_*`。
  * 刻意**没有** `device_instructions` 表:指令 pending 表是内存态(§6 注③——指令比 run 短命,落库只会
  * 造「表里 pending、run 已死」的僵尸行;at-most-once 靠 §5.3 投递边界,不靠指令落库)。
  *
@@ -26,7 +28,6 @@
  *
  * ── 方言差异(A12 doctrine:每处显式写在调用点)────────────────────────────────────────────────────
  *   - `?`(位置序) vs `$n`(显式编号);动态 WHERE(`listAudit`)靠 `ph(dialect, n)` 生成。
- *   - `INSERT IGNORE` vs `ON CONFLICT (pk) DO NOTHING`(`bindSession` 的首绑 CAS)。
  *   - `AUTO_INCREMENT` vs `BIGSERIAL`;`JSON` vs `JSONB`(+ `$n::jsonb` 显式 cast)。
  *   - `KEY …` 内联 vs 独立 `CREATE INDEX IF NOT EXISTS`。
  *   - 回读名单:两方言**同走**同事务 `UPDATE` 后 `SELECT`(PG 本可用 RETURNING,为保单一读路径不用——
@@ -46,19 +47,18 @@
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
-import { type AcquireConnectionInput, type AcquireConnectionResult, type AppendAuditInput, type BindSessionInput, type BindSessionResult, type ConsumeEnrollTokenInput, type ConsumeEnrollTokenResult, type DeviceAdmissionView, type DeviceAuditRow, type DeviceEnrollTokenRow, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type HeartbeatConnectionInput, type IssueEnrollTokenInput, type ListAuditFilter, type RebindSessionInput, type RebindSessionResult, type RevokeDeviceInput, type RevokeDeviceResult } from "../device-store.js";
+import { type AcquireConnectionInput, type AcquireConnectionResult, type AppendAuditInput, type ConsumeEnrollTokenInput, type ConsumeEnrollTokenResult, type DeviceAdmissionView, type DeviceAuditRow, type DeviceEnrollTokenRow, type DeviceOwner, type DeviceRow, type DeviceStore, type HeartbeatConnectionInput, type IssueEnrollTokenInput, type ListAuditFilter, type PlaceDeviceExecutionInput, type PlaceDeviceExecutionResult, type RebindDeviceExecutionInput, type RebindDeviceExecutionResult, type RevokeDeviceInput, type RevokeDeviceResult } from "../device-store.js";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * ── 命名(**落库一律单数**,与设计稿的复数形不同)──────────────────────────────────────────────────
- * design v2 §6 的 DDL 写的是 `devices` / `device_sessions` / `device_enrollment_tokens`(复数),但本仓有一条
+ * design v2 §6 的 DDL 写的是 `devices` / `device_enrollment_tokens` / `device_audit`(复数),但本仓有一条
  * 常驻机器门:`test/schema-naming-invariants.test.ts` 判据① —— 建表的表名必须在 `TABLE_VOCABULARY` 闭集里
  * **且词表全是单数形**。[ref] 车1 的 `retention_hold` / `retention_tombstone` 是同一处先例(那份设计稿同样
- * 写的复数,落库单数)。所以四张表落库名为 `device` / `device_session` / `device_enroll_token` /
+ * 写的复数,落库单数)。所以三张表落库名为 `device` / `device_enroll_token` /
  * `device_audit`,**表结构与设计稿逐列一致**,只有名字随仓规。新表 = 先进词表再建。
  */
 export declare const DEVICES_TABLE = "device";
 export declare const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
-export declare const DEVICE_SESSIONS_TABLE = "device_session";
 export declare const DEVICE_AUDIT_TABLE = "device_audit";
 export declare const TIDB_DEVICE_STATEMENTS: readonly string[];
 /** {@link TIDB_DEVICE_STATEMENTS} 的遍历壳(集成测试用;生产装配由中央 ensureSchema 展开同一份数组)。 */
@@ -134,55 +134,29 @@ export declare class SqlDeviceStore implements DeviceStore {
     heartbeatConnection(input: HeartbeatConnectionInput): Promise<boolean>;
     releaseConnection(deviceId: string, generation: number): Promise<boolean>;
     /**
-     * §4.3.2 首绑写协议 —— **单事务**:设备校验(active ∧ owner)与首绑 CAS 插入在一个事务里。
-     *
-     * 🔴 `FOR UPDATE`(设备行):设备行必须是**当前读**。普通读下,一次与吊销并发的绑定会读到「还 active」
-     * 的旧版本,于是把 session 绑到一台**刚被吊销**的设备上(double-admit 形)。锁读在两引擎都是当前读 ——
-     * 前提写在 {@link SqlTxConn.begin} 的 @contract txn.read-semantics。这把锁在 `devices` 表上,与下面
-     * 被插入的 `device_session` 行不是同一行。
-     *
-     * 🔴 形 B · cas-insert([ref] / [ref])—— 本站点是全仓 `INSERT IGNORE` 的**正当用法**:
-     * `INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected(1/0)是引擎对「谁赢」的**权威**回答,而
-     * `ON DUPLICATE KEY UPDATE pk = pk` 的 affected 新行/既有行都是 1、分不出赢家 ⇒ 这里换不得动词。
-     * 代价必须付清:**同一事务此后不得对被插入的那一行做加锁读**。InnoDB 下撞重复键的 IGNORE 在既有行
-     * 取 **S 锁**,随后的 `SELECT … FOR UPDATE` 要升 X;两个并发首绑各持一把 S 互等 ⇒ ER_LOCK_DEADLOCK
-     * (TiDB 悲观事务无共享锁,这一形在它上面恒绿 —— 双库门看不见)。于是两条路径分家:
-     *  · **赢家**(affected === 1):行是自己刚插的,回执用**入参 + 插入时刻**直接构造,零回读。插入时刻
-     *    仍由 **DB 时钟**给出(插入前一句 `SELECT NOW(3)` / `SELECT now()`,再把它当参数写进 INSERT)——
-     *    时间权威留在 DB,回执里的 `boundAtMs` 与落库值**逐字节同一个**,不是应用侧的近似。
-     *  · **输家**(affected === 0):**结束当前事务**,在**新事务**里 `SELECT … FOR UPDATE` 观察。那一刻
-     *    赢家已提交,读到的是一把干净的 X 锁(无升级);判 同 deviceId = 幂等成功,异 deviceId =
-     *    `conflict`(无未定义态)。设备状态门在输家路径上已经过完,不需要重来。
+     * 设备行的**当前读**(`FOR UPDATE`):首绑 / 换绑两只事务的第一句(全局锁序的第一把:设备行 → 根 `session_meta` → `task_*`)。
+     * 普通读下,一次与吊销并发的绑定会读到「还 active」的旧版本,于是把会话绑到一台**刚被吊销**的设备上(double-admit 形);锁读在两引擎都是当前读 ——
+     * 前提写在 {@link SqlTxConn.begin} 的 @contract txn.read-semantics。行不在 / 不是该属主的 ⇒ `undefined`(反枚举同形)。
      */
-    bindSession(input: BindSessionInput): Promise<BindSessionResult>;
+    private lockDeviceStatus;
     /**
-     * 首绑 CAS 的**输家观察**(形 B 的后半,[ref])—— 独立事务,与那次 `INSERT IGNORE` 无锁关系。
+     * §4.3.2 首绑(§3.3 转换表 place / bind 两行)—— **一只事务**:锁设备行(active ∧ 属主)→ 锁定读根会话行的执行格 → 判官
+     * {@link settledDeviceBindOutcome}(与内存参照实现同一只)→ absent 用 place 语句、writer(device, ∅) 用 bind 语句,写只按住客谓词。
      *
-     * 🔴 `FOR UPDATE`(**真库红修**,2026-08-28 双库跑当场抓到,mock 抓不到):TiDB 的悲观事务里**普通
-     * SELECT 仍是快照读**(读的是本事务 start_ts 的视图),只有加锁读才是当前读。放在新事务里读同样要
-     * 这把锁 —— 新事务的 start_ts 虽在赢家提交之后,但「读的是不是当前」这条判据不该靠时序巧合来满足。
-     * 与旧形的**唯一**差别:此刻我们手上没有那一行的 S 锁,于是这把 X 是**直接取**的,不是升级 ⇒ 两个
-     * 并发输家不会互等([ref] 的死锁形正是那次升级)。
-     *
-     * 行不在 = 赢家的绑定在这一瞬被 `unbindSession` 删了(真实可能,不是不变量破)。这仍然是**响亮**的:
-     * 首绑既没成、也说不出冲突对象,折成任何一种业务回执都是撒谎([ref]:未知失败不伪装成正常拒绝)。
+     * 不读认领:这是认领持有者自己的初始放置写(读写序律唯一的例外,`execution-placement-sql.ts` 头注)。锁序:设备行 → 根 `session_meta`。
+     * 持着根行的锁判过「可写」之后那句 UPDATE 不可能 0 行 —— 0 行即驱动 / 引擎异常,响亮抛,不折成业务分支([ref])。
+     * 并发两只首绑在根行锁上串行:输家的锁定读看到赢家的格 ⇒ 同设备 `same`(幂等成功)/ 异设备 `device_conflict`(单赢家,无未定义态);
+     * 修前的 `INSERT IGNORE` 撞键 S 锁升级死锁形([ref])在这里不存在 —— 两边取的都是同一行的 X 锁,没有升级。
      */
-    private observeLostBind;
+    placeDeviceExecution(input: PlaceDeviceExecutionInput): Promise<PlaceDeviceExecutionResult>;
     /**
-     * O4 显式换绑(2026-08-30 v2 稿 §2)—— **单事务**:目标设备门(当前读)+ 幂等短路 + 前态 CAS +
-     * `session_rebound` 审计行一起提交。三形语义 oracle = `InMemoryDeviceStore.rebindSession`。
-     *
-     * 🔴 两次 `FOR UPDATE`(bindSession 的同一条真库红的射程;当前读的前提见
-     * {@link SqlTxConn.begin} 的 @contract txn.read-semantics):
-     *  · 设备行必须当前读 —— 快照读会把「与吊销并发的换绑」绑到一台刚被吊销的设备上(double-admit 形);
-     *  · 绑定行必须当前读且**持锁到提交** —— 两个并发换绑(同 expectedRev)在锁上串行:赢家 rev+1 提交,
-     *    输家的锁读看到新 rev ⇒ 走 `rev_conflict` 携当前行(单赢家,无未定义态)。锁读判等之后,CAS
-     *    UPDATE(`rev = ?` 谓词 + `rev+1` 恒变列)在持锁下不可能 0 行 —— 0 行即驱动/引擎异常,响亮抛,
-     *    不折成业务分支([ref]:未知失败不伪装成正常拒绝)。
+     * O4 显式换绑(2026-08-30 v2 稿 §2;§3.3 转换表 rebind 行)—— **一只事务**:锁目标设备行(在 / 属 owner / 未吊销)→ 读写序律那一读
+     * {@link lockRootAndReadClaim}(用本事务自己的连接先 `FOR UPDATE` 锁根 `session_meta` 行,再新语句锁定读 `task_active`;有认领 ⇒ `active_run`,
+     * 什么都不写 —— 这一读是「换绑不与在飞 run 交错」的**保证**,路由的池级 `getActiveTaskId` 只作早拒)→ 锁定读执行格 → 判官
+     * {@link settledDeviceRebindOutcome}(住客 ∧ 两属主列 ∧ rev;幂等短路先于写)→ CAS(`execution_rev + 1` 恒变列)→ `session_rebound` 审计行,同一事务提交。
+     * 审计写不进去 = 整次换绑失败(fail-closed,[ref])。持锁判过之后 CAS 不可能 0 行 —— 0 行即引擎异常,响亮抛。三形语义 oracle = `InMemoryDeviceStore.rebindDeviceExecution`。
      */
-    rebindSession(input: RebindSessionInput): Promise<RebindSessionResult>;
-    getSessionBinding(rootSessionId: string): Promise<DeviceSessionRow | null>;
-    deleteByRootSession(rootSessionId: string): Promise<number>;
+    rebindDeviceExecution(input: RebindDeviceExecutionInput): Promise<RebindDeviceExecutionResult>;
     appendAudit(input: AppendAuditInput): Promise<void>;
     /** 审计写的**唯一**语句(池级与事务内共用;`SqlExec` 是两者的公共面)。 */
     private insertAuditOn;