@sema-agent/server 7.138.0 → 7.140.0

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,
@@ -160,7 +140,7 @@ export async function assertDeviceAuditRebindEventSchema(db) {
     try {
         await conn.begin();
         try {
-            await conn.query(db.dialect === "tidb"
+            await conn.query(db.dialect === "mysql"
                 ? `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (NOW(3), ?, NULL, NULL, NULL, NULL)`
                 : `INSERT INTO ${DEVICE_AUDIT_TABLE} (at, event, device_id, owner_tenant, owner_subject, detail) VALUES (now(), $1, NULL, NULL, NULL, NULL)`, ["session_rebound"]);
         }
@@ -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)}`);
@@ -188,9 +168,9 @@ export async function assertDeviceAuditRebindEventSchema(db) {
         conn.release();
     }
 }
-const ms = (dialect, col, alias) => dialect === "tidb" ? `ROUND(UNIX_TIMESTAMP(${col}) * 1000) AS ${alias}` : `(EXTRACT(EPOCH FROM ${col}) * 1000)::bigint AS ${alias}`;
-const NOW = (dialect) => (dialect === "tidb" ? "NOW(3)" : "now()");
-const nowPlusSeconds = (dialect, placeholder) => dialect === "tidb" ? `NOW(3) + INTERVAL ${placeholder} SECOND` : `now() + (${placeholder}::double precision * INTERVAL '1 second')`;
+const ms = (dialect, col, alias) => dialect === "mysql" ? `ROUND(UNIX_TIMESTAMP(${col}) * 1000) AS ${alias}` : `(EXTRACT(EPOCH FROM ${col}) * 1000)::bigint AS ${alias}`;
+const NOW = (dialect) => (dialect === "mysql" ? "NOW(3)" : "now()");
+const nowPlusSeconds = (dialect, placeholder) => dialect === "mysql" ? `NOW(3) + INTERVAL ${placeholder} SECOND` : `now() + (${placeholder}::double precision * INTERVAL '1 second')`;
 function deviceCols(dialect) {
     return [
         "device_id",
@@ -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);
@@ -318,10 +286,10 @@ function readAuditDetail(raw, id) {
     }
 }
 function ph(dialect, n) {
-    return dialect === "tidb" ? "?" : `$${n}`;
+    return dialect === "mysql" ? "?" : `$${n}`;
 }
 function dupKeyName(dialect, err) {
-    if (dialect === "tidb") {
+    if (dialect === "mysql") {
         const msg = String(err?.sqlMessage ?? err?.message ?? "");
         if (new RegExp(UQ_DEVICES_PUBKEY, "i").test(msg))
             return "pubkey";
@@ -341,8 +309,8 @@ export class SqlDeviceStore {
     constructor(db) {
         this.db = db;
     }
-    q(tidb, pg) {
-        return this.db.dialect === "tidb" ? tidb : pg;
+    q(mysql, pg) {
+        return this.db.dialect === "mysql" ? mysql : pg;
     }
     json(value) {
         return dialectJsonEncoder(this.db.dialect)(value);
@@ -351,7 +319,7 @@ export class SqlDeviceStore {
         assertIssueTokenShape(input);
         try {
             await this.db.query(this.q(`INSERT INTO ${DEVICE_ENROLL_TOKENS_TABLE} (token_hash, target_tenant, target_subject, created_by, created_at, expires_at, consumed_at, consumed_device_id, consumed_pubkey, rev)
-           VALUES (?, ?, ?, ?, NOW(3), ${nowPlusSeconds("tidb", "?")}, NULL, NULL, NULL, 0)`, `INSERT INTO ${DEVICE_ENROLL_TOKENS_TABLE} (token_hash, target_tenant, target_subject, created_by, created_at, expires_at, consumed_at, consumed_device_id, consumed_pubkey, rev)
+           VALUES (?, ?, ?, ?, NOW(3), ${nowPlusSeconds("mysql", "?")}, NULL, NULL, NULL, 0)`, `INSERT INTO ${DEVICE_ENROLL_TOKENS_TABLE} (token_hash, target_tenant, target_subject, created_by, created_at, expires_at, consumed_at, consumed_device_id, consumed_pubkey, rev)
            VALUES ($1, $2, $3, $4, now(), ${nowPlusSeconds("pg", "$5")}, NULL, NULL, NULL, 0)`), [input.tokenHash, input.target.tenant, input.target.subject, input.createdBy, input.ttlSeconds]);
         }
         catch (err) {
@@ -366,7 +334,7 @@ export class SqlDeviceStore {
     }
     async getEnrollToken(tokenHash) {
         assertEnrollTokenHashShape(tokenHash);
-        const { rows } = await this.db.query(this.q(`SELECT ${tokenCols("tidb")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = ?`, `SELECT ${tokenCols("pg")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = $1`), [tokenHash]);
+        const { rows } = await this.db.query(this.q(`SELECT ${tokenCols("mysql")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = ?`, `SELECT ${tokenCols("pg")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = $1`), [tokenHash]);
         return rows[0] ? mapTokenRow(rows[0]) : null;
     }
     async consumeEnrollToken(input) {
@@ -414,7 +382,7 @@ export class SqlDeviceStore {
                 return { outcome: "enrolled", device };
             }
             await conn.rollback();
-            const { rows } = await conn.query(this.q(`SELECT ${tokenCols("tidb")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = ?`, `SELECT ${tokenCols("pg")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = $1`), [input.tokenHash]);
+            const { rows } = await conn.query(this.q(`SELECT ${tokenCols("mysql")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = ?`, `SELECT ${tokenCols("pg")} FROM ${DEVICE_ENROLL_TOKENS_TABLE} WHERE token_hash = $1`), [input.tokenHash]);
             const token = rows[0] ? mapTokenRow(rows[0]) : null;
             if (!token)
                 return { outcome: "unknown_token" };
@@ -437,28 +405,28 @@ export class SqlDeviceStore {
         }
     }
     async readDeviceOn(conn, deviceId) {
-        const { rows } = await conn.query(this.q(`SELECT ${deviceCols("tidb")} FROM ${DEVICES_TABLE} WHERE device_id = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1`), [deviceId]);
+        const { rows } = await conn.query(this.q(`SELECT ${deviceCols("mysql")} FROM ${DEVICES_TABLE} WHERE device_id = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1`), [deviceId]);
         return rows[0] ? mapDeviceRow(rows[0]) : null;
     }
     async readDeviceForAdmission(deviceId, owner) {
         assertDeviceIdShape(deviceId);
         assertDeviceOwnerShape(owner);
-        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("tidb")}, ${onlineCol("tidb")} FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ?`, `SELECT ${deviceCols("pg")}, ${onlineCol("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3`), [deviceId, owner.tenant, owner.subject]);
+        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("mysql")}, ${onlineCol("mysql")} FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ?`, `SELECT ${deviceCols("pg")}, ${onlineCol("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3`), [deviceId, owner.tenant, owner.subject]);
         const r = rows[0];
         return r ? { row: mapDeviceRow(r), online: Number(r.online) === 1 } : null;
     }
     async getDeviceUnscoped(deviceId) {
         assertDeviceIdShape(deviceId);
-        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("tidb")} FROM ${DEVICES_TABLE} WHERE device_id = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1`), [deviceId]);
+        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("mysql")} FROM ${DEVICES_TABLE} WHERE device_id = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1`), [deviceId]);
         return rows[0] ? mapDeviceRow(rows[0]) : null;
     }
     async listDevicesByOwner(owner) {
         assertDeviceOwnerShape(owner);
-        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("tidb")} FROM ${DEVICES_TABLE} WHERE owner_tenant = ? AND owner_subject = ? ORDER BY device_id ASC`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE owner_tenant = $1 AND owner_subject = $2 ORDER BY device_id ASC`), [owner.tenant, owner.subject]);
+        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("mysql")} FROM ${DEVICES_TABLE} WHERE owner_tenant = ? AND owner_subject = ? ORDER BY device_id ASC`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE owner_tenant = $1 AND owner_subject = $2 ORDER BY device_id ASC`), [owner.tenant, owner.subject]);
         return rows.map(mapDeviceRow);
     }
     async listDevicesUnscoped() {
-        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("tidb")} FROM ${DEVICES_TABLE} ORDER BY device_id ASC`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} ORDER BY device_id ASC`));
+        const { rows } = await this.db.query(this.q(`SELECT ${deviceCols("mysql")} FROM ${DEVICES_TABLE} ORDER BY device_id ASC`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} ORDER BY device_id ASC`));
         return rows.map(mapDeviceRow);
     }
     async revokeDevice(input) {
@@ -478,7 +446,7 @@ export class SqlDeviceStore {
                 return { outcome: "revoked", row };
             }
             await conn.rollback();
-            const { rows } = await conn.query(this.q(`SELECT ${deviceCols("tidb")} FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3`), [input.deviceId, input.owner.tenant, input.owner.subject]);
+            const { rows } = await conn.query(this.q(`SELECT ${deviceCols("mysql")} FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ?`, `SELECT ${deviceCols("pg")} FROM ${DEVICES_TABLE} WHERE device_id = $1 AND owner_tenant = $2 AND owner_subject = $3`), [input.deviceId, input.owner.tenant, input.owner.subject]);
             if (!rows[0])
                 return { outcome: "not_found" };
             return { outcome: "already_revoked", row: mapDeviceRow(rows[0]) };
@@ -496,7 +464,7 @@ export class SqlDeviceStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const cas = await conn.query(this.q(`UPDATE ${DEVICES_TABLE} SET conn_generation = conn_generation + 1, conn_epoch = ?, replica_id = ?, lease_expires_at = ${nowPlusSeconds("tidb", "?")}, connected_at = NOW(3), last_seen_at = NOW(3), rev = rev + 1
+            const cas = await conn.query(this.q(`UPDATE ${DEVICES_TABLE} SET conn_generation = conn_generation + 1, conn_epoch = ?, replica_id = ?, lease_expires_at = ${nowPlusSeconds("mysql", "?")}, connected_at = NOW(3), last_seen_at = NOW(3), rev = rev + 1
             WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? AND status = 'active' AND (lease_expires_at IS NULL OR lease_expires_at <= NOW(3))`, `UPDATE ${DEVICES_TABLE} SET conn_generation = conn_generation + 1, conn_epoch = $1, replica_id = $2, lease_expires_at = ${nowPlusSeconds("pg", "$3")}, connected_at = now(), last_seen_at = now(), rev = rev + 1
             WHERE device_id = $4 AND owner_tenant = $5 AND owner_subject = $6 AND status = 'active' AND (lease_expires_at IS NULL OR lease_expires_at <= now())`), [input.connEpoch, input.replicaId, input.leaseSeconds, input.deviceId, input.owner.tenant, input.owner.subject]);
             const { rows } = await conn.query(this.q(`SELECT conn_generation, status FROM ${DEVICES_TABLE} WHERE device_id = ? AND owner_tenant = ? AND owner_subject = ? FOR UPDATE`, `SELECT conn_generation, 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]);
@@ -520,7 +488,7 @@ export class SqlDeviceStore {
     async heartbeatConnection(input) {
         assertDeviceIdShape(input.deviceId);
         assertWholeSeconds("leaseSeconds", input.leaseSeconds);
-        const res = await this.db.query(this.q(`UPDATE ${DEVICES_TABLE} SET last_seen_at = NOW(3), lease_expires_at = ${nowPlusSeconds("tidb", "?")}, rev = rev + 1 WHERE device_id = ? AND conn_generation = ? AND status = 'active'`, `UPDATE ${DEVICES_TABLE} SET last_seen_at = now(), lease_expires_at = ${nowPlusSeconds("pg", "$1")}, rev = rev + 1 WHERE device_id = $2 AND conn_generation = $3 AND status = 'active'`), [input.leaseSeconds, input.deviceId, input.generation]);
+        const res = await this.db.query(this.q(`UPDATE ${DEVICES_TABLE} SET last_seen_at = NOW(3), lease_expires_at = ${nowPlusSeconds("mysql", "?")}, rev = rev + 1 WHERE device_id = ? AND conn_generation = ? AND status = 'active'`, `UPDATE ${DEVICES_TABLE} SET last_seen_at = now(), lease_expires_at = ${nowPlusSeconds("pg", "$1")}, rev = rev + 1 WHERE device_id = $2 AND conn_generation = $3 AND status = 'active'`), [input.leaseSeconds, input.deviceId, input.generation]);
         return res.affected === 1;
     }
     async releaseConnection(deviceId, generation) {
@@ -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/ensure-index.d.ts

@@ -1,5 +1,4 @@
-/** 本原语认得的两种方言(闭集;新方言进来是编译期的事,不是运行期的 `default` 臂)。 */
-export type SqlDialect = "mysql" | "pg";
+import type { SqlDialect } from "./sql-driver.js";
 /**
  * 一条索引的**声明**(纯数据)。两方言共用同一份声明 —— 这就是"一处属主"的兑现物:
  * per-store 文件各导出自己那份 `readonly IndexSpec[]`,PG 侧由该 store 的 `ensurePg*Schema` 应用,

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 mysql: "execution_role VARCHAR(16) NULL";
+    readonly pg: "execution_role VARCHAR(16) COLLATE \"C\"";
+}, {
+    readonly name: "execution_lane";
+    readonly mysql: "execution_lane VARCHAR(32) NULL";
+    readonly pg: "execution_lane VARCHAR(32) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_id";
+    readonly mysql: "execution_device_id VARCHAR(64) NULL";
+    readonly pg: "execution_device_id VARCHAR(64) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_owner_tenant";
+    readonly mysql: "execution_device_owner_tenant VARCHAR(190) NULL";
+    readonly pg: "execution_device_owner_tenant VARCHAR(190) COLLATE \"C\"";
+}, {
+    readonly name: "execution_device_owner_subject";
+    readonly mysql: "execution_device_owner_subject VARCHAR(190) NULL";
+    readonly pg: "execution_device_owner_subject VARCHAR(190) COLLATE \"C\"";
+}, {
+    readonly name: "execution_placed_at";
+    readonly mysql: "execution_placed_at DATETIME(3) NULL";
+    readonly pg: "execution_placed_at TIMESTAMPTZ(3)";
+}, {
+    readonly name: "execution_rev";
+    readonly mysql: "execution_rev BIGINT NULL";
+    readonly pg: "execution_rev BIGINT";
+}, {
+    readonly name: "fork_key";
+    readonly mysql: "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