@sema-agent/server 7.146.0 → 7.148.0

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

@@ -0,0 +1,157 @@
+/**
+ * **SQL 会话店 = 引擎座店 + 部署的会话格**(两方言同一只类;组合座 `store-backend.ts` 装配)。
+ *
+ * ## 两半,一只店
+ *  · **座**(`src/stores-sql/` 的方言店):引擎座表 `session_meta` / `session_event` 的唯一写者 —— 唤醒、追加、fork、导入、暂存、删除。
+ *  · **部署格**(本模块):本服务记在一只会话上的格,全部住旁表 `session_ext`(属主 `session-ext-table.ts`)—— 列表投影的标题 / 置顶 / 行标签、
+ *    换源通告的基线、位置与项目、执行放置那一格与 fork 键。读引擎座表只经它的公布列(身份、属主、化身、时刻、委派判别位、fork 谱系的源 id);写只写旁表。
+ * 座在它的写事务里锁住根行之后调部署的**事务内钩**({@link createSqlSessionWriteHooks},契约在 `stores-sql/session-write-hooks.ts`)——
+ * 认领、本处写者、导入落 mirror、fork 键都在座的同一事务里由钩判 / 写(同事务两句:锁根行一句、钩的读写各一句)。
+ *
+ * ## 一条列表读口
+ * 列表面(`listSessions` / `listSessionRows` / `sessionSummaryOf`)是一条 SELECT、一只行映射({@link SqlSessionStore.selectListRows}):
+ * `session_meta` LEFT JOIN 旁表(标题 / 置顶;行不在 = 未命名、未置顶)LEFT JOIN run 账本的预览。两方言只差语句文本(窗函数 / `DISTINCT ON`、JSON 标量提取、
+ * LIKE 的转义字面量、布尔的读法)。
+ *
+ * ## 旁表的写序(一条,与执行放置的写序律同一条)
+ * 每个格写者在一只事务里:锁根 `session_meta` 行(行不在 ⇒ 不写)→ 补旁表行(行在不动)→ 要判格的再锁定读那一行 → 一句按 `session_id` 定址的格写。根行先 ⇒ 与座的删除 /
+ * 导入 / 换装同一锁序,外键的补行不会与删除的级联互等;补行先于锁定读 ⇒ 锁定读永远落在一行在的记录上(不拿 InnoDB 间隙锁)。
+ */
+import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import type { TiDBSessionStore } from "../stores-sql/tidb-session-store.js";
+import type { SessionWriteHooks } from "../stores-sql/session-write-hooks.js";
+import type { SqlDriver } from "./sql-driver.js";
+import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import { type RegisterReceipt, type SessionBirth, type WithdrawOutcome } from "../session-incarnation.js";
+import { type SessionDeletionFace } from "../session-deletion.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import type { SessionSummary } from "./store-contracts.js";
+import type { SessionWorkspace } from "../session-workspace.js";
+/** 座的面:座的公开成员(两方言同形 —— PG 孪生按结构赋给它,组合座里 tsc 判)。 */
+export type SessionSeat = Pick<TiDBSessionStore, "retention" | "placements" | "durability" | "acquire" | "register" | "registerWithReceipt" | "deleteSessionIf" | "placementOf" | "listPlaced" | "headOf" | "touch" | "release" | "forget" | "fork" | "forkTo" | "exportEntries" | "listEntryIds" | "exportEntriesStream" | "importEntries" | "replaceEntries" | "beginImportStaging" | "readStagedEntries" | "sweepStagingSessions" | "size" | "dispose">;
+/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形)。 */
+export interface SessionListOptions {
+    owner?: string;
+    includeUnowned?: boolean;
+    cursor?: {
+        lastActivityAt: string;
+        sessionId: string;
+    };
+    limit: number;
+    q?: string;
+}
+/**
+ * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
+ *  · 四个词同一只判官 {@link judgeSessionWrite}(local 店的写锁内同调这一只):`erase` 只判这一行的在删令牌(不是 ⇒ 拒 `SessionDeletionSupersededError`);其余认领在 ⇒ 拒 `SessionActiveRunError`;
+ *    `import` 再判这一处是写者 ⇒ 拒 `SessionWriterPresentError`;
+ *  · `import` 放行 ⇒ 这一格落 mirror(写者在别处)、客户端写计数 +1;删除三词放行 ⇒ 什么都不写(级联随根行带走旁表行,钩不另删);
+ *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
+ */
+export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
+export declare class SqlSessionStore implements SessionStore {
+    private readonly db;
+    /** 座(引擎座表的唯一写者)。 */
+    private readonly seat;
+    /** 托管留存声明 / placement 声明 / 耐久声明:座的声明逐字转发。 */
+    readonly retention: SessionSeat["retention"];
+    readonly placements: SessionSeat["placements"];
+    readonly durability: SessionSeat["durability"];
+    /** 执行席(规则在 `src/execution-placement.ts`;实现与语句的唯一属主 = `execution-placement-sql.ts`)。 */
+    readonly executionPlacement: ExecutionPlacementSeat;
+    /** `db` = 座的池包成的 SqlDriver(同一只池);`seatOn` 拿部署的事务内钩建座。 */
+    constructor(db: SqlDriver, seatOn: (hooks: SessionWriteHooks) => SessionSeat);
+    acquire(...a: Parameters<SessionSeat["acquire"]>): Promise<AcquiredSession>;
+    register(sessionId: string, owner: string | null): Promise<void>;
+    /** 出生回执面(座逐字转发;`plugins/session-birth.ts`)。 */
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    /** 条件撤回面:座的条件删除 + 本部署的判据(启用标记 / 客户端写计数 / 别的 run / 本次 run 的部署行;同一事务)。 */
+    withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
+    listPlaced(...a: Parameters<SessionSeat["listPlaced"]>): Promise<PlacedSessionRow[]>;
+    /**
+     * 按 id 读一行(属主 / 住客 / 叶子一次读)—— 座的那一读加一条「不在删」:在删的行对删除门之外的读者读作不在(会话三态,`src/session-deletion.ts`)。
+     * 一条 PK SELECT(根行 LEFT JOIN 旁表行),不上锁。
+     */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
+    /** 删除门的头读(`OwnerAwareSessionStore.deletionHeadOf`):活行 ∪ 在删行 —— 座的原始一读。开始删它的那位属主重发删除(= 接管)就过得了门;别人得到与「不在」同一句。 */
+    deletionHeadOf(sessionId: string): Promise<SessionHead | undefined>;
+    touch(sessionId: string): Promise<void>;
+    release(sessionId: string): Promise<void>;
+    forget(sessionId: string): void;
+    fork(...a: Parameters<SessionSeat["fork"]>): ReturnType<SessionSeat["fork"]>;
+    forkTo(...a: Parameters<SessionSeat["forkTo"]>): ReturnType<SessionSeat["forkTo"]>;
+    exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+    listEntryIds(sessionId: string): Promise<string[] | null>;
+    exportEntriesStream(...a: Parameters<SessionSeat["exportEntriesStream"]>): ReturnType<SessionSeat["exportEntriesStream"]>;
+    importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    beginImportStaging(...a: Parameters<SessionSeat["beginImportStaging"]>): ReturnType<SessionSeat["beginImportStaging"]>;
+    readStagedEntries(stagingId: string): Promise<SessionTreeEntry[]>;
+    sweepStagingSessions(): Promise<number>;
+    readonly sessionDeletion: SessionDeletionFace;
+    /**
+     * 围栏(删除路唯一的认领判):一只事务 —— 锁根行(读属主与住客)→ 不在 / 属主不等 ⇒ 回滚、`undefined` → 补旁表行 + 锁定读在删令牌 →
+     *  · 活 ∧ 不带 `expect` ⇒ 判认领(判官 `judgeSessionWrite` 的 `delete` 臂,锁定读 `task_active`;在 ⇒ 回滚、抛 `SessionActiveRunError`)→ 写新令牌;
+     *    活 ∧ 带 `expect`(收尾者)⇒ 回滚、`undefined` —— 收尾者读到之后那一次删完、同 id 重登记的新行不被碰;
+     *  · 在删 ∧ 带 `expect` 而持有的不是它 ⇒ `undefined`;持有者仍可能活着(`running`,或 `elsewhere` 且令牌铸于接管期限之内 —— 别的副本上那一次可能还在跑)⇒
+     *    回滚、`{ inProgress }`;否则 ⇒ 接管(换新令牌;不判认领:在删期间规则 L 不让认领落下)。
+     * 写序与旁表的其余格写者同一条(根行 → 旁表;根行先 ⇒ 与认领事务、座的删除 / 导入同一锁序)。
+     */
+    private fenceDeletion;
+    get size(): number;
+    dispose(): void;
+    /**
+     * E16 — list the caller's sessions (CC /resume picker), keyset-paginated newest-first by last activity. Session IDENTITY/enumeration comes from
+     * `session_meta` (owner-filtered on its owner column); the side table supplies the title / pin; LEFT JOINs onto the `task_run` runs ledger
+     * supply the run-derived half (latest run's status / task_id / runId, run count, the preview) but never gate which sessions exist. Keyset on `(updated_at, session_id)`.
+     */
+    listSessions(opts: SessionListOptions): Promise<SessionSummary[]>;
+    /** {@link listSessions} with each row's occupant (owner + incarnation) from the same SELECT — `OwnerAwareSessionStore.listSessionRows`; the incarnation never enters the row. */
+    listSessionRows(opts: SessionListOptions): Promise<Array<SessionRowAnswer<SessionSummary>>>;
+    /** ONE session's list row — {@link listSessions}' projection (same SELECT, same mapper) scoped to one id; `undefined` = not a row of the list face
+     *  (no such session / placed). The run subqueries are scoped to the same id. */
+    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
+    /** {@link sessionSummaryOf} 那一读 + 读到它时行上的住客(写原语的应答行要复核住客,`settleSessionRowWrite`)。 */
+    private listRowOf;
+    /**
+     * The list projection's ONE SELECT + row mapper ({@link listSessions} and {@link sessionSummaryOf} both read through it). `runSessionId` scopes the
+     * three run subqueries to one session (the single-row read); the list leaves them whole. Placeholders are minted in text order (run scope ×3,
+     * then `where`, then the LIMIT), so one builder serves both dialects. `sm.incarnation` is read for the row tag and the answer row's occupant only.
+     * The run JOINs (the run-derived half of the row — `SessionRunRollup` in `store-contracts.ts`; the local twin's rule is `session-run-rollup.ts`, one case table pins both):
+     *  · a count rollup;
+     *  · `latest` = the LATEST run per session (`created_at DESC, task_id DESC`, ties broken by task_id so EXACTLY one row joins) ⇒ status / task_id / runId;
+     *  · `preview` = the most recent run whose preview column is non-empty BY CHARACTER LENGTH ({@link RUN_PREVIEW_PRESENT}) ⇒ `objectivePreview` — decoupled
+     *    from `latest`: a last turn with no user text (column `""`) falls back to the sentence before it; none ⇒ NULL.
+     * LEFT JOINs keep sessions with no runs (preview NULL, run_count 0) and sessions with no side-table row (title NULL, not pinned).
+     */
+    private selectListRows;
+    /**
+     * 会话行格写原语 —— 用户标题 / 置顶的唯一写口(规则与判序:`src/session-row.ts` 头注「写原语」;事务与语句:`session-row-sql.ts`)。应答行在提交 / 回滚之后
+     * 由列表行读另读(含新 `rowTag`)、复核仍是判过的那一位住客。只写列表面上的行(委派分区行 ⇒ `absent`);`updated_at` 不动(改名不是活动)。
+     */
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
+    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
+    /** Cheap pre-LLM probe: "none" = session_meta row not yet REGISTERED (createRun fires before the Runner's session acquire — the titler retries),
+     *  "untitled" / "titled" as read (no side-table row = untitled). */
+    probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
+    /** The auto-titler's write: lands ONLY when title IS NULL (a concurrent/prior title — the user's included — wins; writer order: `src/session-row.ts`).
+     *  Returns whether this call set it. No session row ⇒ `false`. */
+    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** 换源通告的基线读(一行 PK 读;列的三态读法见 `instruction-source-notice.ts`)。旁表行不在 ⇒ 读作「没记过」。语句期限 {@link BASELINE_IO_DEADLINE_MS}(过期 ⇒ 查询自己拒、连接销毁)。 */
+    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
+    /**
+     * CAS 覆写基线(期望值 = 调用方读到的那一份;不符 ⇒ 0 行、不抛 —— 契约见 `InstructionSourceStore`)。会话行不在 ⇒ 不写。**不**碰 `updated_at`。
+     * 期限:事务里每一句带语句期限 {@link BASELINE_IO_DEADLINE_MS} —— 被行锁卡住的写由查询自己在期限内拒、连接销毁(事务随连接关闭回滚,池里不留卡住的连接);
+     * 调用方的 `withinIoDeadline` 同一只数,是它那一侧的放手。
+     */
+    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /** 会话行的位置与项目那一格(域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座)。**住客围栏**:只写化身仍是 `incarnation` 的那一行(锁根行时按化身收窄)—— 行不在、或同 id 已换了住客 ⇒
+     * 不写、不抛。**不**碰 `updated_at`。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
+}
+//# sourceMappingURL=session-store-sql.d.ts.map

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

@@ -0,0 +1,398 @@
+import { uuidv7 } from "@sema-agent/core";
+import { escapeLike } from "./sql-escape.js";
+import { jsonColumnText } from "./sql-json-column.js";
+import { pgSafeJsonStringify } from "./pg-safe-json.js";
+import { DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement, readDeletingTokenOn } from "./session-ext-table.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
+import { createSqlExecutionPlacementSeat, markMirrorStatement, readCellOn, readClaimOn, writeCellOn } from "./execution-placement-sql.js";
+import { judgeSessionWrite, sessionWriteTouchesCell } from "../execution-placement.js";
+import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
+import { forkLineageOfRow, headFromRow, incarnationFromCell } from "../session-incarnation.js";
+import { CROSS_PROCESS_TAKEOVER_AFTER_MS, deletionTokenMintedAt } from "../session-deletion.js";
+import { sessionRowTagKey } from "../session-row.js";
+import { writeSessionRowCellsSql } from "./session-row-sql.js";
+import { bumpClientWritesOn, createSqlWithdrawJudge } from "./session-withdraw-sql.js";
+import { WITHDRAWABLE_ENTRY_TYPES } from "./session-birth.js";
+const RUN_PREVIEW_PRESENT = "CHAR_LENGTH(objective_preview) > 0";
+function binder(dialect) {
+    const values = [];
+    return {
+        values,
+        p: (v) => {
+            values.push(v);
+            return dialect === "pg" ? `$${values.length}` : "?";
+        },
+    };
+}
+const rowsOnTxn = (txn) => async (sql, values) => (await txn.query(sql, [...values])).rows;
+export function createSqlSessionWriteHooks(db) {
+    const dialect = db.dialect;
+    return {
+        async beforeCommit(txn, write) {
+            const rows = rowsOnTxn(txn);
+            const root = write.rootSessionId;
+            const verdict = await judgeSessionWrite(write, { claim: () => readClaimOn(rows, dialect, root), cell: () => readCellOn(rows, dialect, root), deleting: () => readDeletingTokenOn(rows, dialect, root) });
+            if (verdict !== "proceed")
+                return verdict;
+            if (sessionWriteTouchesCell(write.op)) {
+                await writeCellOn(txn, dialect, root, markMirrorStatement(dialect, root));
+                await bumpClientWritesOn(txn, dialect, root);
+            }
+            return "proceed";
+        },
+        keyedFork: {
+            async record(txn, fork) {
+                const ensure = ensureSessionExtRowStatement(dialect, fork.rootSessionId);
+                await txn.query(ensure.text, [...ensure.values]);
+                const b = binder(dialect);
+                const res = await txn.query(`UPDATE ${SESSION_EXT_TABLE} SET fork_key = ${b.p(fork.forkKey)} WHERE session_id = ${b.p(fork.rootSessionId)}`, b.values);
+                if (res.affected !== 1)
+                    throw new Error(`fork of session ${fork.rootSessionId}: the fork key write matched no row of a row this transaction just created — engine/driver anomaly, refusing to guess`);
+            },
+            async targetOf(sessionId) {
+                const b = binder(dialect);
+                const row = (await db.query(`SELECT sm.owner, se.fork_key FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+                if (row === undefined)
+                    return undefined;
+                return { owner: row.owner === null || row.owner === undefined ? null : String(row.owner), forkKey: row.fork_key === null || row.fork_key === undefined ? null : String(row.fork_key) };
+            },
+        },
+    };
+}
+const BASELINE_STATEMENT = { deadlineMs: BASELINE_IO_DEADLINE_MS };
+async function withLockedSessionExt(db, sessionId, lock, write) {
+    const conn = await db.connect();
+    const query = (sql, params) => conn.query(sql, params, lock.statement);
+    try {
+        await conn.begin();
+        const b = binder(db.dialect);
+        const locked = await query(`SELECT session_id FROM session_meta WHERE session_id = ${b.p(sessionId)}${lock.where === undefined ? "" : ` AND ${lock.where(b.p)}`} FOR UPDATE`, b.values);
+        if (locked.rows.length === 0) {
+            await conn.rollback();
+            return false;
+        }
+        const ensure = ensureSessionExtRowStatement(db.dialect, sessionId);
+        await query(ensure.text, [...ensure.values]);
+        const wrote = await write(query);
+        await conn.commit();
+        return wrote;
+    }
+    catch (err) {
+        await conn.rollback().catch(() => undefined);
+        throw err;
+    }
+    finally {
+        conn.release();
+    }
+}
+const pinnedOf = (dialect, v) => (dialect === "pg" ? v === true : Number(v) === 1);
+const listedLineageOf = (sessionId, forkedFrom) => {
+    const lineage = forkLineageOfRow(sessionId, forkedFrom, undefined);
+    return lineage.forkedFrom !== undefined ? { forkedFrom: lineage.forkedFrom } : {};
+};
+function holderMayBeAlive(holder, token) {
+    switch (holder) {
+        case "running":
+            return true;
+        case "ended":
+            return false;
+        case "elsewhere": {
+            const minted = deletionTokenMintedAt(token);
+            return minted === undefined || Date.now() - minted < CROSS_PROCESS_TAKEOVER_AFTER_MS;
+        }
+    }
+}
+export class SqlSessionStore {
+    db;
+    seat;
+    retention;
+    placements;
+    durability;
+    executionPlacement;
+    constructor(db, seatOn) {
+        this.db = db;
+        this.seat = seatOn(createSqlSessionWriteHooks(db));
+        this.retention = this.seat.retention;
+        this.placements = this.seat.placements;
+        this.durability = this.seat.durability;
+        this.executionPlacement = createSqlExecutionPlacementSeat(db);
+    }
+    acquire(...a) {
+        return this.seat.acquire(...a);
+    }
+    register(sessionId, owner) {
+        return this.seat.register(sessionId, owner);
+    }
+    registerWithReceipt(sessionId, owner) {
+        return this.seat.registerWithReceipt(sessionId, owner);
+    }
+    withdrawBirth(birth, ownTaskId) {
+        const cond = {
+            expect: { owner: birth.owner, incarnation: birth.incarnation },
+            withdrawableEntryTypes: WITHDRAWABLE_ENTRY_TYPES,
+            judge: createSqlWithdrawJudge(this.db.dialect, birth.sessionId, ownTaskId),
+        };
+        return this.seat.deleteSessionIf(birth.sessionId, cond);
+    }
+    placementOf(sessionId) {
+        return this.seat.placementOf(sessionId);
+    }
+    listPlaced(...a) {
+        return this.seat.listPlaced(...a);
+    }
+    async headOf(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT sm.owner, sm.incarnation, sm.leaf_id FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            `WHERE sm.session_id = ${b.p(sessionId)} AND se.${DELETING_TOKEN_COLUMN.name} IS NULL`, b.values)).rows[0];
+        if (row === undefined)
+            return undefined;
+        return headFromRow(sessionId, row.owner ?? null, row.incarnation, row.leaf_id ?? null);
+    }
+    deletionHeadOf(sessionId) {
+        return this.seat.headOf(sessionId);
+    }
+    touch(sessionId) {
+        return this.seat.touch(sessionId);
+    }
+    release(sessionId) {
+        return this.seat.release(sessionId);
+    }
+    forget(sessionId) {
+        this.seat.forget(sessionId);
+    }
+    fork(...a) {
+        return this.seat.fork(...a);
+    }
+    forkTo(...a) {
+        return this.seat.forkTo(...a);
+    }
+    exportEntries(sessionId) {
+        return this.seat.exportEntries(sessionId);
+    }
+    listEntryIds(sessionId) {
+        return this.seat.listEntryIds(sessionId);
+    }
+    exportEntriesStream(...a) {
+        return this.seat.exportEntriesStream(...a);
+    }
+    importEntries(sessionId, owner, entries) {
+        return this.seat.importEntries(sessionId, owner, entries);
+    }
+    replaceEntries(sessionId, owner, entries) {
+        return this.seat.replaceEntries(sessionId, owner, entries);
+    }
+    beginImportStaging(...a) {
+        return this.seat.beginImportStaging(...a);
+    }
+    readStagedEntries(stagingId) {
+        return this.seat.readStagedEntries(stagingId);
+    }
+    sweepStagingSessions() {
+        return this.seat.sweepStagingSessions();
+    }
+    sessionDeletion = {
+        fence: (sessionId, owner, opts) => this.fenceDeletion(sessionId, owner, opts),
+        holds: async (sessionId, token) => {
+            const b = binder(this.db.dialect);
+            const row = (await this.db.query(`SELECT ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+            return row !== undefined && row[DELETING_TOKEN_COLUMN.name] === token;
+        },
+        pending: async () => {
+            const rows = (await this.db.query(`SELECT sm.session_id, sm.owner, se.${DELETING_TOKEN_COLUMN.name} AS token FROM session_meta sm JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE se.${DELETING_TOKEN_COLUMN.name} IS NOT NULL ORDER BY sm.session_id`, [])).rows;
+            return rows.map((r) => ({ sessionId: String(r.session_id), owner: r.owner ?? null, token: String(r.token) }));
+        },
+    };
+    async fenceDeletion(sessionId, owner, opts) {
+        const dialect = this.db.dialect;
+        const conn = await this.db.connect();
+        try {
+            await conn.begin();
+            const rows = async (sql, values) => (await conn.query(sql, [...values])).rows;
+            const root = (await rows(`SELECT owner, incarnation FROM session_meta WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+            if (root === undefined || (root.owner ?? null) !== owner) {
+                await conn.rollback();
+                return undefined;
+            }
+            const held = await readDeletingTokenOn(rows, dialect, sessionId);
+            if (held === null) {
+                if (opts.expect !== undefined) {
+                    await conn.rollback();
+                    return undefined;
+                }
+                const verdict = await judgeSessionWrite({ op: "delete", rootSessionId: sessionId }, { claim: () => readClaimOn(rows, dialect, sessionId), cell: async () => ({ role: "absent" }), deleting: async () => held });
+                if (verdict !== "proceed") {
+                    await conn.rollback();
+                    throw verdict.refuse;
+                }
+            }
+            else {
+                if (opts.expect !== undefined && held !== opts.expect) {
+                    await conn.rollback();
+                    return undefined;
+                }
+                if (holderMayBeAlive(opts.holder(held), held)) {
+                    await conn.rollback();
+                    return { inProgress: true };
+                }
+            }
+            const token = uuidv7();
+            const b = binder(dialect);
+            const res = await conn.query(`UPDATE ${SESSION_EXT_TABLE} SET ${DELETING_TOKEN_COLUMN.name} = ${b.p(token)} WHERE session_id = ${b.p(sessionId)}`, b.values);
+            if (res.affected !== 1)
+                throw new Error(`deletion fence of session ${sessionId}: the token write matched ${res.affected} row(s) of a side-table row this transaction ensured under a held root-row lock — engine/driver anomaly, refusing to guess`);
+            await conn.commit();
+            return { token, incarnation: incarnationFromCell(sessionId, root.incarnation, "absent") };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    get size() {
+        return this.seat.size;
+    }
+    dispose() {
+        this.seat.dispose();
+    }
+    async listSessions(opts) {
+        return (await this.listSessionRows(opts)).map((a) => a.row);
+    }
+    async listSessionRows(opts) {
+        const dialect = this.db.dialect;
+        return this.selectListRows({
+            limit: opts.limit,
+            where: (p) => {
+                const where = ["sm.placement_kind IS NULL"];
+                if (opts.owner !== undefined)
+                    where.push(opts.includeUnowned ? `(sm.owner = ${p(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${p(opts.owner)}`);
+                if (opts.q) {
+                    const escape = dialect === "pg" ? "'\\'" : "'\\\\'";
+                    where.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${p(`%${escapeLike(opts.q)}%`)}) ESCAPE ${escape})`);
+                }
+                if (opts.cursor) {
+                    const at = new Date(opts.cursor.lastActivityAt);
+                    where.push(`(sm.updated_at < ${p(at)} OR (sm.updated_at = ${p(at)} AND sm.session_id < ${p(opts.cursor.sessionId)}))`);
+                }
+                return where;
+            },
+        });
+    }
+    async sessionSummaryOf(sessionId) {
+        return (await this.listRowOf(sessionId))?.row;
+    }
+    async listRowOf(sessionId) {
+        return (await this.selectListRows({ limit: 1, runSessionId: sessionId, where: (p) => ["sm.placement_kind IS NULL", `sm.session_id = ${p(sessionId)}`] }))[0];
+    }
+    async selectListRows(q) {
+        const dialect = this.db.dialect;
+        const b = binder(dialect);
+        const runWhere = () => (q.runSessionId !== undefined ? ` WHERE session_id = ${b.p(q.runSessionId)}` : "");
+        const runAnd = () => (q.runSessionId !== undefined ? ` AND session_id = ${b.p(q.runSessionId)}` : "");
+        const runCount = `LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run${runWhere()} GROUP BY session_id) r ON r.session_id = sm.session_id `;
+        const latest = dialect === "pg"
+            ? "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, status, task_id, result ->> 'runId' AS last_task_run_id FROM task_run" +
+                runWhere() +
+                "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.session_id = sm.session_id "
+            : "LEFT JOIN (SELECT session_id, status, task_id, last_task_run_id FROM (" +
+                "    SELECT session_id, status, task_id, JSON_UNQUOTE(JSON_EXTRACT(result, '$.runId')) AS last_task_run_id, " +
+                "      ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn FROM task_run" +
+                runWhere() +
+                "  ) lr WHERE rn = 1) latest ON latest.session_id = sm.session_id ";
+        const preview = dialect === "pg"
+            ? `LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview FROM task_run WHERE ${RUN_PREVIEW_PRESENT}` +
+                runAnd() +
+                "  ORDER BY session_id, created_at DESC, task_id DESC) pv ON pv.session_id = sm.session_id "
+            : "LEFT JOIN (SELECT session_id, objective_preview FROM (" +
+                "    SELECT session_id, objective_preview, ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY created_at DESC, task_id DESC) AS rn " +
+                `FROM task_run WHERE ${RUN_PREVIEW_PRESENT}` +
+                runAnd() +
+                "  ) pr WHERE rn = 1) pv ON pv.session_id = sm.session_id ";
+        const where = [...q.where(b.p), `se.${DELETING_TOKEN_COLUMN.name} IS NULL`];
+        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.forked_from, se.title, se.pinned, " +
+            "  COALESCE(r.run_count, 0) AS run_count, pv.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
+            "FROM session_meta sm " +
+            `LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id ` +
+            runCount +
+            latest +
+            preview +
+            "WHERE " + where.join(" AND ") + " " +
+            `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${b.p(q.limit)}`;
+        const rows = (await this.db.query(sql, b.values)).rows;
+        return rows.map((r) => {
+            const runId = r.last_task_run_id;
+            const sessionId = String(r.session_id);
+            const owner = r.owner ?? null;
+            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
+            const title = r.title ?? null;
+            const pinned = pinnedOf(dialect, r.pinned);
+            const row = {
+                sessionId,
+                owner,
+                lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
+                firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
+                runCount: Number(r.run_count),
+                objectivePreview: r.objective_preview ?? null,
+                lastStatus: r.status == null ? "" : String(r.status),
+                lastRunId: r.last_run_id ?? null,
+                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
+                title,
+                pinned,
+                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
+                ...listedLineageOf(sessionId, r.forked_from),
+            };
+            return { row, occupant: { owner, incarnation } };
+        });
+    }
+    async writeSessionRowCells(sessionId, cells, how) {
+        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
+    }
+    async probeTitle(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT se.title FROM session_meta sm LEFT JOIN ${SESSION_EXT_TABLE} se ON se.session_id = sm.session_id WHERE sm.session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        if (row === undefined)
+            return "none";
+        return row.title === null || row.title === undefined ? "untitled" : "titled";
+    }
+    async setTitleIfNull(sessionId, title) {
+        return withLockedSessionExt(this.db, sessionId, {}, async (query) => {
+            const b = binder(this.db.dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET title = ${b.p(title)} WHERE session_id = ${b.p(sessionId)} AND title IS NULL`, b.values)).affected > 0;
+        });
+    }
+    async readInstructionSource(sessionId) {
+        const b = binder(this.db.dialect);
+        const conn = await this.db.connect();
+        try {
+            const row = (await conn.query(`SELECT instruction_source FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values, BASELINE_STATEMENT)).rows[0];
+            return decodeInstructionSource(row?.instruction_source);
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async recordInstructionSource(sessionId, expected, source) {
+        const next = encodeInstructionSource(source);
+        await withLockedSessionExt(this.db, sessionId, { statement: BASELINE_STATEMENT }, async (query) => {
+            const b = binder(this.db.dialect);
+            const text = `UPDATE ${SESSION_EXT_TABLE} SET instruction_source = ${b.p(next)} WHERE session_id = ${b.p(sessionId)} AND ${expected.recorded ? `instruction_source = ${b.p(encodeInstructionSource(expected.source))}` : "instruction_source IS NULL"}`;
+            return (await query(text, b.values)).affected > 0;
+        });
+    }
+    async readSessionWorkspace(sessionId) {
+        const b = binder(this.db.dialect);
+        const row = (await this.db.query(`SELECT ${jsonColumnText(this.db.dialect, "workspace")} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${b.p(sessionId)}`, b.values)).rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        const dialect = this.db.dialect;
+        const cell = encodeSessionWorkspaceCell(workspace, dialect === "pg" ? pgSafeJsonStringify : JSON.stringify, sessionId);
+        await withLockedSessionExt(this.db, sessionId, { where: (p) => `incarnation = ${p(incarnation)}` }, async (query) => {
+            const b = binder(dialect);
+            return (await query(`UPDATE ${SESSION_EXT_TABLE} SET workspace = ${b.p(cell)}${dialect === "pg" ? "::jsonb" : ""} WHERE session_id = ${b.p(sessionId)}`, b.values)).affected > 0;
+        });
+    }
+}
+//# sourceMappingURL=session-store-sql.js.map

package/dist/plugins/session-withdraw-sql.d.ts

@@ -0,0 +1,36 @@
+/**
+ * **条件撤回的部署那一半**(SQL 两方言;规则在 `plugins/session-birth.ts` 头注)—— 会话店座(`stores-sql/tidb-session-store.ts` 的 `withdrawSessionOn`,
+ * PG 孪生同调)锁住根行、判完化身 / 内容 / 认领之后,在**同一事务、同一连接**上问部署:启用标记、客户端写计数、别的 run;放行 ⇒ 删本次 run 的部署行。
+ * 客户端写计数的 +1 也在这里一处:四个 SQL 写者里不在自己 UPDATE 里带它的那几个(导入、会话规则、附件绑定)调 {@link countClientWriteOn}。
+ * 每一读都是锁定读(`FOR UPDATE`;TiDB 悲观事务里普通 SELECT 读事务开始时的快照,看不到等根锁期间别人提交的写)。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+import type { WithdrawJudgeVerdict } from "../session-incarnation.js";
+/**
+ * 判据与计数句只用到的那一面:一句语句、交回行(会话店交给部署钩的事务语句面 `SessionTxStatements`、驱动的事务连接 `SqlTxConn` 都满足它 ——
+ * 结构型,本部署不读店目录里的型)。
+ */
+export interface WithdrawStatementFace {
+    query(sql: string, params?: unknown[]): Promise<{
+        readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+    }>;
+}
+/** 撤回出口的启用标记在标记表(`plugins/one-time-migration-marker.ts`)里的键 = 落它的一次性迁移(窗口见 `plugins/one-time-migrations.ts` 登记表 M43 行)。 */
+export declare const WITHDRAW_MARK_ID = "M43";
+/**
+ * 部署判据(一次提交的一只候选;`ownTaskId` = 本次提交认领赢的那条 run):
+ *  · 启用标记(M43)不在 ⇒ `upgrade_pending`(混跑窗里旧副本的写者不递增计数,判不出「没人写过」⇒ 一律留);
+ *  · 客户端写计数 > 0 ⇒ `client_writes`(先补旁表行再锁定读 —— 锁定读落在在的行上,见 `execution-placement-sql.ts` 的写序律);
+ *  · 本会话有本次 run 之外的 run 行 ⇒ `runs`;
+ *  · 放行 ⇒ 同一语句面上删本次 run 的部署行(账本事件 / 认领 / run 行)与本会话的续跑输入(别的 run 都不在 ⇒ 那一行只能是本次写的)。
+ */
+export declare function createSqlWithdrawJudge(dialect: SqlDialect, sessionId: string, ownTaskId: string | undefined): (tx: WithdrawStatementFace) => Promise<WithdrawJudgeVerdict>;
+/**
+ * 一次客户端写:补旁表行 + 锁定读在删令牌 + 计数 +1(调用方已在同一事务里锁住根行、根行在)。会话规则、附件绑定两个 SQL 写者调这一只(会话规则店收它作构造参数,组合座交入,店目录不读部署);
+ * 这只会话在删(会话三态,`src/session-deletion.ts`)⇒ 抛 `SessionDeletingError`,调用方的写不发生(删除级联的规则 / 附件腿之后到的写不复活它们;local 孪生 = 会话店 `withClientWrite` 的计数口同判)。
+ * 导入臂的旁表行已由锁它的那一读补过,只调计数那一句 {@link bumpClientWritesOn};标题 / 置顶的写者在自己的 UPDATE 里带 `BUMP_CLIENT_WRITES`(`session-row-sql.ts`)。
+ */
+export declare function countClientWriteOn(tx: WithdrawStatementFace, dialect: SqlDialect, sessionId: string): Promise<void>;
+/** 客户端写计数 +1 的那一句(前提:同一事务里根行已锁、旁表行已在)。 */
+export declare function bumpClientWritesOn(tx: WithdrawStatementFace, dialect: SqlDialect, sessionId: string): Promise<void>;
+//# sourceMappingURL=session-withdraw-sql.d.ts.map

package/dist/plugins/session-withdraw-sql.js

@@ -0,0 +1,42 @@
+import { BUMP_CLIENT_WRITES, ensureSessionExtRowStatement, readDeletingTokenOn, SESSION_EXT_TABLE } from "./session-ext-table.js";
+import { SessionDeletingError } from "../execution-placement.js";
+import { MIGRATION_MARKER_TABLE } from "./one-time-migration-marker.js";
+function placeholders(dialect, from, count) {
+    return Array.from({ length: count }, (_, i) => (dialect === "pg" ? `$${from + i}` : "?"));
+}
+export const WITHDRAW_MARK_ID = "M43";
+export function createSqlWithdrawJudge(dialect, sessionId, ownTaskId) {
+    const [p1, p2] = placeholders(dialect, 1, 2);
+    return async (tx) => {
+        const mark = await tx.query(`SELECT migration_id FROM ${MIGRATION_MARKER_TABLE} WHERE migration_id = ${p1}`, [WITHDRAW_MARK_ID]);
+        if (mark.rows.length === 0)
+            return { keep: "upgrade_pending" };
+        const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+        await tx.query(ensure.text, [...ensure.values]);
+        const ext = (await tx.query(`SELECT client_writes FROM ${SESSION_EXT_TABLE} WHERE session_id = ${p1} FOR UPDATE`, [sessionId])).rows[0];
+        if (Number(ext?.client_writes ?? 0) > 0)
+            return { keep: "client_writes" };
+        const others = ownTaskId === undefined
+            ? await tx.query(`SELECT task_id FROM task_run WHERE session_id = ${p1} LIMIT 1 FOR UPDATE`, [sessionId])
+            : await tx.query(`SELECT task_id FROM task_run WHERE session_id = ${p1} AND task_id <> ${p2} LIMIT 1 FOR UPDATE`, [sessionId, ownTaskId]);
+        if (others.rows.length > 0)
+            return { keep: "runs" };
+        if (ownTaskId !== undefined) {
+            await tx.query(`DELETE FROM task_event WHERE task_id = ${p1}`, [ownTaskId]);
+            await tx.query(`DELETE FROM task_active WHERE task_id = ${p1}`, [ownTaskId]);
+            await tx.query(`DELETE FROM task_run WHERE task_id = ${p1}`, [ownTaskId]);
+        }
+        await tx.query(`DELETE FROM checkpoint_ctx WHERE session_id = ${p1}`, [sessionId]);
+        return "proceed";
+    };
+}
+export async function countClientWriteOn(tx, dialect, sessionId) {
+    if ((await readDeletingTokenOn(async (sql, values) => (await tx.query(sql, [...values])).rows, dialect, sessionId)) !== null)
+        throw new SessionDeletingError(sessionId);
+    await bumpClientWritesOn(tx, dialect, sessionId);
+}
+export async function bumpClientWritesOn(tx, dialect, sessionId) {
+    const [p1] = placeholders(dialect, 1, 1);
+    await tx.query(`UPDATE ${SESSION_EXT_TABLE} SET ${BUMP_CLIENT_WRITES} WHERE session_id = ${p1}`, [sessionId]);
+}
+//# sourceMappingURL=session-withdraw-sql.js.map

package/dist/plugins/session-workspace-cell.d.ts

@@ -1,7 +1,7 @@
 import type { SessionWorkspace } from "../session-workspace.js";
 import { type JsonColumnReader } from "./sql-json-column.js";
-/** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
-export declare const SESSION_META_WORKSPACE_COLUMN: {
+/** 列定义的唯一属主(旁表建表句内插它,`session-ext-table.ts`)。 */
+export declare const SESSION_WORKSPACE_COLUMN: {
     readonly name: "workspace";
     readonly mysql: "workspace JSON NULL";
     readonly pg: "workspace JSONB";