@sema-agent/server 7.138.0 → 7.139.0

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

package/dist/plugins/execution-placement-sql.js

@@ -0,0 +1,223 @@
+import { isExecutionLane } from "../execution-lane-caps.js";
+import { sessionFaceFromRow } from "../session-incarnation.js";
+import { toIso } from "./sql-row-helpers.js";
+import { WRITABLE, assertPlaceableLane, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
+export const SESSION_META_PLACEMENT_COLUMNS = [
+    { name: "execution_role", tidb: "execution_role VARCHAR(16) NULL", pg: `execution_role VARCHAR(16) COLLATE "C"` },
+    { name: "execution_lane", tidb: "execution_lane VARCHAR(32) NULL", pg: `execution_lane VARCHAR(32) COLLATE "C"` },
+    { name: "execution_device_id", tidb: "execution_device_id VARCHAR(64) NULL", pg: `execution_device_id VARCHAR(64) COLLATE "C"` },
+    { name: "execution_device_owner_tenant", tidb: "execution_device_owner_tenant VARCHAR(190) NULL", pg: `execution_device_owner_tenant VARCHAR(190) COLLATE "C"` },
+    { name: "execution_device_owner_subject", tidb: "execution_device_owner_subject VARCHAR(190) NULL", pg: `execution_device_owner_subject VARCHAR(190) COLLATE "C"` },
+    { name: "execution_placed_at", tidb: "execution_placed_at DATETIME(3) NULL", pg: "execution_placed_at TIMESTAMPTZ(3)" },
+    { name: "execution_rev", tidb: "execution_rev BIGINT NULL", pg: "execution_rev BIGINT" },
+    { name: "fork_key", tidb: "fork_key VARCHAR(255) NULL", pg: `fork_key VARCHAR(255) COLLATE "C"` },
+];
+export function sessionMetaPlacementColumnsDdl(dialect) {
+    return SESSION_META_PLACEMENT_COLUMNS.map((c) => c[dialect]).join(",\n     ");
+}
+const WRITER = "writer";
+const MIRROR = "mirror";
+const NOT_WRITER = "(execution_role IS NULL OR execution_role <> 'writer')";
+export const MIRROR_ON_COMMIT_SET = "execution_role = 'mirror'";
+export const MIRROR_ON_COMMIT_GUARD = NOT_WRITER;
+export function importedRowCells(forkKey) {
+    return { columns: "fork_key, execution_role", values: [forkKey, MIRROR] };
+}
+export 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";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+function occupantPredicate(dialect, p, root, occupant) {
+    const nullSafeEq = dialect === "pg" ? "IS NOT DISTINCT FROM" : "<=>";
+    return `session_id = ${p(root)} AND incarnation = ${p(occupant.incarnation)} AND owner ${nullSafeEq} ${p(occupant.owner)} AND placement_kind IS NULL`;
+}
+export function readPlacementRowStatement(dialect, root, opts) {
+    const b = binder(dialect);
+    return { text: `SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS} FROM session_meta WHERE session_id = ${b.p(root)}${opts.lock ? " FOR UPDATE" : ""}`, values: b.values };
+}
+export function placeWriterStatement(dialect, root, occupant, cell, now) {
+    const b = binder(dialect);
+    const set = `execution_role = '${WRITER}', execution_lane = ${b.p(cell.lane)}, execution_device_id = ${b.p(cell.device?.id ?? null)}, ` +
+        `execution_device_owner_tenant = ${b.p(cell.device?.owner.tenant ?? null)}, execution_device_owner_subject = ${b.p(cell.device?.owner.subject ?? null)}, ` +
+        `execution_placed_at = ${b.p(now)}, execution_rev = 0`;
+    return { text: `UPDATE session_meta SET ${set} WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role IS NULL`, values: b.values };
+}
+export function bindDeviceStatement(dialect, root, occupant, device, now) {
+    const b = binder(dialect);
+    const set = `execution_device_id = ${b.p(device.id)}, execution_device_owner_tenant = ${b.p(device.owner.tenant)}, execution_device_owner_subject = ${b.p(device.owner.subject)}, execution_placed_at = ${b.p(now)}, execution_rev = 0`;
+    return {
+        text: `UPDATE session_meta SET ${set} WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role = '${WRITER}' AND execution_lane = 'device' AND execution_device_id IS NULL`,
+        values: b.values,
+    };
+}
+export function rebindDeviceStatement(dialect, root, occupant, owner, expectedRev, targetDeviceId, now) {
+    const b = binder(dialect);
+    const set = `execution_device_id = ${b.p(targetDeviceId)}, execution_placed_at = ${b.p(now)}, execution_rev = execution_rev + 1`;
+    const where = `${occupantPredicate(dialect, b.p, root, occupant)} AND execution_role = '${WRITER}' AND execution_lane = 'device' ` +
+        `AND execution_device_owner_tenant = ${b.p(owner.tenant)} AND execution_device_owner_subject = ${b.p(owner.subject)} AND execution_rev = ${b.p(expectedRev)}`;
+    return { text: `UPDATE session_meta SET ${set} WHERE ${where}`, values: b.values };
+}
+export function markMirrorStatement(dialect, root, occupant) {
+    const b = binder(dialect);
+    return { text: `UPDATE session_meta SET execution_role = '${MIRROR}' WHERE ${occupantPredicate(dialect, b.p, root, occupant)} AND ${NOT_WRITER}`, values: b.values };
+}
+export function backfillWriterStatement(dialect, lane, now) {
+    const b = binder(dialect);
+    return {
+        text: `UPDATE session_meta SET execution_role = '${WRITER}', execution_lane = ${b.p(lane)}, execution_placed_at = ${b.p(now)}, execution_rev = 0 ` +
+            "WHERE execution_role IS NULL AND placement_kind IS NULL AND EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = session_meta.session_id)",
+        values: b.values,
+    };
+}
+export function migrateDeviceBindingsStatement(dialect, sourceTable) {
+    if (dialect === "pg") {
+        return {
+            text: `UPDATE session_meta SET execution_role = '${WRITER}', execution_lane = 'device', execution_device_id = ds.device_id, ` +
+                "execution_device_owner_tenant = ds.owner_tenant, execution_device_owner_subject = ds.owner_subject, execution_placed_at = ds.bound_at, execution_rev = ds.rev " +
+                `FROM ${sourceTable} ds WHERE ds.root_session_id = session_meta.session_id AND session_meta.placement_kind IS NULL`,
+            values: [],
+        };
+    }
+    const str = (col) => `CONVERT(ds.${col} USING utf8mb4)`;
+    return {
+        text: `UPDATE session_meta sm JOIN ${sourceTable} ds ON ${str("root_session_id")} COLLATE utf8mb4_bin = sm.session_id ` +
+            `SET sm.execution_role = '${WRITER}', sm.execution_lane = 'device', sm.execution_device_id = ${str("device_id")}, ` +
+            `sm.execution_device_owner_tenant = ${str("owner_tenant")}, sm.execution_device_owner_subject = ${str("owner_subject")}, sm.execution_placed_at = ds.bound_at, sm.execution_rev = ds.rev ` +
+            "WHERE sm.placement_kind IS NULL",
+        values: [],
+    };
+}
+export function countOrphanBindingsStatement(dialect, sourceTable) {
+    const rootKey = dialect === "pg" ? "ds.root_session_id" : "CONVERT(ds.root_session_id USING utf8mb4) COLLATE utf8mb4_bin";
+    return {
+        text: `SELECT COUNT(*) AS orphans FROM ${sourceTable} ds WHERE NOT EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = ${rootKey} AND sm.placement_kind IS NULL)`,
+        values: [],
+    };
+}
+export class ExecutionPlacementRowError extends Error {
+    sessionId;
+    code = "execution_placement.row_unreadable";
+    constructor(sessionId, detail) {
+        super(`session ${sessionId}: the execution placement columns do not form a placement (${detail}) — refusing to read it as any placement`);
+        this.sessionId = sessionId;
+        this.name = "ExecutionPlacementRowError";
+    }
+}
+const isNull = (v) => v === null || v === undefined;
+const text = (v) => (Buffer.isBuffer(v) ? v.toString("utf8") : String(v));
+export function placementCellFromRow(root, row) {
+    const role = row.execution_role;
+    const deviceCols = [row.execution_device_id, row.execution_device_owner_tenant, row.execution_device_owner_subject];
+    if (isNull(role) || role === MIRROR) {
+        if (!isNull(row.execution_lane) || deviceCols.some((v) => !isNull(v)))
+            throw new ExecutionPlacementRowError(root, `role ${isNull(role) ? "NULL" : MIRROR} with a lane or device`);
+        return isNull(role) ? { role: "absent" } : { role: "mirror" };
+    }
+    if (role !== WRITER)
+        throw new ExecutionPlacementRowError(root, `role ${JSON.stringify(text(role))} is not writer / mirror / NULL`);
+    const lane = isNull(row.execution_lane) ? "" : text(row.execution_lane);
+    if (!isExecutionLane(lane))
+        throw new ExecutionPlacementRowError(root, `writer lane ${JSON.stringify(lane)} is not an execution lane`);
+    if (isNull(row.execution_device_id)) {
+        if (deviceCols.some((v) => !isNull(v)))
+            throw new ExecutionPlacementRowError(root, "device owner without a device");
+        return { role: "writer", lane };
+    }
+    if (lane !== "device")
+        throw new ExecutionPlacementRowError(root, `a device on the ${lane} lane`);
+    if (deviceCols.some(isNull) || isNull(row.execution_rev) || isNull(row.execution_placed_at))
+        throw new ExecutionPlacementRowError(root, "a device without its owner, rev or placement time");
+    return {
+        role: "writer",
+        lane,
+        device: {
+            id: text(row.execution_device_id),
+            owner: { tenant: text(row.execution_device_owner_tenant), subject: text(row.execution_device_owner_subject) },
+            rev: Number(row.execution_rev),
+            placedAt: toIso(row.execution_placed_at),
+        },
+    };
+}
+export function placementReadingFromRow(root, row) {
+    if (row === undefined || !isNull(row.placement_kind))
+        return undefined;
+    return { occupant: sessionFaceFromRow(root, isNull(row.owner) ? null : text(row.owner), row.incarnation), cell: placementCellFromRow(root, row) };
+}
+export function rowsOnSqlExec(exec) {
+    return async (sql, values) => (await exec.query(sql, [...values])).rows;
+}
+export async function lockRootAndReadClaim(conn, dialect, root) {
+    const ph = dialect === "pg" ? "$1" : "?";
+    const row = await conn(`SELECT session_id FROM session_meta WHERE session_id = ${ph} FOR UPDATE`, [root]);
+    if (row.length === 0)
+        return { rowPresent: false, activeTaskId: null };
+    const claim = await conn(`SELECT task_id FROM task_active WHERE session_id = ${ph} FOR UPDATE`, [root]);
+    return { rowPresent: true, activeTaskId: claim[0] === undefined ? null : text(claim[0].task_id) };
+}
+export async function readPlacementOn(conn, dialect, root) {
+    const s = readPlacementRowStatement(dialect, root, { lock: true });
+    return placementReadingFromRow(root, (await conn(s.text, s.values))[0]);
+}
+function placementInvariant(root, what) {
+    return new Error(`execution placement of session ${root}: ${what} matched no row while a re-read finds the cell writable — engine/driver anomaly, refusing to guess`);
+}
+export function createSqlExecutionPlacementSeat(db) {
+    const read = async (root) => {
+        const s = readPlacementRowStatement(db.dialect, root, { lock: false });
+        return placementReadingFromRow(root, (await db.query(s.text, [...s.values])).rows[0]);
+    };
+    return {
+        read,
+        async place(root, occupant, cell) {
+            assertPlaceableLane(root, cell);
+            const s = placeWriterStatement(db.dialect, root, occupant, { lane: cell.lane }, new Date());
+            if ((await db.query(s.text, [...s.values])).affected === 1)
+                return { outcome: "placed" };
+            const settled = settledPlaceOutcome(root, await read(root), occupant, cell);
+            if (settled === WRITABLE)
+                throw placementInvariant(root, "place");
+            return settled;
+        },
+        async markMirror(root, occupant) {
+            const conn = await db.connect();
+            try {
+                await conn.begin();
+                const rowsOn = rowsOnSqlExec(conn);
+                const claim = await lockRootAndReadClaim(rowsOn, db.dialect, root);
+                if (!claim.rowPresent) {
+                    await conn.rollback();
+                    return { outcome: "gone" };
+                }
+                const settled = settledMirrorOutcome(root, await readPlacementOn(rowsOn, db.dialect, root), occupant);
+                if (settled !== WRITABLE) {
+                    await conn.rollback();
+                    return settled;
+                }
+                if (claim.activeTaskId !== null) {
+                    await conn.rollback();
+                    return { outcome: "active", activeTaskId: claim.activeTaskId };
+                }
+                const s = markMirrorStatement(db.dialect, root, occupant);
+                if ((await conn.query(s.text, [...s.values])).affected !== 1)
+                    throw placementInvariant(root, "markMirror under a held row lock");
+                await conn.commit();
+                return { outcome: "mirrored" };
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        },
+    };
+}
+//# sourceMappingURL=execution-placement-sql.js.map

package/dist/plugins/file-history-store-sql.d.ts

@@ -183,15 +183,16 @@ export declare class PgFileHistoryStore extends SqlFileHistoryStore {
 }
 /**
  * [ref] D1② — A7-recipe upgrade precondition assert (**refuse to start**, never a warn; the form and
- * rationale follow `assertPermissionRuleTicketSchema` verbatim: this repo ships no ALTER TABLE, and
+ * rationale follow `assertPermissionRuleTicketSchema` verbatim: the boot check never alters a table, and
  * `CREATE TABLE IF NOT EXISTS` is a no-op on an existing table whose columns predate this build).
  *
  * The probe is one always-empty `WHERE 1=0` read per table naming every column this build references.
- * ONLY a provable missing-column error gets the destructive recreate guidance — everything else
- * (timeout / reset / permission / missing table) rethrows untouched: advising `DROP TABLE` for a
- * connection blip is more expensive than the defect this gate exists to stop. Honest cost statement:
- * dropping these tables loses per-file REWIND history (working-tree convenience state) — session
- * transcripts and every other durable subsystem are untouched.
+ * ONLY a provable missing-column error gets the missing-column refusal — everything else
+ * (timeout / reset / permission / missing table) rethrows untouched: diagnosing a connection blip as a
+ * schema drift is more expensive than the defect this gate exists to stop. The refusal's ways out are the
+ * closed set of three shared with the whole-database check (`describeProbedTableDrift`); none of them
+ * is destructive. Honest cost statement: the history lives in these tables (per-file REWIND history,
+ * working-tree convenience state) — session transcripts and every other durable subsystem are untouched.
  */
 export declare function assertFileHistorySchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];

