@sema-agent/server 7.137.0 → 7.139.0

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;

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

@@ -1,11 +1,12 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { isDupKeyError, isCheckViolationError } from "./sql-errors.js";
-import { DEVICE_AUDIT_EVENTS, assertAcquireShape, assertDeviceIdShape, assertDeviceOwnerShape, assertEnrollTokenHashShape, assertIssueTokenShape, assertNewDeviceShape, assertRebindShape, assertRevokeShape, assertRootSessionIdShape, assertWholeSeconds, parseDeviceAuditEvent, parseDevicePlatformOs, parseDeviceStatus, } from "../device-store.js";
+import { DEVICE_AUDIT_EVENTS, assertAcquireShape, assertDeviceIdShape, assertDeviceOwnerShape, assertEnrollTokenHashShape, assertIssueTokenShape, assertNewDeviceShape, assertPlaceDeviceShape, assertRebindShape, assertRevokeShape, assertWholeSeconds, parseDeviceAuditEvent, parseDevicePlatformOs, parseDeviceStatus, } from "../device-store.js";
+import { WRITABLE, boundDeviceOf, settledDeviceBindOutcome, settledDeviceRebindOutcome } from "../execution-placement.js";
+import { bindDeviceStatement, lockRootAndReadClaim, placeWriterStatement, readPlacementOn, rebindDeviceStatement, rowsOnSqlExec } from "./execution-placement-sql.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn } from "./sql-json-column.js";
 export const DEVICES_TABLE = "device";
 export const DEVICE_ENROLL_TOKENS_TABLE = "device_enroll_token";
-export const DEVICE_SESSIONS_TABLE = "device_session";
 export const DEVICE_AUDIT_TABLE = "device_audit";
 const UQ_DEVICES_PUBKEY = "uq_device_pubkey";
 const AUDIT_EVENT_CHECK = DEVICE_AUDIT_EVENTS.map((e) => `'${e}'`).join(", ");
