@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/ensure-index.js

@@ -1,5 +1,7 @@
 import { recordFailOpen } from "../observability/fail-open.js";
 import { readLiveColumns } from "./schema-live-columns.js";
+import { isDupKeyErrorOfWrappedQuery } from "./sql-errors.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 function rowsOf(res) {
     if (Array.isArray(res)) {
         const first = res[0];
@@ -19,11 +21,120 @@ function lacksConcurrentlySupport(err) {
         return true;
     return typeof code !== "string";
 }
-async function pgIndexValid(q, name) {
-    const rows = rowsOf(await q(`SELECT i.indisvalid FROM pg_index i WHERE i.indexrelid = to_regclass(${quoteLiteral(name)})`));
+const EXPRESSION_PART = "<expression>";
+async function pgIndexLive(q, spec) {
+    const rows = rowsOf(await q("SELECT i.indisvalid AS indisvalid, i.indisunique AS indisunique, " +
+        "(i.indpred IS NULL AND i.indexprs IS NULL) AS whole, " +
+        "(SELECT c.relname::text FROM pg_class c WHERE c.oid = i.indrelid) AS tbl, " +
+        "(SELECT n.nspname::text FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = i.indrelid) AS nsp, " +
+        "COALESCE((SELECT string_agg(a.attname::text, ',' ORDER BY a.attname::text) FROM generate_series(0, i.indnkeyatts - 1) AS k(n) " +
+        "JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = i.indkey[k.n]), '') AS cols, " +
+        "EXISTS (SELECT 1 FROM pg_constraint k WHERE k.conindid = i.indexrelid AND k.contype = 'u') AS backs_constraint " +
+        "FROM pg_index i WHERE i.indexrelid = to_regclass(quote_ident((SELECT n.nspname FROM pg_class t JOIN pg_namespace n ON n.oid = t.relnamespace " +
+        `WHERE t.oid = to_regclass(${quoteLiteral(quoteId("pg", spec.table))}))) || '.' || quote_ident(${quoteLiteral(spec.name)}))`));
     if (rows.length === 0)
         return undefined;
-    return rows[0].indisvalid !== false;
+    const row = rows[0];
+    const schema = typeof row.nsp === "string" ? row.nsp : undefined;
+    const shape = typeof row.cols === "string" && typeof row.tbl === "string" && typeof row.indisunique === "boolean"
+        ? {
+            table: row.tbl,
+            schema,
+            unique: row.indisunique,
+            columns: row.cols === "" ? [] : row.cols.split(","),
+            whole: row.whole !== false,
+            constraint: row.backs_constraint === true,
+        }
+        : undefined;
+    return { valid: row.indisvalid !== false, schema, shape };
+}
+async function mysqlIndexRows(q, spec) {
+    const rows = rowsOf(await q(`SHOW INDEX FROM ${quoteId("mysql", spec.table)} WHERE Key_name = ${quoteLiteral(spec.name)}`));
+    return rows.map((r) => Object.fromEntries(Object.entries(r).map(([k, v]) => [k.toLowerCase(), v])));
+}
+function mysqlShapeOf(spec, rows) {
+    if (!rows.every((r) => "column_name" in r && "non_unique" in r))
+        return undefined;
+    const keyParts = [...rows].sort((a, b) => Number(a.seq_in_index) - Number(b.seq_in_index));
+    return {
+        table: spec.table,
+        schema: undefined,
+        unique: keyParts.every((r) => Number(r.non_unique) === 0),
+        columns: keyParts.map((r) => (isExpressionPart(r) ? EXPRESSION_PART : r.column_name)),
+        whole: keyParts.every((r) => r.sub_part === null || r.sub_part === undefined),
+        constraint: false,
+    };
+}
+const isExpressionPart = (r) => (typeof r.expression === "string" && r.expression !== "") || typeof r.column_name !== "string";
+const columnSet = (dialect, cols) => [...new Set(dialect === "mysql" ? cols.map((c) => c.toLowerCase()) : cols)].sort();
+function shapeProblem(dialect, spec, live) {
+    const problems = [];
+    if (live.table !== spec.table)
+        problems.push(`it is on table ${live.table}`);
+    if (!live.unique)
+        problems.push("it is not UNIQUE");
+    if (columnSet(dialect, live.columns).join(",") !== columnSet(dialect, spec.columns).join(",")) {
+        problems.push(`it covers (${live.columns.length === 0 ? "no plain key column" : live.columns.join(", ")})`);
+    }
+    if (!live.whole)
+        problems.push(dialect === "pg" ? "it is a partial or expression index" : "it is a prefix or expression index");
+    return problems.length === 0 ? undefined : problems.join("; ");
+}
+export class UniqueIndexRefusalError extends StoreBootRefusalError {
+    kind;
+    spec;
+    constructor(kind, spec, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.spec = spec;
+        this.name = "UniqueIndexRefusalError";
+    }
+}
+const declaredShape = (spec) => `UNIQUE (${spec.columns.join(", ")})`;
+function shapeRefusal(dialect, spec, live, problem) {
+    const name = quoteId(dialect, spec.name);
+    const where = live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`;
+    const drop = dialect === "mysql"
+        ? `ALTER TABLE ${quoteId("mysql", spec.table)} DROP INDEX ${name};`
+        : live.constraint
+            ? `ALTER TABLE ${where}${quoteId("pg", live.table)} DROP CONSTRAINT ${name};`
+            : `DROP INDEX CONCURRENTLY IF EXISTS ${where}${name};`;
+    return new UniqueIndexRefusalError("shape", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} is not the shape this build declares (${declaredShape(spec)}): ${problem} — refusing to start. ` +
+        "The name is taken, so the index is not rebuilt, and this build relies on it to reject duplicate rows. " +
+        `Way out: stop writers to ${spec.table}, run ${drop} and start again — the next start builds the index with the declared shape ` +
+        "(if rows already break it, that start refuses and names the duplicates). Until it is rebuilt nothing enforces the uniqueness.");
+}
+function duplicatesRefusal(dialect, spec, cause) {
+    const cols = columnList(dialect, spec);
+    const notNull = spec.columns.map((c) => `${quoteId(dialect, c)} IS NOT NULL`).join(" AND ");
+    const leftover = dialect === "pg" ? " The failed build leaves an INVALID index of that name; the next start drops and rebuilds it by itself." : "";
+    return new UniqueIndexRefusalError("duplicates", spec, `ensureIndex: unique index ${spec.name} on table ${spec.table} cannot be built — ${spec.table} already holds rows that share (${spec.columns.join(", ")}) — refusing to start, ` +
+        "because this build relies on this index to reject duplicate rows. " +
+        `Way out: find them with SELECT ${cols}, COUNT(*) FROM ${quoteId(dialect, spec.table)} WHERE ${notNull} GROUP BY ${cols} HAVING COUNT(*) > 1 ` +
+        "(rows with a NULL in any of these columns never conflict, so they are left out), remove or merge the extra rows — this build cannot choose which row survives — and start again; " +
+        `the next start builds the index.${leftover}`, { cause });
+}
+function isDuplicateKeyFailure(dialect, err) {
+    if (!isDupKeyErrorOfWrappedQuery(dialect, err))
+        return false;
+    switch (dialect) {
+        case "pg":
+            return Reflect.get(err, "constraint") !== "pg_class_relname_nsp_index";
+        case "mysql":
+            return true;
+        default: {
+            const _never = dialect;
+            throw new Error(`ensureIndex: 未知方言 ${String(_never)}`);
+        }
+    }
+}
+const failureOfBuild = (dialect, spec, err) => spec.unique === true && isDuplicateKeyFailure(dialect, err) ? duplicatesRefusal(dialect, spec, err) : err;
+function assertUniqueShape(dialect, spec, live) {
+    if (live === undefined)
+        return;
+    const problem = shapeProblem(dialect, spec, live);
+    if (problem !== undefined)
+        throw shapeRefusal(dialect, spec, live, problem);
 }
 const refusal = (spec, unique, what) => `ensureIndex: PostgreSQL 索引 ${spec.name}(表 ${spec.table})${what} —— 拒绝带病启动。` +
     "(一个 INVALID 索引会让此后每一次 CREATE INDEX … IF NOT EXISTS 静默跳过它,而规划器永不使用它。)" +
@@ -35,6 +146,8 @@ export async function ensureIndex(q, dialect, spec) {
         await applyIndex(q, dialect, spec);
     }
     catch (err) {
+        if (err instanceof UniqueIndexRefusalError)
+            throw err;
         let live;
         try {
             live = await readLiveColumns(async (sql) => rowsOf(await q(sql)), dialect);
@@ -54,40 +167,60 @@ function indexColumnMissing(live, spec) {
 async function applyIndex(q, dialect, spec) {
     switch (dialect) {
         case "mysql": {
-            const present = rowsOf(await q("SELECT 1 AS present FROM information_schema.statistics WHERE table_schema = DATABASE() " +
-                `AND table_name = ${quoteLiteral(spec.table)} AND index_name = ${quoteLiteral(spec.name)} LIMIT 1`));
-            if (present.length > 0)
+            const present = await mysqlIndexRows(q, spec);
+            if (present.length > 0) {
+                if (spec.unique === true)
+                    assertUniqueShape("mysql", spec, mysqlShapeOf(spec, present));
                 return;
-            await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
-                `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            try {
+                await q(`ALTER TABLE ${quoteId("mysql", spec.table)} ADD ${spec.unique ? "UNIQUE " : ""}INDEX ` +
+                    `${quoteId("mysql", spec.name)} (${columnList("mysql", spec)})`);
+            }
+            catch (err) {
+                throw failureOfBuild("mysql", spec, err);
+            }
             return;
         }
         case "pg": {
             const unique = spec.unique ? "UNIQUE " : "";
             const name = quoteId("pg", spec.name);
             const tail = `${unique}INDEX CONCURRENTLY IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`;
+            const build = async (sql) => {
+                try {
+                    await q(sql);
+                }
+                catch (err) {
+                    throw failureOfBuild("pg", spec, err);
+                }
+            };
             try {
-                await q(`CREATE ${tail}`);
+                await build(`CREATE ${tail}`);
             }
             catch (err) {
-                if (!lacksConcurrentlySupport(err))
+                if (err instanceof UniqueIndexRefusalError || !lacksConcurrentlySupport(err))
                     throw err;
                 recordFailOpen("server.ensure-index.concurrently-unsupported", `${spec.table}.${spec.name}`);
-                await q(`CREATE ${unique}INDEX IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`);
+                await build(`CREATE ${unique}INDEX IF NOT EXISTS ${name} ON ${quoteId("pg", spec.table)} (${columnList("pg", spec)})`);
                 return;
             }
-            const valid = await pgIndexValid(q, spec.name);
-            if (valid !== false)
+            let live = await pgIndexLive(q, spec);
+            if (live === undefined)
                 return;
-            await q(`DROP INDEX CONCURRENTLY IF EXISTS ${name}`);
-            try {
-                await q(`CREATE ${tail}`);
-            }
-            catch (err) {
-                throw new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+            if (!live.valid) {
+                await q(`DROP INDEX CONCURRENTLY IF EXISTS ${live.schema === undefined ? "" : `${quoteId("pg", live.schema)}.`}${name}`);
+                try {
+                    await build(`CREATE ${tail}`);
+                }
+                catch (err) {
+                    throw err instanceof UniqueIndexRefusalError ? err : new Error(refusal(spec, unique, "重建时失败"), { cause: err });
+                }
+                live = await pgIndexLive(q, spec);
+                if (live?.valid === false)
+                    throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
             }
-            if ((await pgIndexValid(q, spec.name)) === false)
-                throw new Error(refusal(spec, unique, "重建后仍是 INVALID"));
+            if (spec.unique === true)
+                assertUniqueShape("pg", spec, live?.shape);
             return;
         }
         default: {

package/dist/plugins/ensure-schema-lock-policy.d.ts

@@ -1,18 +1,3 @@
-/**
- * 两方言启动锁(`ensureSchema` / `oneTimeMigrations` 的 MySQL `GET_LOCK(?,0)` 与 PG `pg_try_advisory_lock`)的
- * **轮询策略唯一属主**(7.83.0 修复验证 车HC HC-1/HC-2 后收口:此前两只孪生各抄一份循环,一份改了「永不放弃」
- * 另一份还是「40 次放弃后无锁跑」,而 [ref] 之后无锁跑的那条腿发的是不带 `IF NOT EXISTS` 的 `ADD INDEX`,两副本
- * 双发 ⇒ 输的那只拒启)。方言只提供「试一次」的探针,循环、抖动、退避、进展 warn、坏连接上抛全在这里。
- *
- * 三条律:
- *  · **按进展轮询,不按次数放弃** —— 持锁方还活着(两方言的锁都是连接级,随连接消失,不会遗留)就一直等,
- *    每 {@link LOCK_PROBE_WARN_EVERY} 次 warn 一行说明在等谁;**永不**无锁跑(「响亮地等」严格优于「静默地竞争 DDL」)。
- *  · **坏连接不是争用**(HC-2,对 7.82.1 的回归):探针自己**连续**抛 {@link MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} 次 =
- *    这条连接已不可用(`_queryable=false` / 半开 TCP),与「谁持锁」无关 ⇒ 上抛让启动响亮失败,不许无界轮。
- *    偶发一次抛(TiDB 悲观锁抖动)照旧继续轮,计数在一次成功探针后归零。
- *  · 轮询间隙进程不持任何快照(每次探针是亚毫秒的独立语句)⇒ 与 PG `CREATE INDEX CONCURRENTLY` 的
- *    `WaitForOlderSnapshots` 永不互等(理由全文见 `pg-pool.ts` `acquirePgEnsureSchemaLock` 头注)。
- */
 export declare const LOCK_PROBE_INITIAL_JITTER_MS = 400;
 export declare const LOCK_PROBE_WARN_EVERY = 40;
 export declare const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;

package/dist/plugins/ensure-schema-lock-policy.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 export const LOCK_PROBE_INITIAL_JITTER_MS = 400;
 export const LOCK_PROBE_WARN_EVERY = 40;
 export const MAX_CONSECUTIVE_LOCK_PROBE_ERRORS = 5;
@@ -17,13 +18,13 @@ export async function pollUntilLocked(tryOnce, opts) {
         catch (err) {
             consecutiveErrors += 1;
             const msg = err?.message ?? String(err);
-            console.warn(`[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
+            writeLogText("stderr", `[${opts.tag}] ${opts.label} probe attempt ${attempt + 1} threw (${consecutiveErrors}/${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS}):`, msg);
             if (consecutiveErrors >= MAX_CONSECUTIVE_LOCK_PROBE_ERRORS) {
                 throw new Error(`[${opts.tag}] ${opts.label}: lock probe threw ${MAX_CONSECUTIVE_LOCK_PROBE_ERRORS} times in a row — the connection itself is unusable, refusing to poll forever (last: ${msg})`, { cause: err });
             }
         }
         if (attempt > 0 && attempt % LOCK_PROBE_WARN_EVERY === 0) {
-            console.warn(`[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
+            writeLogText("stderr", `[${opts.tag}] still waiting for ${opts.label} (another replica is running the serialized DDL; attempt ${attempt})`);
         }
         await sleep(lockProbeBackoffMs(attempt));
     }

package/dist/plugins/execution-lane-rename-m40.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 🔴 一次性迁移 **M40**(窗口见 `plugins/one-time-migrations.ts` 登记表 M40 行;头注 M40 段):没有执行环境的那条车道的存词由退役名改成 `none`。
+ *
+ * 本文件是那一对词与「读到退役词时补哪一句」的**唯一属主**:SQL 腿(`one-time-migrations.ts` 的 M40 步,两方言两张表)、local 两腿(会话元数据边档 ——
+ * `LocalSessionStore.renameRetiredExecutionLaneWordM40`,排在严格边档对账之前;问账日志 —— `FileApprovalAskStore.renameRetiredExecutionLaneWordM40`,
+ * 排在 M32 回填之前)与两只 SQL 读口的拒句(`approval-ask-store-sql.ts` / `execution-placement-sql.ts`)都读这里。窗关删码 = 删这只文件与上面那几处调用。
+ *
+ * 本文件只 import 类型(零运行期依赖)⇒ 被一次性迁移段与它 import 的店文件同时读,不成环。
+ */
+import type { ExecutionLane } from "../execution-lane-caps.js";
+/** 退役的存词(本版之前的部署在没有声明车道时铸下的那一个)。本版的车道闭集里没有它,任何读口读到都响亮拒。 */
+export declare const RETIRED_EXECUTION_LANE_WORD_M40 = "in-process";
+/** 它的新名:声明「这一部署没有执行环境」的那条车道。 */
+export declare const RENAMED_EXECUTION_LANE_M40: ExecutionLane;
+/**
+ * 读口拒句的补句:读到的词就是退役词 ⇒ 说清它是什么、为什么还在(迁移之后又被写下 = 有一只更早版本的副本还在服务)与出路;别的词 ⇒ 空串(拒句不变)。
+ * 起服的迁移改完之后,只有混跑的旧副本还会写下它(版本围栏见登记表 M40 行与 MIGRATION 本版节)。
+ */
+export declare function retiredExecutionLaneHintM40(word: string): string;
+//# sourceMappingURL=execution-lane-rename-m40.d.ts.map

package/dist/plugins/execution-lane-rename-m40.js

@@ -0,0 +1,10 @@
+export const RETIRED_EXECUTION_LANE_WORD_M40 = "in-process";
+export const RENAMED_EXECUTION_LANE_M40 = "none";
+export function retiredExecutionLaneHintM40(word) {
+    if (word !== RETIRED_EXECUTION_LANE_WORD_M40)
+        return "";
+    return (` — "${RETIRED_EXECUTION_LANE_WORD_M40}" is the name an earlier version gave the lane with no execution environment, which this version calls "${RENAMED_EXECUTION_LANE_M40}"; ` +
+        "the one-time migration M40 at boot renames every stored copy, so this row was written afterwards by a replica of an earlier version that is still serving. " +
+        "Stop every replica of the earlier version, then restart this version once (its boot renames what they wrote)");
+}
+//# sourceMappingURL=execution-lane-rename-m40.js.map

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

@@ -1,92 +1,40 @@
 /**
- * **执行放置的 SQL 唯一模块** —— `session_meta` 上 `execution_*` 七列 + `fork_key` 一列的列定义、住客谓词、行 → 格解码、每一种转换的语句,
- * 与「写事务内先锁根行再读认领」那一读。规则在 `src/execution-placement.ts` 头注;本模块只说 SQL。
+ * **执行放置的 SQL 唯一模块** —— 执行放置七列 + `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 的连接都行)。
+ * ## 格住在部署旁表
+ * 八列住 `session_ext`(会话的部署格旁表,建表 / 外键 / 补行的唯一属主 = `session-ext-table.ts`;一会话一行,`ON DELETE CASCADE` 随 `session_meta` 行走),
+ * 不在引擎座表 `session_meta` 上(一张表一个 DDL 属主)。旁表行不在 = 八列全缺省(absent / 非键控 fork);写者在锁住根行之后按需补行。
  *
- * ## 住客谓词(写与 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`),永不对现住客重试。
+ * ## 属主
+ *  · 列定义住旁表属主(`session-ext-table.ts` 的 `EXECUTION_PLACEMENT_COLUMNS`;一次性迁移 M32 / M41 读同一份)。
+ *  · **语句唯一属主**:执行席、会话店的事务内钩(导入落 mirror)、设备店(首绑 / 换绑 / 绑定数)与一次性迁移的事务都借这里的语句,别处零手写。
+ *    语句是方言无关的 `{ text, values }`(调用方用自己的连接跑)。
  *
- * ## 读写序律(写事务内的认领读)
- * 改根住客 / 放置的每个写者(换绑 CAS · 导入三写口 · identical 补 mirror · 删除终刀 · 留存删除)在写事务内、用该事务自己的连接先 `FOR UPDATE` 锁根
- * `session_meta` 行,再以新语句锁定读 `task_active(root)`({@link lockRootAndReadClaim}):有认领 ⇒ 不写。全局锁序:设备行 → 根 meta → `task_*`
- * (`run-store-sql.ts` 的 `createRun` 同序先锁根行)。认领持有者自己的初始放置写(place / bind)是唯一例外,不读认领、仍按住客谓词。
+ * ## 写序律(一条,所有部署格的写者同一条)
+ * 改住客 / 放置的每个写者(place · 首绑 / 换绑 · identical 补 mirror · 导入写口 · 删除终刀 · 留存删除)在写事务内、用该事务自己的连接:
+ * ① `FOR UPDATE` 锁根 `session_meta` 行(读住客:属主 + 化身 + 委派判别位)→ ② 需要时新语句锁定读认领 `task_active(root)`({@link lockRootAndReadClaim})
+ * → ③ 补旁表行、再锁定读这一格({@link readCellOn};先补后锁:锁定读永远落在一行在的记录上,InnoDB 间隙锁不会让两只补行互等)→ 判官(住客对不对、格是什么)
+ * → ④ 一句按格谓词定址的 UPDATE。
+ * 住客由 ① 的锁钉住(删除 / 重登记 / 改属主都要先拿这把锁),所以写语句只按格谓词定址、不再带住客谓词;持锁判过「可写」之后 UPDATE 必中一行,0 行即引擎异常。
+ * 全局锁序:设备行 → 根 meta → `task_*` → 旁表行(`run-store-sql.ts` 的 `createRun` 同序先锁根行)。认领持有者自己的初始放置写(place / 首绑)是唯一不读认领的写。
  */
 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;
+/** 按根的一次池读(非事务;不加锁):根行 LEFT JOIN 旁表行。写事务内的当前读是 {@link readPlacementOn}(两句锁定读)。 */
+export declare function readPlacementRowStatement(dialect: SqlDialect, root: string): PlacementStatement;
 /**
  * place:absent → writer(L[, D]),`execution_rev = 0`。非 device 车道由会话店的执行席用(`device` 缺);device 车道的首绑由设备店在锁住设备行的
- * 同一事务里用(`device` 在场)。时刻用调用方的钟(与 `updated_at` 同一只)。
+ * 同一事务里用(`device` 在场)。时刻用调用方的钟。只在写序律 ① 锁住根行、判官答「可写」之后、{@link ensureSessionExtRowStatement} 补过行之后跑。
  */
-export declare function placeWriterStatement(dialect: SqlDialect, root: string, occupant: SessionFace, cell: {
+export declare function placeWriterStatement(dialect: SqlDialect, root: string, cell: {
     readonly lane: ExecutionLane;
     readonly device?: {
         readonly id: string;
@@ -94,14 +42,14 @@ export declare function placeWriterStatement(dialect: SqlDialect, root: string,
     };
 }, now: Date): PlacementStatement;
 /** bind:writer(device, ∅) → writer(device, D)(fresh 首绑撞上迁移回填的格),`execution_rev = 0`。 */
-export declare function bindDeviceStatement(dialect: SqlDialect, root: string, occupant: SessionFace, device: {
+export declare function bindDeviceStatement(dialect: SqlDialect, root: string, 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;
+/** rebind:writer(device, D) → writer(device, D'),按格 ∧ 两属主列 ∧ rev 定址,`execution_rev + 1`(恒变列)。属主两列不动(换绑只在同一属主的设备之间)。 */
+export declare function rebindDeviceStatement(dialect: SqlDialect, root: string, owner: DeviceOwner, expectedRev: number, targetDeviceId: string, now: Date): PlacementStatement;
 /**
- * 带设备列的根会话行(非委派分区行上 `execution_device_id` 非空):绑定数的读只用它**缩小**读的行 —— 一条绑定必有设备列,反之不然;
+ * 带设备列的根会话格(旁表上 `execution_device_id` 非空、根行不是委派分区行):绑定数的读只用它**缩小**读的行 —— 一条绑定必有设备列,反之不然;
  * 是不是一条绑定只由行的唯一解码 {@link placementCellFromRow} + `boundDeviceOf` 判(SQL 不另判一遍)。两方言同一句。
  */
 export declare function deviceCellRowsStatement(): PlacementStatement;
@@ -110,16 +58,23 @@ export declare function deviceCellRowsStatement(): PlacementStatement;
  * (设备在而属主 / rev / 时刻缺、设备落在别的车道)原样抛 {@link ExecutionPlacementRowError},不当一条绑定数进去,也不当没有。
  */
 export declare function countDeviceBindingsOn(conn: PlacementRowsOn): Promise<number>;
-/** identical 臂补 mirror:absent / mirror → mirror,WHERE 住客谓词 ∧ 不是 writer。 */
-export declare function markMirrorStatement(dialect: SqlDialect, root: string, occupant: SessionFace): PlacementStatement;
-/** 回填(一次性迁移):无执行格、非委派分区、有 run 行的会话行 ⇒ writer(表唯一项)。幂等(第二次跑零行)。 */
+/** identical 臂补 mirror(导入写口同一句):absent / mirror → mirror,WHERE 不是 writer。写序律同 {@link placeWriterStatement}。 */
+export declare function markMirrorStatement(dialect: SqlDialect, root: string): PlacementStatement;
+/** 回填(一次性迁移 M32,窗内;写的是 7.139–7.146 形 —— 八列在 `session_meta` 上,M41 随后连同其余部署格搬进旁表):无执行格、非委派分区、有 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`)整行覆盖
+ * 搬绑定(一次性迁移 M32,窗内;写 7.139–7.146 形的 `session_meta` 八列,同 {@link backfillWriterStatement}):按 `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;
+/**
+ * 搬绑定的**旁表形**(一次性迁移 M32 ③,窗内;库已是旁表形 —— M41 之后、或本版起的新库,执行格住 `session_ext`):与 {@link migrateDeviceBindingsStatement}
+ * 同一组覆盖(`rev` 原值、`bound_at → execution_placed_at`、只碰非委派分区行),按写序律先补旁表行(旁表属主的补行语句 {@link ensureSessionExtRowsStatement},不碰任何格)、
+ * 再一句 UPDATE 只写执行格(受影响行数 = 搬了几行,与 7.139–7.146 形同一读法)。
+ * 两句按序跑;`sourceTable` 是调用方的常量表名。
+ */
+export declare function migrateDeviceBindingsOntoSideTableStatements(dialect: SqlDialect, sourceTable: string): readonly [ensure: PlacementStatement, move: PlacementStatement];
 /** 搬绑定的孤儿计数(绑定行指向的根会话行不在,或是委派分区行 ⇒ 丢弃):迁移收据里点名的那个数。 */
 export declare function countOrphanBindingsStatement(dialect: SqlDialect, sourceTable: string): PlacementStatement;
 /** 一行放置读不通(角色 / 车道不在闭集,或列的组合不是四态之一)—— 响亮拒,不读作 absent(那等于把一行坏数据当成「还没放」放行给首交)。 */
@@ -144,18 +99,38 @@ export interface RootClaimReading {
     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` 不是它(另一只连接,不在锁序里)。根行不在 ⇒ 不读认领。
+ * 写序律 ②:根行已被本事务锁住之后,以新语句 `SELECT task_id FROM task_active WHERE session_id = ? FOR UPDATE` 锁定读认领(PG 读已提交下取新快照、
+ * TiDB 悲观事务是当前读)。只在写事务内、锁根行之后调(会话店的事务内钩在店锁住根行之后调它;其余写者经 {@link lockRootAndReadClaim} 一步做完 ① ②)。
+ */
+export declare function readClaimOn(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<string | null>;
+/**
+ * 写序律 ① ②(头注):**同一连接**上先锁根行,再锁定读认领。只在写事务内调;池级 `getActiveTaskId` 不是它(另一只连接,不在锁序里)。根行不在 ⇒ 不读认领。
  */
 export declare function lockRootAndReadClaim(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<RootClaimReading>;
-/** 写事务内按根的当前读(`FOR UPDATE`)→ 读数。 */
+/**
+ * 写序律 ③:锁住的旁表这一格。只在根行已被本事务锁住之后调。**先补行、再锁定读**(补行 = 缺省一行,读法与行不在同一):锁定读永远落在一行在的记录上 ——
+ * InnoDB 可重复读下,锁定读一只不在的键拿的是间隙锁(彼此兼容),两只事务随后各自补行时插入意向锁互等 ⇒ 死锁。之后的格写({@link writeCellOn})只剩一句 UPDATE。
+ */
+export declare function readCellOn(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<Exclude<ExecutionPlacementCell, {
+    role: "forking";
+}>>;
+/** 写事务内按根的当前读(写序律 ① + ③,两句锁定读)→ 读数。行不在 / 委派分区行 ⇒ `undefined`。 */
 export declare function readPlacementOn(conn: PlacementRowsOn, dialect: SqlDialect, root: string): Promise<ExecutionPlacementReading | undefined>;
+/** 格写只用到的那一面:一句语句、交回受影响行数(驱动的事务连接 `SqlExec` 与会话店交给部署钩的 `SessionTxStatements` 都满足它)。 */
+export interface PlacementCellWriter {
+    query(sql: string, params?: unknown[]): Promise<{
+        readonly affected: number;
+    }>;
+}
+/**
+ * 写序律 ④:一句格写(持锁判过「可写」之后;旁表行已在 —— 锁它的那一读 {@link readCellOn} 补的)。格写必中一行,0 行即引擎异常 ⇒ 响亮抛,不折成业务答案。
+ */
+export declare function writeCellOn(exec: PlacementCellWriter, dialect: SqlDialect, root: string, statement: PlacementStatement): Promise<void>;
 /**
- * SQL 会话店的执行席(两孪生同一只实现:语句与判官都在这里与 `execution-placement.ts`,方言只在语句文本里)。`db` = 店自己的池包成的 SqlDriver。
- *  · `read` —— 一次池读;
- *  · `place` —— 一句自动提交的 UPDATE(认领持有者自己的初始放置写:不读认领、按住客谓词);0 行 ⇒ 按根复读、交判官分类;
- *  · `markMirror` —— 一只事务:锁根行读认领 → 锁定读这一行 → 判官 → 有认领 ⇒ `active` → UPDATE(持锁下必中一行)。
+ * SQL 会话店的执行席(两孪生同一只实现:语句与判官都在这里与 `execution-placement.ts`,方言只在语句文本里)。`db` = 店的池包成的 SqlDriver。
+ *  · `read` —— 一次池读(根行 LEFT JOIN 旁表行);
+ *  · `place` —— 一只事务:锁根行读格(写序律 ① ③,不读认领:认领持有者自己的初始放置写;③ 先补行再锁定读)→ 判官 → 格写;
+ *  · `markMirror` —— 一只事务:锁根行读认领(① ②)→ 补行 + 锁定读这一格(③)→ 判官 → 有认领 ⇒ `active` → 格写。
  */
 export declare function createSqlExecutionPlacementSeat(db: Pick<SqlDriver, "dialect" | "query" | "connect">): ExecutionPlacementSeat;
 //# sourceMappingURL=execution-placement-sql.d.ts.map