package/dist/plugins/file-history-store-sql.js

@@ -3,6 +3,7 @@ import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenD
 import { BlobTooLargeError, SqlBlobBackend } from "./blob-backend.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
+import { describeProbedTableDrift } from "./schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -835,11 +836,10 @@ export async function assertFileHistorySchema(query, dialect) {
                 throw err;
             throw new Error(`${table} is missing required columns — refusing to start. This build's per-file rewind history (S-15) ` +
                 `references every probed column unconditionally; a partial table would fail mid-write and could publish a ` +
-                `half-shaped history graph. This repository ships no ALTER TABLE migrations, so the table must be recreated: run ` +
-                `\`DROP TABLE ${table};\` on the ${dialect === "pg" ? "PostgreSQL" : "MySQL-protocol"} backend and restart — the ` +
-                `schema is recreated at boot. Cost, honestly stated: dropping file_history_* tables loses per-file REWIND history ` +
-                `(working-tree convenience state); session transcripts and all other durable subsystems are untouched. ` +
-                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}`);
+                `half-shaped history graph. The file_history_* tables hold the per-file REWIND history (working-tree convenience ` +
+                `state); session transcripts and all other durable subsystems are untouched, and an in-place ALTER keeps the history.\n` +
+                `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                (await describeProbedTableDrift(query, dialect, [table])));
         }
     }
 }

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