@@ -56,17 +57,6 @@ export const TIDB_DEVICE_STATEMENTS = [
     consumed_pubkey   VARBINARY(128) NULL,
     rev               BIGINT         NOT NULL DEFAULT 0,
     PRIMARY KEY (token_hash)
-  ) COLLATE utf8mb4_bin`,
-    `CREATE TABLE IF NOT EXISTS ${DEVICE_SESSIONS_TABLE} (
-    -- 键 = 根会话(task-R1-3:后代继承不另绑);一根会话恒一设备(改绑 = 显式动作)。
-    root_session_id VARBINARY(128) NOT NULL,
-    device_id       VARBINARY(64)  NOT NULL,
-    owner_tenant    VARBINARY(190) NOT NULL,
-    owner_subject   VARBINARY(190) NOT NULL,
-    bound_at        DATETIME(3)    NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
-    rev             BIGINT         NOT NULL DEFAULT 0,
-    PRIMARY KEY (root_session_id),
-    KEY idx_device_session_device (device_id)
   ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS ${DEVICE_AUDIT_TABLE} (
     id            BIGINT AUTO_INCREMENT,
@@ -90,7 +80,6 @@ export async function ensureTiDBDeviceSchema(pool) {
 }
 export const DEVICE_INDEXES = [
     { table: `${DEVICES_TABLE}`, name: "idx_device_owner", columns: ["owner_tenant", "owner_subject"] },
-    { table: `${DEVICE_SESSIONS_TABLE}`, name: "idx_device_session_device", columns: ["device_id"] },
     { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_device", columns: ["device_id", "at"] },
     { table: `${DEVICE_AUDIT_TABLE}`, name: "idx_device_audit_event", columns: ["event", "at"] },
 ];
@@ -133,15 +122,6 @@ export async function ensurePgDeviceSchema(q) {
     consumed_pubkey   VARCHAR(128) COLLATE "C",
     rev               BIGINT       NOT NULL DEFAULT 0,
     PRIMARY KEY (token_hash)
-  )`);
-    await q(`CREATE TABLE IF NOT EXISTS ${DEVICE_SESSIONS_TABLE} (
-    root_session_id VARCHAR(128) COLLATE "C" NOT NULL,
-    device_id       VARCHAR(64)  COLLATE "C" NOT NULL,
-    owner_tenant    VARCHAR(190) COLLATE "C" NOT NULL,
-    owner_subject   VARCHAR(190) COLLATE "C" NOT NULL,
-    bound_at        TIMESTAMPTZ(3) NOT NULL DEFAULT now(),
-    rev             BIGINT       NOT NULL DEFAULT 0,
-    PRIMARY KEY (root_session_id)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${DEVICE_AUDIT_TABLE} (
     id            BIGSERIAL    PRIMARY KEY,
@@ -172,8 +152,8 @@ export async function assertDeviceAuditRebindEventSchema(db) {
                 : `ALTER TABLE ${DEVICE_AUDIT_TABLE} DROP CHECK ck_device_audit_event; ALTER TABLE ${DEVICE_AUDIT_TABLE} ADD CONSTRAINT ck_device_audit_event CHECK (event IN (${AUDIT_EVENT_CHECK}));`;
             throw new Error(`${DEVICE_AUDIT_TABLE} still carries a pre-O4 event CHECK that rejects 'session_rebound' — refusing to start. ` +
                 "The rebind verb (POST /v1/devices/sessions/:rootSessionId/rebind) writes this audit event in the same transaction " +
-                "as its CAS, so on this table every rebind would fail at runtime after a healthy-looking boot. This repository ships " +
-                "no ALTER TABLE migrations, and dropping an AUDIT table would destroy security-axis history — run the manual " +
+                "as its CAS, so on this table every rebind would fail at runtime after a healthy-looking boot. Nothing in this build " +
+                "rewrites this table's constraint on its own, and dropping an AUDIT table would destroy security-axis history — run the manual " +
                 `constraint rebuild instead (history preserved, defense-in-depth restored to the current closed set): \`${remedy}\` ` +
                 "The application layer remains the enforcing authority for this closed set (parseDeviceAuditEvent). " +
                 `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
@@ -234,9 +214,6 @@ function tokenCols(dialect) {
         "rev",
     ].join(", ");
 }
-function sessionCols(dialect) {
-    return ["root_session_id", "device_id", "owner_tenant", "owner_subject", ms(dialect, "bound_at", "bound_at_ms"), "rev"].join(", ");
-}
 function auditCols(dialect) {
     return ["id", ms(dialect, "at", "at_ms"), "event", "device_id", "owner_tenant", "owner_subject", jsonColumnText(dialect, "detail")].join(", ");
 }
@@ -287,15 +264,6 @@ function mapTokenRow(r) {
         rev: Number(r.rev),
     };
 }
-function mapSessionRow(r) {
-    return {
-        rootSessionId: bufToStr(r.root_session_id),
-        deviceId: bufToStr(r.device_id),
-        owner: { tenant: bufToStr(r.owner_tenant), subject: bufToStr(r.owner_subject) },
-        boundAtMs: Number(r.bound_at_ms),
-        rev: Number(r.rev),
-    };
-}
 function mapAuditRow(r) {
     const tenant = strOrNull(r.owner_tenant);
     const subject = strOrNull(r.owner_subject);
@@ -528,51 +496,38 @@ export class SqlDeviceStore {
         const res = await this.db.query(this.q(`UPDATE ${DEVICES_TABLE} SET lease_expires_at = NULL, rev = rev + 1 WHERE device_id = ? AND conn_generation = ?`, `UPDATE ${DEVICES_TABLE} SET lease_expires_at = NULL, rev = rev + 1 WHERE device_id = $1 AND conn_generation = $2`), [deviceId, generation]);
         return res.affected === 1;
     }
-    async bindSession(input) {
-        assertRootSessionIdShape(input.rootSessionId);
-        assertDeviceIdShape(input.deviceId);
-        assertDeviceOwnerShape(input.owner);
+    async lockDeviceStatus(conn, deviceId, owner) {
+        const dev = await conn.query(this.q(`SELECT status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT status FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [deviceId, owner.tenant, owner.subject]);
+        return dev.rows[0] ? parseDeviceStatus(bufToStr(dev.rows[0].status)) : undefined;
+    }
+    async placeDeviceExecution(input) {
+        assertPlaceDeviceShape(input);
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const dev = await conn.query(this.q(`SELECT status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT status FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [input.deviceId, input.owner.tenant, input.owner.subject]);
-            if (!dev.rows[0]) {
+            const status = await this.lockDeviceStatus(conn, input.deviceId, input.owner);
+            if (status !== "active") {
                 await conn.rollback();
-                return { outcome: "device_not_found" };
+                return { outcome: status === undefined ? "device_not_found" : "device_revoked" };
             }
-            if (parseDeviceStatus(bufToStr(dev.rows[0].status)) !== "active") {
+            const rowsOn = rowsOnSqlExec(conn);
+            const reading = await readPlacementOn(rowsOn, this.db.dialect, input.root);
+            const settled = settledDeviceBindOutcome(input.root, reading, input.occupant, input.deviceId);
+            if (settled !== WRITABLE) {
                 await conn.rollback();
-                return { outcome: "device_revoked" };
-            }
-            const clock = await conn.query(this.q(`SELECT ${ms("tidb", NOW("tidb"), "bound_at_ms")}`, `SELECT ${ms("pg", NOW("pg"), "bound_at_ms")}`));
-            const boundAtMs = Number(clock.rows[0].bound_at_ms);
-            const ins = await conn.query(this.q(`INSERT IGNORE INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES (?, ?, ?, ?, FROM_UNIXTIME(? / 1000), 0)`, `INSERT INTO ${DEVICE_SESSIONS_TABLE} (root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev) VALUES ($1, $2, $3, $4, to_timestamp($5::double precision / 1000.0), 0) ON CONFLICT (root_session_id) DO NOTHING`), [input.rootSessionId, input.deviceId, input.owner.tenant, input.owner.subject, boundAtMs]);
-            if (ins.affected === 1) {
-                await conn.commit();
-                return { outcome: "bound", row: { rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.owner, boundAtMs, rev: 0 } };
+                return settled;
             }
-            await conn.rollback();
-        }
-        catch (err) {
-            await conn.rollback().catch(() => undefined);
-            throw err;
-        }
-        finally {
-            conn.release();
-        }
-        return await this.observeLostBind(input);
-    }
-    async observeLostBind(input) {
-        const conn = await this.db.connect();
-        try {
-            await conn.begin();
-            const { rows } = await conn.query(this.q(`SELECT ${sessionCols("tidb")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ? FOR UPDATE`, `SELECT ${sessionCols("pg")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1 FOR UPDATE`), [input.rootSessionId]);
+            const now = new Date();
+            const device = { id: input.deviceId, owner: input.owner };
+            const stmt = reading.cell.role === "absent"
+                ? placeWriterStatement(this.db.dialect, input.root, input.occupant, { lane: "device", device }, now)
+                : bindDeviceStatement(this.db.dialect, input.root, input.occupant, device, now);
+            const res = await conn.query(stmt.text, [...stmt.values]);
+            if (res.affected !== 1)
+                throw new Error(`device-store: first bind of session ${input.root} affected ${res.affected} rows under a held row lock — engine anomaly, refusing to guess`);
             await conn.commit();
-            const row = rows[0] ? mapSessionRow(rows[0]) : null;
-            if (!row)
-                throw new Error("device-store: the winning session binding vanished before the losing binder could observe it");
-            const same = row.deviceId === input.deviceId && row.owner.tenant === input.owner.tenant && row.owner.subject === input.owner.subject;
-            return { outcome: same ? "idempotent" : "conflict", row };
+            const placed = { id: input.deviceId, owner: { tenant: input.owner.tenant, subject: input.owner.subject }, rev: 0, placedAt: now.toISOString() };
+            return { outcome: "bound", device: placed };
         }
         catch (err) {
             await conn.rollback().catch(() => undefined);
@@ -582,40 +537,41 @@ export class SqlDeviceStore {
             conn.release();
         }
     }
-    async rebindSession(input) {
+    async rebindDeviceExecution(input) {
         assertRebindShape(input);
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const dev = await conn.query(this.q(`SELECT status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT status FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [input.toDeviceId, input.owner.tenant, input.owner.subject]);
-            if (!dev.rows[0] || parseDeviceStatus(bufToStr(dev.rows[0].status)) !== "active") {
+            if ((await this.lockDeviceStatus(conn, input.targetDeviceId, input.owner)) !== "active") {
                 await conn.rollback();
                 return { outcome: "device_not_found" };
             }
-            const cur = await conn.query(this.q(`SELECT ${sessionCols("tidb")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT ${sessionCols("pg")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1 AND owner_tenant = $2 AND owner_subject = $3 FOR UPDATE`), [input.rootSessionId, input.owner.tenant, input.owner.subject]);
-            if (!cur.rows[0]) {
+            const rowsOn = rowsOnSqlExec(conn);
+            const claim = await lockRootAndReadClaim(rowsOn, this.db.dialect, input.root);
+            if (!claim.rowPresent) {
                 await conn.rollback();
-                return { outcome: "binding_not_found" };
+                return { outcome: "gone" };
             }
-            const row = mapSessionRow(cur.rows[0]);
-            if (row.deviceId === input.toDeviceId && row.rev === input.expectedRev) {
+            if (claim.activeTaskId !== null) {
                 await conn.rollback();
-                return { outcome: "idempotent", row };
+                return { outcome: "active_run", activeTaskId: claim.activeTaskId };
             }
-            if (row.rev !== input.expectedRev) {
+            const reading = await readPlacementOn(rowsOn, this.db.dialect, input.root);
+            const settled = settledDeviceRebindOutcome(reading, input.occupant, input.owner, input.expectedRev, input.targetDeviceId);
+            if (settled !== WRITABLE) {
                 await conn.rollback();
-                return { outcome: "rev_conflict", row };
+                return settled;
             }
-            const cas = await conn.query(this.q(`UPDATE ${DEVICE_SESSIONS_TABLE} SET device_id = ?, bound_at = NOW(3), rev = rev + 1 WHERE root_session_id = ? AND owner_tenant = ? AND owner_subject = ? AND rev = ?`, `UPDATE ${DEVICE_SESSIONS_TABLE} SET device_id = $1, bound_at = now(), rev = rev + 1 WHERE root_session_id = $2 AND owner_tenant = $3 AND owner_subject = $4 AND rev = $5`), [input.toDeviceId, input.rootSessionId, input.owner.tenant, input.owner.subject, input.expectedRev]);
-            if (cas.affected !== 1) {
+            const from = boundDeviceOf(reading.cell).id;
+            const now = new Date();
+            const stmt = rebindDeviceStatement(this.db.dialect, input.root, input.occupant, input.owner, input.expectedRev, input.targetDeviceId, now);
+            const cas = await conn.query(stmt.text, [...stmt.values]);
+            if (cas.affected !== 1)
                 throw new Error(`device-store: rebind CAS affected ${cas.affected} rows under a held row lock — engine anomaly, refusing to guess`);
-            }
-            await this.insertAuditOn(conn, { event: "session_rebound", deviceId: input.toDeviceId, owner: row.owner, detail: { from: row.deviceId, to: input.toDeviceId, rev: row.rev + 1 } });
-            const { rows } = await conn.query(this.q(`SELECT ${sessionCols("tidb")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ?`, `SELECT ${sessionCols("pg")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1`), [input.rootSessionId]);
+            const rev = input.expectedRev + 1;
+            await this.insertAuditOn(conn, { event: "session_rebound", deviceId: input.targetDeviceId, owner: input.owner, detail: { from, to: input.targetDeviceId, rev } });
             await conn.commit();
-            if (!rows[0])
-                throw new Error("device-store: rebound session binding vanished inside its own transaction");
-            return { outcome: "rebound", row: mapSessionRow(rows[0]) };
+            return { outcome: "rebound", from, device: { id: input.targetDeviceId, owner: { tenant: input.owner.tenant, subject: input.owner.subject }, rev, placedAt: now.toISOString() } };
         }
         catch (err) {
             await conn.rollback().catch(() => undefined);
@@ -625,16 +581,6 @@ export class SqlDeviceStore {
             conn.release();
         }
     }
-    async getSessionBinding(rootSessionId) {
-        assertRootSessionIdShape(rootSessionId);
-        const { rows } = await this.db.query(this.q(`SELECT ${sessionCols("tidb")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ?`, `SELECT ${sessionCols("pg")} FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1`), [rootSessionId]);
-        return rows[0] ? mapSessionRow(rows[0]) : null;
-    }
-    async deleteByRootSession(rootSessionId) {
-        assertRootSessionIdShape(rootSessionId);
-        const res = await this.db.query(this.q(`DELETE FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = ?`, `DELETE FROM ${DEVICE_SESSIONS_TABLE} WHERE root_session_id = $1`), [rootSessionId]);
-        return res.affected;
-    }
     async appendAudit(input) {
         await this.insertAuditOn(this.db, input);
     }

package/dist/plugins/execution-placement-sql.d.ts

@@ -0,0 +1,151 @@
+/**
+ * **执行放置的 SQL 唯一模块** —— `session_meta` 上 `execution_*` 七列 + `fork_key` 一列的列定义、住客谓词、行 → 格解码、每一种转换的语句,
+ * 与「写事务内先锁根行再读认领」那一读。规则在 `src/execution-placement.ts` 头注;本模块只说 SQL。
+ *
+ * ## 属主
+ *  · **列定义唯一属主**(两方言):中央 DDL(`tidb-pool.ts` 的 `CREATE TABLE session_meta`、`pg-session-storage.ts` 的 `PG_SESSION_SCHEMA`)内插
+ *    {@link sessionMetaPlacementColumnsDdl}(先例:`SESSION_META_INCARNATION_COLUMN`);起服列册对账(`schema-consistency.ts`)从同一份建表文本解析期望列集。
+ *    存量库的加列只由一次性迁移做,`ensureSchema` 不 ALTER(SCHEMA POLICY)。
+ *  · **语句唯一属主**:会话店(执行席、导入写口)与设备店(首绑 / 换绑)、一次性迁移(搬绑定 / 回填)的事务都借这里的语句,别处零手写。
+ *    语句是方言无关的 `{ text, values }`(调用方用自己的连接跑:SqlDriver 的 `SqlTxConn`、node-pg 的客户端、mysql2 的连接都行)。
+ *
+ * ## 住客谓词(写与 judged 复核的唯一定址)
+ * `session_id = :root AND incarnation = :inc AND owner <=> :owner(PG:IS NOT DISTINCT FROM)AND placement_kind IS NULL` —— core 行期望判官 `sessionRowMatches`
+ * (属主 + 化身;会话行格写原语在锁住的行上判的就是它,`session-row.ts`)的 SQL 拼法(同一化身的属主会变:local M10 认领、identical 重戳、SQL 导入提交点改属主)。
+ * 0 行一律按住客复读分类(判官在 `execution-placement.ts`),永不对现住客重试。
+ *
+ * ## 读写序律(写事务内的认领读)
+ * 改根住客 / 放置的每个写者(换绑 CAS · 导入三写口 · identical 补 mirror · 删除终刀 · 留存删除)在写事务内、用该事务自己的连接先 `FOR UPDATE` 锁根
+ * `session_meta` 行,再以新语句锁定读 `task_active(root)`({@link lockRootAndReadClaim}):有认领 ⇒ 不写。全局锁序:设备行 → 根 meta → `task_*`
+ * (`run-store-sql.ts` 的 `createRun` 同序先锁根行)。认领持有者自己的初始放置写(place / bind)是唯一例外,不读认领、仍按住客谓词。
+ */
+import type { SqlDialect, SqlDriver, SqlExec } from "./sql-driver.js";
+import type { DeviceOwner } from "../device-store.js";
+import { type ExecutionLane } from "../execution-lane-caps.js";
+import { type SessionFace } from "../session-incarnation.js";
+import { type ExecutionPlacementCell, type ExecutionPlacementReading, type ExecutionPlacementSeat } from "../execution-placement.js";
+/** 一条语句:文本 + 按序的参数(`?` / `$n` 已按方言铸好)。 */
+export interface PlacementStatement {
+    readonly text: string;
+    readonly values: readonly unknown[];
+}
+/**
+ * `session_meta` 的八列(执行放置七列 + `fork_key`)—— 两方言各一句,**唯一属主**。宽度:车道词 ≤ 32、设备 id 与 `device` 表同宽 64、
+ * 属主两列与设备店同宽 190、fork 键 255(服务端拼的不透明串)。PG 文本列 `COLLATE "C"`(与同表同形)。全部可空:NULL = absent / 非键控 fork。
+ */
+export declare const SESSION_META_PLACEMENT_COLUMNS: readonly [{
+    readonly name: "execution_role";
+    readonly tidb: "execution_role VARCHAR(16) NULL";
+    readonly pg: "execution_role VARCHAR(16) COLLATE \"C\"";
+}, {
+    readonly name: "execution_lane";
+    readonly tidb: "execution_lane VARCHAR(32) NULL";
+    readonly pg: "execution_lane VARCHAR(32) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_id";
+    readonly tidb: "execution_device_id VARCHAR(64) NULL";
+    readonly pg: "execution_device_id VARCHAR(64) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_owner_tenant";
+    readonly tidb: "execution_device_owner_tenant VARCHAR(190) NULL";
+    readonly pg: "execution_device_owner_tenant VARCHAR(190) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_owner_subject";
+    readonly tidb: "execution_device_owner_subject VARCHAR(190) NULL";
+    readonly pg: "execution_device_owner_subject VARCHAR(190) COLLATE \"C\"";
+}, {
+    readonly name: "execution_placed_at";
+    readonly tidb: "execution_placed_at DATETIME(3) NULL";
+    readonly pg: "execution_placed_at TIMESTAMPTZ(3)";
+}, {
+    readonly name: "execution_rev";
+    readonly tidb: "execution_rev BIGINT NULL";
+    readonly pg: "execution_rev BIGINT";
+}, {
+    readonly name: "fork_key";
+    readonly tidb: "fork_key VARCHAR(255) NULL";
+    readonly pg: "fork_key VARCHAR(255) COLLATE \"C\"";
+}];
+/** 中央 DDL 内插的那一段(列与列之间逗号分隔,不带首尾逗号)。 */
+export declare function sessionMetaPlacementColumnsDdl(dialect: SqlDialect): string;
+/** 导入提交点同句落 mirror 的 SET 片段与守卫谓词(会话店的提交点 UPDATE 内插这两段:`SET …, ${MIRROR_ON_COMMIT_SET} WHERE session_id = ? AND ${MIRROR_ON_COMMIT_GUARD}`)。 */
+export declare const MIRROR_ON_COMMIT_SET = "execution_role = 'mirror'";
+export declare const MIRROR_ON_COMMIT_GUARD = "(execution_role IS NULL OR execution_role <> 'writer')";
+/** 导入新建 / 换装重插的那一行在执行与 fork 两格上的值:`fork_key` = 沿用的键(或 NULL)、`execution_role` = mirror(列名与值同出一处)。 */
+export declare function importedRowCells(forkKey: string | null): {
+    readonly columns: string;
+    readonly values: readonly unknown[];
+};
+/** 读一行放置要的列(住客两列 + 委派判别位 + 执行七列;行 → 读数的唯一解码 {@link placementReadingFromRow} 吃的就是这一组)。导入写口的事务内锁读内插它。 */
+export declare const SESSION_META_PLACEMENT_READ_COLUMNS = "owner, incarnation, placement_kind, execution_role, execution_lane, execution_device_id, execution_device_owner_tenant, execution_device_owner_subject, execution_placed_at, execution_rev";
+/** 按根读一行(`lock` ⇒ `FOR UPDATE`:写事务内的当前读;非事务读不加锁)。 */
+export declare function readPlacementRowStatement(dialect: SqlDialect, root: string, opts: {
+    readonly lock: boolean;
+}): PlacementStatement;
+/**
+ * place:absent → writer(L[, D]),`execution_rev = 0`。非 device 车道由会话店的执行席用(`device` 缺);device 车道的首绑由设备店在锁住设备行的
+ * 同一事务里用(`device` 在场)。时刻用调用方的钟(与 `updated_at` 同一只)。
+ */
+export declare function placeWriterStatement(dialect: SqlDialect, root: string, occupant: SessionFace, cell: {
+    readonly lane: ExecutionLane;
+    readonly device?: {
+        readonly id: string;
+        readonly owner: DeviceOwner;
+    };
+}, now: Date): PlacementStatement;
+/** bind:writer(device, ∅) → writer(device, D)(fresh 首绑撞上迁移回填的格),`execution_rev = 0`。 */
+export declare function bindDeviceStatement(dialect: SqlDialect, root: string, occupant: SessionFace, device: {
+    readonly id: string;
+    readonly owner: DeviceOwner;
+}, now: Date): PlacementStatement;
+/** rebind:writer(device, D) → writer(device, D'),按住客 ∧ 两属主列 ∧ rev 定址,`execution_rev + 1`(恒变列)。属主两列不动(换绑只在同一属主的设备之间)。 */
+export declare function rebindDeviceStatement(dialect: SqlDialect, root: string, occupant: SessionFace, owner: DeviceOwner, expectedRev: number, targetDeviceId: string, now: Date): PlacementStatement;
+/** identical 臂补 mirror:absent / mirror → mirror,WHERE 住客谓词 ∧ 不是 writer。 */
+export declare function markMirrorStatement(dialect: SqlDialect, root: string, occupant: SessionFace): PlacementStatement;
+/** 回填(一次性迁移):无执行格、非委派分区、有 run 行的会话行 ⇒ writer(表唯一项)。幂等(第二次跑零行)。 */
+export declare function backfillWriterStatement(dialect: SqlDialect, lane: ExecutionLane, now: Date): PlacementStatement;
+/**
+ * 搬绑定(一次性迁移):按 `sourceTable`(退役改名后的绑定表,列 = `root_session_id, device_id, owner_tenant, owner_subject, bound_at, rev`)整行覆盖
+ * 根会话行的 device 位(`rev` 原值、`bound_at → execution_placed_at`)。只碰非委派分区行。MySQL 协议那张表的列是 VARBINARY ⇒ 转成字符串再比 / 再写。
+ * `sourceTable` 是调用方的常量表名(不是用户输入)。
+ */
+export declare function migrateDeviceBindingsStatement(dialect: SqlDialect, sourceTable: string): PlacementStatement;
+/** 搬绑定的孤儿计数(绑定行指向的根会话行不在,或是委派分区行 ⇒ 丢弃):迁移收据里点名的那个数。 */
+export declare function countOrphanBindingsStatement(dialect: SqlDialect, sourceTable: string): PlacementStatement;
+/** 一行放置读不通(角色 / 车道不在闭集,或列的组合不是四态之一)—— 响亮拒,不读作 absent(那等于把一行坏数据当成「还没放」放行给首交)。 */
+export declare class ExecutionPlacementRowError extends Error {
+    readonly sessionId: string;
+    readonly code = "execution_placement.row_unreadable";
+    constructor(sessionId: string, detail: string);
+}
+/** 行 → 格(三态;`forking` 只 local)。列的组合必须是四态之一,否则 {@link ExecutionPlacementRowError}。 */
+export declare function placementCellFromRow(root: string, row: Readonly<Record<string, unknown>>): Exclude<ExecutionPlacementCell, {
+    role: "forking";
+}>;
+/** 一行 → 一次读数(住客 + 格)。行不在 / 委派分区行 ⇒ `undefined`;空化身 ⇒ 响亮拒(活住客的投影 `sessionFaceFromRow`)。 */
+export declare function placementReadingFromRow(root: string, row: Readonly<Record<string, unknown>> | undefined): ExecutionPlacementReading | undefined;
+/** 一条语句在调用方事务连接上的执行口(只要行):`SqlTxConn` / node-pg 客户端 / mysql2 连接各包一行即得。 */
+export type PlacementRowsOn = (text: string, values: readonly unknown[]) => Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+/** SqlDriver 连接的执行口。 */
+export declare function rowsOnSqlExec(exec: SqlExec): PlacementRowsOn;
+/** 锁根行之后读认领的读数:`rowPresent: false` ⇒ 根行不在(认领读不做,`activeTaskId` 恒 null)。 */
+export interface RootClaimReading {
+    readonly rowPresent: boolean;
+    readonly activeTaskId: string | null;
+}
+/**
+ * 读写序律那一读(头注):**同一连接**上先 `SELECT … FROM session_meta WHERE session_id = ? FOR UPDATE` 锁根行,再以新语句
+ * `SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE` 锁定读认领(PG 读已提交下取新快照、TiDB 悲观事务是当前读)。
+ * 只在写事务内调;池级 `getActiveTaskId` 不是它(另一只连接,不在锁序里)。根行不在 ⇒ 不读认领。
+ */
+export declare function lockRootAndReadClaim(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<RootClaimReading>;
+/** 写事务内按根的当前读(`FOR UPDATE`)→ 读数。 */
+export declare function readPlacementOn(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<ExecutionPlacementReading | undefined>;
+/**
+ * SQL 会话店的执行席(两孪生同一只实现:语句与判官都在这里与 `execution-placement.ts`,方言只在语句文本里)。`db` = 店自己的池包成的 SqlDriver。
+ *  · `read` —— 一次池读;
+ *  · `place` —— 一句自动提交的 UPDATE(认领持有者自己的初始放置写:不读认领、按住客谓词);0 行 ⇒ 按根复读、交判官分类;
+ *  · `markMirror` —— 一只事务:锁根行读认领 → 锁定读这一行 → 判官 → 有认领 ⇒ `active` → UPDATE(持锁下必中一行)。
+ */
+export declare function createSqlExecutionPlacementSeat(db: Pick<SqlDriver, "dialect" | "query" | "connect">): ExecutionPlacementSeat;
+//# sourceMappingURL=execution-placement-sql.d.ts.map