@@ -152,7 +152,7 @@ export declare class FileRunStore implements InProcessClaimFence {
     whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
-     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, a device-placement reject):
+     *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement reject):
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;
@@ -332,6 +332,11 @@ export declare class FileRunStore implements InProcessClaimFence {
      * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);数据根独占 ⇒ 本车道没有滚动升级窗,不需要读侧半场。幂等:第二跑零命中零写盘。
      */
     migrateLegacyHolderDeathCodes(): number;
+    /**
+     * 一次性迁移 **M32 的 local 腿**(执行放置回填;窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表):有 run 行的会话 id(去重)。
+     * 起服时调(`LocalBackend.runOneTimeMigrations`,任何读者之前);读内存索引(构造时已从盘上 hydrate),零写。
+     */
+    sessionIdsWithRuns(): ReadonlySet<string>;
     /** Release every open event-log fd (called by LocalBackend.close so a graceful restart can re-open the data dir). */
     dispose(): void;
 }

package/dist/plugins/file-run-store.js

@@ -280,6 +280,7 @@ export class FileRunStore {
                     "Refusing to boot with an EMPTY single-active claim index (every session would look unclaimed, so a delete or a fresh run could race a live/parked one). " +
                     "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
             }
+            recordFailOpen("server.run-store.file-active-claims-unreadable", detail);
             claims = [];
         }
         const nonTerminalBySanitizedSession = new Map();
@@ -1009,6 +1010,9 @@ export class FileRunStore {
         }
         return migrated;
     }
+    sessionIdsWithRuns() {
+        return new Set([...this.runs.values()].map((r) => r.sessionId));
+    }
     dispose() {
         for (const log of this.eventLogs.values()) {
             try {

package/dist/plugins/fork-routing-session-store.d.ts

@@ -25,6 +25,8 @@
  */
 import { type SessionStore, type AcquiredSession, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
 import { type DelegationTree } from "../delegated-session-owner.js";
+import type { ExecutionPlacementSeat } from "../execution-placement.js";
+import type { ForkToFn } from "./session-fork.js";
 /** acquire 选项形(core 5.48 SessionStore 契约):[ref] placement=受信 spawner 的分区建会话声明。 */
 type AcquireOpts = {
     requireExisting?: boolean;
@@ -54,6 +56,10 @@ export declare class ForkRoutingSessionStore implements SessionStore {
         olderThanMs?: number;
         scope?: string;
     }) => Promise<PlacedSessionRow[]>;
+    /** 执行席透传(host 有才有):执行放置是**根会话行**上的一格,根会话行住 host durable 店;transient 店没有会话行可放,也就不声明席。 */
+    readonly executionPlacement?: ExecutionPlacementSeat;
+    /** fork 续写的店契约透传(host 有才有):目标在 host 店原子新建,新 id 与源一并记 host 路由(与 {@link fork} 的 host 腿同)。 */
+    readonly forkTo?: ForkToFn;
     constructor(host: SessionStore, transient: SessionStore);
     private remember;
     private pick;

package/dist/plugins/fork-routing-session-store.js

@@ -11,6 +11,8 @@ export class ForkRoutingSessionStore {
     placed = new Set();
     placements;
     listPlaced;
+    executionPlacement;
+    forkTo;
     constructor(host, transient) {
         this.host = host;
         this.transient = transient;
@@ -23,6 +25,20 @@ export class ForkRoutingSessionStore {
         if (host.fork === undefined && transient.fork === undefined) {
             this.fork = undefined;
         }
+        const hostFaces = host;
+        if (hostFaces.executionPlacement !== undefined)
+            this.executionPlacement = hostFaces.executionPlacement;
+        const hostForkTo = hostFaces.forkTo;
+        if (typeof hostForkTo === "function") {
+            this.forkTo = async (sourceId, owner, target) => {
+                const out = await hostForkTo.call(host, sourceId, owner, target);
+                if (out !== null && out.outcome !== "occupied") {
+                    this.remember(sourceId, "host");
+                    this.remember(out.id, "host");
+                }
+                return out;
+            };
+        }
     }
     remember(id, where) {
         this.route.delete(id);