@sema-agent/server 7.150.0 → 7.151.0

package/dist/plugins/serving-requirement.d.ts

@@ -2,25 +2,30 @@
  * **起服准入**(SQL 两方言;常设)—— 「这只库要求每一只服务者有哪些能力」一张表,与本构建的能力名单比:库上记着本构建没有的能力 ⇒ 拒启,本构建不迁移、不服务。
  *
  * ## 律
- *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 两词闭集
- *    {@link SERVING_REQUIREMENT_STATES}:`pending`(要求方已认领、还没做任何不兼容写)/ `in_force`(不兼容写已开始或已完成)。两态都要求;读出词表外的词 ⇒ 当作 `in_force`,拒句点名那一行。
+ *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 一词闭集
+ *    {@link SERVING_REQUIREMENT_STATES}:`in_force` = 一只带能力 M 的构建在这只库上放行了 M,M 的不兼容写已开始或马上开始。读出词表外的词(含 7.150.0 闭集里
+ *    从无写者的 `pending`)⇒ 当作 `in_force`,拒句点名那一行与原词。
  *  · 判据 = `knows(本构建, M)`(`knowsCapability`,与停-迁-起证据读法同一只谓词);发布线不进判据(同版本串的构建可以能力不同)。
  *  · 两次读,同一判据:SQL 一次性迁移段头、取迁移锁之前读一次(锁外预读);取到迁移锁之后、第一步迁移之前在锁连接上再读一次(锁内复核)——
  *    在本进程等锁时握着锁的那一只若写下了要求,锁内复核读得到。拒 ⇒ 本构建不迁移;库上只留本进程的登记行(段头第一步)。
  *  · 表不在(跳过了 `ensureSchema()` 的嵌入方)⇒ 拒:证不出「没有要求」不是「没有要求」。
- *  · 本构建不写本表(没有写者;写者随之后的停-迁-起迁移来)—— 表空 ⇒ 准入恒过。装早一版:从本版起的每一只构建都读它,之后写下的要求挡得住它们重启开服。
+ *  · 写者一只({@link recordServingRequirement}):每一条停-迁-起迁移(`stop-then-start.ts`;三类围栏同记)在守卫段放行之后、它**自己的**第一笔不兼容写之前,
+ *    在锁连接上落 `(M, in_force)`(缺席才落;已在的行 —— 含词表外的词 —— 一个字节不动)。只在还欠那一条的库上写(起过那一条的库不写)。
+ *    表空 ⇒ 准入恒过。7.150.0 起的每一只构建都读它,之后写下的要求挡得住缺这项能力的构建重启开服。
+ *  · 读法一只({@link unmetServingRequirements}):准入(非空即拒)与起服拒句的升级清单(点名本构建缺的在力能力)同读,不各写一句。
  *
  * ## 射程(如实)
  * 挡的是**起服者**:已在服务的副本不再读本表;准入与开服之间的停顿也不在它的射程里。早于本表那一版的构建不读本表。
  */
 import { StoreBootRefusalError } from "./store-contracts.js";
-import { type ReplicaRegistration } from "./replica-registration.js";
+import { type ReplicaCapability, type ReplicaRegistration } from "./replica-registration.js";
 import { type UnmetServingRequirement } from "./stop-then-start-sentence.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
 import type { SqlDialect, SqlExec } from "./sql-driver.js";
 /** 表名。 */
 export declare const SERVING_REQUIREMENT_TABLE = "serving_requirement";
-/** 要求行的状态词(闭集)。 */
-export declare const SERVING_REQUIREMENT_STATES: readonly ["pending", "in_force"];
+/** 要求行的状态词(闭集;一态 —— 本构建没有「认领了、还没写」的中间态:要求紧跟在本条第一笔不兼容写之前落)。 */
+export declare const SERVING_REQUIREMENT_STATES: readonly ["in_force"];
 export type ServingRequirementState = (typeof SERVING_REQUIREMENT_STATES)[number];
 /** 拒启码(确定的拒启表态;继承 {@link StoreBootRefusalError}:开库等待窗不重试、降级臂不吞)。 */
 export declare const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
@@ -44,6 +49,20 @@ export declare class ServingRequirementUnmetError extends StoreBootRefusalError
 }
 /** 准入读的两张表(本表与段头写的登记表)都在库里;不在 ⇒ 拒(`table_absent`),点名公开序列。 */
 export declare function assertReplicaTablesPresent(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration): Promise<void>;
-/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。纯读;两方言同一句(无占位符)。 */
+/**
+ * **要求的唯一读法**:库上记着、本构建(`me` 的能力名单)没有的那几行,按能力名排序。纯读;两方言同一句(无占位符,读口 = 列册对账同一只无参读口)。
+ * 读者两只:准入({@link assertServingRequirementsMet},非空即拒)与起服拒句的升级清单(`schema-consistency.ts` 的 `describeUpgradeChecklist`,点名这几项能力)。
+ */
+export declare function unmetServingRequirements(read: SchemaProbeRead, me: Pick<ReplicaRegistration, "capabilities">): Promise<readonly UnmetServingRequirement[]>;
+/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。读法 = {@link unmetServingRequirements}。 */
 export declare function assertServingRequirementsMet(db: SqlExec, me: ReplicaRegistration): Promise<void>;
+/**
+ * **要求的唯一写口**:一条停-迁-起迁移放行之后、它自己的第一笔不兼容写之前,在迁移段的锁连接上落 `(migrationId, in_force)`。缺席才落(MySQL 协议
+ * `ON DUPLICATE KEY UPDATE migration_id = migration_id` / PG `ON CONFLICT DO NOTHING`,与副本登记句同形):已在的行 —— 含手写的词表外词 —— 一个字节不动。
+ * 记下之后缺这项能力的构建起服即拒(准入);记下之后、那一笔写之前进程崩 ⇒ 行留着(保守:缺能力的构建拒启,带能力的构建下次起服照常续)。
+ * 读写权限 7.150.0 起已是部署前提(`docs/DEPLOY-PREREQS.md` 7.150.0 节)。`migrationId` 在型上就要在能力名单里。
+ */
+export declare function recordServingRequirement(db: {
+    exec(sql: string, params?: readonly unknown[]): Promise<number>;
+}, dialect: SqlDialect, migrationId: ReplicaCapability, nowMs: number): Promise<void>;
 //# sourceMappingURL=serving-requirement.d.ts.map

package/dist/plugins/serving-requirement.js

@@ -2,7 +2,7 @@ import { StoreBootRefusalError } from "./store-contracts.js";
 import { REPLICA_REGISTRATION_TABLE, knowsCapability } from "./replica-registration.js";
 import { servingRequirementUnmetSentence } from "./stop-then-start-sentence.js";
 export const SERVING_REQUIREMENT_TABLE = "serving_requirement";
-export const SERVING_REQUIREMENT_STATES = ["pending", "in_force"];
+export const SERVING_REQUIREMENT_STATES = ["in_force"];
 export const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
 export function servingRequirementDdl(dialect) {
     return dialect === "mysql"
@@ -37,17 +37,24 @@ function stateOf(cell) {
     const word = String(cell);
     return SERVING_REQUIREMENT_STATES.includes(word) ? { state: word, word } : { state: "in_force", word };
 }
-export async function assertServingRequirementsMet(db, me) {
-    const { rows } = await db.query(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`);
+export async function unmetServingRequirements(read, me) {
     const unmet = [];
-    for (const r of rows) {
+    for (const r of await read(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`)) {
         const migration = String(r["migration_id"]);
         if (knowsCapability(me.capabilities, migration))
             continue;
         const { state, word } = stateOf(r["state"]);
         unmet.push({ migration, state, word });
     }
+    return unmet;
+}
+export async function assertServingRequirementsMet(db, me) {
+    const unmet = await unmetServingRequirements(async (sql) => (await db.query(sql)).rows, me);
     if (unmet.length > 0)
         throw new ServingRequirementUnmetError("capability_missing", unmet, [], me.releaseLine);
 }
+export async function recordServingRequirement(db, dialect, migrationId, nowMs) {
+    const insert = `INSERT INTO ${SERVING_REQUIREMENT_TABLE} (migration_id, state, required_at_ms) VALUES (${dialect === "mysql" ? "?, 'in_force', ?" : "$1, 'in_force', $2"})`;
+    await db.exec(dialect === "mysql" ? `${insert} ON DUPLICATE KEY UPDATE migration_id = migration_id` : `${insert} ON CONFLICT (migration_id) DO NOTHING`, [migrationId, nowMs]);
+}
 //# sourceMappingURL=serving-requirement.js.map

package/dist/plugins/session-birth.d.ts

@@ -14,10 +14,14 @@
  * (TiDB 悲观事务里普通 SELECT 读的是事务开始时的快照,看不到等锁期间提交的写;两方言一律 `FOR UPDATE`)。
  */
 import type { SessionTreeEntry } from "@sema-agent/core";
+import type { SessionKind } from "../session-kind.js";
 import type { RegisterReceipt, SessionBirth, WithdrawOutcome } from "../session-incarnation.js";
-/** 出生回执面(会话店的窄面;`register` 的同笔写形)。 */
+/**
+ * 出生回执面(会话店的窄面;`register` 的同笔写形)。`kind` = 这只会话的种类(律 `session-kind.ts`):**只在这一笔真建了新行时**写下,写在建行的同一笔里
+ * (SQL = 建行事务里的建行钩;local = 建行那一笔格写);已在的行 ⇒ 零写(种类终身不改)。缺席 = 顶层对话,逐字今形。
+ */
 export interface SessionBirthFace {
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: SessionKind): Promise<RegisterReceipt>;
 }
 /** 条件撤回面(会话店的窄面;部署装配在店上,一只事务里判完、删完)。`ownTaskId` = 本次提交认领赢的那条 run(没有 ⇒ 缺)。 */
 export interface SessionWithdrawFace {

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

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const SESSION_CAPTURE_OPTOUT_TABLE = "session_capture_optout";
 const UNREADABLE_RECORD_REASON = "capture opt-out record present but unreadable (kept fail-closed)";
 export const SESSION_CAPTURE_KEY_WIDTH = 255;
@@ -81,6 +82,7 @@ export class SqlSessionCaptureRecordStore {
         return out;
     }
 }
+sealStoreClass(SqlSessionCaptureRecordStore, "sql-session-capture-record-store", { mark: "exit", read: "exit", list: "exit" });
 export class TiDBSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
     constructor(pool) {
         super(mysqlDriver(pool), "mysql");

package/dist/plugins/session-ext-table.d.ts

@@ -1,5 +1,6 @@
 import { StoreBootRefusalError } from "./store-contracts.js";
 import type { SqlDialect, SqlDriver } from "./sql-driver.js";
+import type { IndexSpec } from "./ensure-index.js";
 /** 表名(建表句、语句模块、迁移同读)。 */
 export declare const SESSION_EXT_TABLE = "session_ext";
 /** 一列:名字 + 两方言定义。 */
@@ -27,8 +28,20 @@ export declare const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
  * 在删对删除门之外的一切读者与写者读作「行不在」(头读 / 列表 / 规则 L 的认领);存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`。
  */
 export declare const DELETING_TOKEN_COLUMN: SessionExtColumn;
-/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格与在删令牌不在 `session_meta` 上出现过,不搬)。 */
+/**
+ * **会话种类**(律 `src/session-kind.ts`):`NULL` = 顶层对话(存量行与老壳建的行恒为 NULL —— 无回填、无一次性迁移);非空 = 闭集里的一个词。
+ * 唯一写者 = 建行事务里的建行钩(`plugins/session-store-sql.ts` 的 `birth.record`,本事务刚建下的这一行);此后无写口(终身不改)。宽度 32 = 词表的余量。
+ * 存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`(中央建表句生成)。
+ */
+export declare const SESSION_KIND_COLUMN: SessionExtColumn;
+/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格、在删令牌与种类不在 `session_meta` 上出现过,不搬)。 */
 export declare const SESSION_EXT_COLUMNS: readonly SessionExtColumn[];
+/**
+ * 本表的索引声明(两方言共用一份;MySQL 协议方言另以内联 `KEY` 随建表句到货,存量库缺谁补谁 —— `ensure-index.ts`):种类那一列给老化候选面
+ * (`listIdleOfKind`:只读带种类的行,不扫整表)。
+ */
+export declare const SESSION_EXT_KIND_INDEX = "idx_session_ext_kind";
+export declare const SESSION_EXT_INDEXES: readonly IndexSpec[];
 /** M41 从 `session_meta` 搬进本表的那一组(计数格之前的全部格)。 */
 export declare const SESSION_EXT_MOVED_COLUMNS: readonly SessionExtColumn[];
 /** 外键约束名(两方言同名;起服探针与迁移的后置条件按名读)。 */

package/dist/plugins/session-ext-table.js

@@ -22,7 +22,10 @@ const PRODUCT_COLUMNS = [
 export const CLIENT_WRITES_COLUMN = { name: "client_writes", mysql: "client_writes BIGINT NOT NULL DEFAULT 0", pg: "client_writes BIGINT NOT NULL DEFAULT 0" };
 export const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
 export const DELETING_TOKEN_COLUMN = { name: "deleting_token", mysql: "deleting_token VARCHAR(36) NULL", pg: `deleting_token VARCHAR(36) COLLATE "C"` };
-export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS, CLIENT_WRITES_COLUMN, DELETING_TOKEN_COLUMN];
+export const SESSION_KIND_COLUMN = { name: "session_kind", mysql: "session_kind VARCHAR(32) NULL", pg: `session_kind VARCHAR(32) COLLATE "C"` };
+export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS, CLIENT_WRITES_COLUMN, DELETING_TOKEN_COLUMN, SESSION_KIND_COLUMN];
+export const SESSION_EXT_KIND_INDEX = "idx_session_ext_kind";
+export const SESSION_EXT_INDEXES = [{ table: SESSION_EXT_TABLE, name: SESSION_EXT_KIND_INDEX, columns: [SESSION_KIND_COLUMN.name] }];
 export const SESSION_EXT_MOVED_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_COLUMNS];
 export const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
 export const SESSION_META_KEY_COLLATION_PROBE = "SELECT CHARACTER_SET_NAME AS cs, COLLATION_NAME AS coll FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'session_meta' AND COLUMN_NAME = 'session_id'";
@@ -43,6 +46,7 @@ export function sessionExtDdl(dialect, referenced) {
         `     ${key},\n` +
         SESSION_EXT_COLUMNS.map((c) => `     ${c[dialect]},\n`).join("") +
         "     PRIMARY KEY (session_id),\n" +
+        (dialect === "mysql" ? SESSION_EXT_INDEXES.map((i) => `     KEY ${i.name} (${i.columns.join(", ")}),\n`).join("") : "") +
         `     CONSTRAINT ${SESSION_EXT_FOREIGN_KEY} FOREIGN KEY (session_id) REFERENCES session_meta (session_id) ON DELETE CASCADE\n` +
         (dialect === "pg" ? "   )" : "   ) COLLATE utf8mb4_bin"));
 }

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

@@ -23,9 +23,56 @@
  *       之后这一行连同标题换了主 —— 是行的历史,不是越权写。
  * 应答不在事务内读(理由见上),所以③这一窗在;不取「事务内应答」。
  * 全局锁序:根 `session_meta` 一行 → 它的旁表行(→ 读日志 mark 时它的末条事件),不碰 `task_*`(与旁表的每个写者同序:根行先)。
+ *
+ * ## 「锁根行读住客」只有一句({@link lockSessionRootOn})
+ * 部署侧(本目录之外的 `src/stores-sql/**` 不在射程)每一个先锁根 `session_meta` 行再判 / 写的写事务都经它:行格写原语与落定段({@link lockSessionRowOn})、
+ * 执行席的写序律 ①(`execution-placement-sql.ts`)、旁表格写(`session-store-sql.ts` 的 `withLockedSessionExt`)。选择列是它们要的并集(属主 · 化身 · 委派判别位 · 叶序 · 最后活动 —— 最后一格是删除围栏的老化重判读的),
+ * 各读者按自己的读法解码同一行。
+ *
+ * ## 落定段({@link withLandedRow};律在 `landed-attendants.ts` 头注)
+ * 一只事务:{@link lockSessionRowOn}(锁根行 → 补旁表行 → 锁读格与在删令牌)→ 判官 `judgeLandedRow`(就是 `judgeSessionRowWrite` 的 `replay` 写者:行在 ∧ 非在删 ∧
+ * 非委派分区 ∧ 属主与化身整对同)→ 是 ⇒ 段体在**同一连接、同一事务**里跑各店的语句源 → 提交;不是 ⇒ 回滚、一个字节不写。死锁受害 / 仲裁输了
+ * (`SqlArbitrationLostError`:文件历史哨兵消失等)⇒ 从**段首**重来(含锁根行与判,经仓里唯一的 `retryOnDeadlock`)—— 段内不许有自己回滚重开事务的语句源。
+ */
+import type { SqlDialect, SqlDriver, SqlTxConn } from "./sql-driver.js";
+import type { SessionLogMark } from "@sema-agent/core";
+import { type SessionFace } from "../session-incarnation.js";
+import { type LockedSessionRow, type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome, type LandedOutcome } from "../session-row.js";
+/** 一条连接上的行读口(本事务的语句面:SQL 文本 + 参数 → 行)—— `SqlTxConn` / mysql2 连接 / node-pg 客户端各包一行即得。 */
+export type SessionRootRowsOn = (text: string, values: readonly unknown[]) => Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+/** `SqlTxConn` 的行读口。 */
+export declare function rootRowsOnTx(conn: Pick<SqlTxConn, "query">): SessionRootRowsOn;
+/**
+ * **锁根行读住客 —— 唯一一句**(头注):同一连接上 `SELECT owner, incarnation, placement_kind, leaf_seq, updated_at FROM session_meta WHERE session_id = ? FOR UPDATE`。
+ * 行不在 ⇒ `undefined`(InnoDB 可重复读下锁一只不在的键取间隙锁 —— 挡住同 id 的并发登记到本事务结束,调用方随即回滚)。读者各自解码五格。
+ */
+export declare function lockSessionRootOn(conn: SessionRootRowsOn, dialect: SqlDialect, sessionId: string): Promise<Readonly<Record<string, unknown>> | undefined>;
+/**
+ * 会话根行的部署格(SQL 会话规则店的构造参数,组合座 `store-backend.ts` 交入;店目录不认识根行与旁表,R8):`lockRoot` = 上面那一句(行在不在),
+ * `countClientWrite` = 客户端写计数的唯一一处(`session-withdraw-sql.ts`)。形由规则店的 `SessionRootSeat` 型在组合座上结构核对。
+ */
+export declare const SQL_SESSION_ROOT_SEAT: {
+    readonly lockRoot: (conn: Pick<SqlTxConn, "query">, dialect: SqlDialect, sessionId: string) => Promise<boolean>;
+    readonly countClientWrite: (conn: SqlTxConn, dialect: SqlDialect, sessionId: string) => Promise<void>;
+};
+/**
+ * 写原语与落定段的**同一前缀**(头注 ①):锁根行({@link lockSessionRootOn})→ 行在 ⇒ 写序律:先补旁表行、再锁定读它的格与在删令牌(锁定读永远落在一行在的记录上 ——
+ * InnoDB 间隙锁死锁,见 `execution-placement-sql.ts` 的 readCellOn;锁定读 = 最新已提交)→ 判官吃的形;`logMark` ⇒ 同锁下读日志的 mark。行不在 ⇒ `locked: undefined`。
+ */
+export declare function lockSessionRowOn(conn: SqlTxConn, dialect: SqlDialect, sessionId: string, opts: {
+    readonly logMark: boolean;
+}): Promise<{
+    readonly locked: LockedSessionRow | undefined;
+    readonly mark?: SessionLogMark;
+}>;
+/**
+ * **落定段**(头注「落定段」):一只事务里锁根行判住客(`landed` = 提交回执交回的那一位 / identical 臂门读的那一位 / 运行腿受理时见证的那一位 / 路由门读的那一位)→
+ * 是那一位 ⇒ `body(本事务连接)` → 提交 ⇒ `{ landed: true, value }`;不是 ⇒ 回滚 ⇒ `{ landed: false }`(一个字节没写)。`body` 抛 ⇒ 回滚、原样上抛(段体自己的拒,
+ * 例:规则收紧门)。死锁受害 / 仲裁输了 / `alsoRetry` 认的错 ⇒ 从段首整段重来(重来同样重锁、重判)。
  */
-import type { SqlDriver } from "./sql-driver.js";
-import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type SessionRowWriteOutcome } from "../session-row.js";
+export declare function withLandedRow<T>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, landed: SessionFace, body: (tx: SqlTxConn) => Promise<T>, opts?: {
+    readonly alsoRetry?: (err: unknown) => boolean;
+}): Promise<LandedOutcome<T>>;
 /**
  * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
  * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。

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

@@ -1,6 +1,8 @@
-import { BUMP_CLIENT_WRITES, SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
+import { BUMP_CLIENT_WRITES, DELETING_TOKEN_COLUMN, SESSION_EXT_TABLE, ensureSessionExtRowStatement } from "./session-ext-table.js";
 import { incarnationFromCell } from "../session-incarnation.js";
-import { judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
+import { retryOnDeadlock } from "./sql-errors.js";
+import { countClientWriteOn } from "./session-withdraw-sql.js";
+import { judgeLandedRow, judgeSessionRowWrite, settleSessionRowWrite, } from "../session-row.js";
 function binder(dialect) {
     const values = [];
     return {
@@ -11,11 +13,27 @@ function binder(dialect) {
         },
     };
 }
+export function rootRowsOnTx(conn) {
+    return async (text, values) => (await conn.query(text, [...values])).rows;
+}
+export async function lockSessionRootOn(conn, dialect, sessionId) {
+    return (await conn(`SELECT owner, incarnation, placement_kind, leaf_seq, updated_at FROM session_meta WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+}
+export const SQL_SESSION_ROOT_SEAT = {
+    async lockRoot(conn, dialect, sessionId) {
+        return (await lockSessionRootOn(rootRowsOnTx(conn), dialect, sessionId)) !== undefined;
+    },
+    async countClientWrite(conn, dialect, sessionId) {
+        await countClientWriteOn(conn, dialect, sessionId);
+    },
+};
 function lockedRowFrom(dialect, sessionId, row, ext) {
+    const token = ext?.[DELETING_TOKEN_COLUMN.name];
     return {
         owner: row.owner === null || row.owner === undefined ? null : String(row.owner),
         incarnation: incarnationFromCell(sessionId, row.incarnation, "absent"),
         placed: row.placement_kind !== null && row.placement_kind !== undefined,
+        deleting: token !== null && token !== undefined,
         mirror: ext?.execution_role === "mirror",
         cells: {
             title: ext?.title === null || ext?.title === undefined ? null : String(ext.title),
@@ -23,6 +41,40 @@ function lockedRowFrom(dialect, sessionId, row, ext) {
         },
     };
 }
+export async function lockSessionRowOn(conn, dialect, sessionId, opts) {
+    const root = await lockSessionRootOn(rootRowsOnTx(conn), dialect, sessionId);
+    if (root === undefined)
+        return { locked: undefined };
+    const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+    await conn.query(ensure.text, [...ensure.values]);
+    const extRead = binder(dialect);
+    const ext = (await conn.query(`SELECT execution_role, title, pinned, ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${extRead.p(sessionId)} FOR UPDATE`, extRead.values)).rows[0];
+    const locked = lockedRowFrom(dialect, sessionId, root, ext);
+    return opts.logMark ? { locked, mark: await lockedLogMark(conn, dialect, sessionId, root.leaf_seq) } : { locked };
+}
+export async function withLandedRow(db, sessionId, landed, body, opts) {
+    return retryOnDeadlock(db.dialect, async () => {
+        const conn = await db.connect();
+        try {
+            await conn.begin();
+            const { locked } = await lockSessionRowOn(conn, db.dialect, sessionId, { logMark: false });
+            if (!judgeLandedRow(sessionId, landed, locked)) {
+                await conn.rollback();
+                return { landed: false };
+            }
+            const value = await body(conn);
+            await conn.commit();
+            return { landed: true, value };
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }, opts?.alsoRetry);
+}
 async function lockedLogMark(conn, dialect, sessionId, leafSeq) {
     const b = binder(dialect);
     const last = await conn.query(`SELECT entry_id FROM session_event WHERE session_id = ${b.p(sessionId)} ORDER BY seq DESC LIMIT 1 FOR UPDATE`, b.values);
@@ -35,17 +87,8 @@ export async function writeSessionRowCellsSql(db, sessionId, cells, how, readAns
     const conn = await db.connect();
     try {
         await conn.begin();
-        const read = binder(dialect);
-        const locked = (await conn.query(`SELECT owner, incarnation, placement_kind, leaf_seq FROM session_meta WHERE session_id = ${read.p(sessionId)} FOR UPDATE`, read.values)).rows[0];
-        const extRead = binder(dialect);
-        let ext;
-        if (locked !== undefined) {
-            const ensure = ensureSessionExtRowStatement(dialect, sessionId);
-            await conn.query(ensure.text, [...ensure.values]);
-            ext = (await conn.query(`SELECT execution_role, title, pinned FROM ${SESSION_EXT_TABLE} WHERE session_id = ${extRead.p(sessionId)} FOR UPDATE`, extRead.values)).rows[0];
-        }
-        const mark = how.row.log === undefined || locked === undefined ? undefined : await lockedLogMark(conn, dialect, sessionId, locked.leaf_seq);
-        verdict = judgeSessionRowWrite(sessionId, how, locked === undefined ? undefined : lockedRowFrom(dialect, sessionId, locked, ext), () => {
+        const { locked, mark } = await lockSessionRowOn(conn, dialect, sessionId, { logMark: how.row.log !== undefined });
+        verdict = judgeSessionRowWrite(sessionId, how, locked, () => {
             if (mark === undefined)
                 throw new Error(`writeSessionRowCellsSql: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
             return mark;

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

@@ -21,26 +21,18 @@ import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type Ses
 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 IdleSession, type IdleSessionCursor, type SessionKind, type SessionKindReading } from "../session-kind.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 RegisterReceipt, type SessionBirth, type SessionFace, 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 { SessionListQuery, 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;
-}
+/** 列表面的查询(`OwnerAwareSessionStore.listSessions` 的入参形;三店同一形)。 */
+export type SessionListOptions = SessionListQuery;
 /**
  * 会话店的事务内钩(座锁住根行之后、写之前调;同一事务、同一连接):
  *  · 四个词同一只判官 {@link judgeSessionWrite}(local 店的写锁内同调这一只):`erase` 只判这一行的在删令牌(不是 ⇒ 拒 `SessionDeletionSupersededError`);其余认领在 ⇒ 拒 `SessionActiveRunError`;
@@ -49,6 +41,11 @@ export interface SessionListOptions {
  *  · 键控 fork(服务扩展)—— `record`:新行的 fork 键落旁表(新行是本事务刚插下的,本事务持着它的锁);`targetOf`:撞上已在的目标时的一次池读(属主 + fork 键)。
  */
 export declare function createSqlSessionWriteHooks(db: Pick<SqlDriver, "dialect" | "query">): SessionWriteHooks;
+/**
+ * 🔴 **视图谓词的 SQL 一句**(两方言同一函数;列表 lister 与老化候选面同调 —— local 店的同一判是 `session-kind.ts` 的 `sessionKindListed`):
+ * 缺省视图(`view` 缺席)⇒ 只有无种类的行;`view` 在场 ⇒ 恰那一种。`se` = 旁表 `session_ext` 的别名(LEFT JOIN:旁表行不在 = 无种类)。
+ */
+export declare function sessionKindSql(view: SessionKind | undefined, p: (v: unknown) => string): string;
 export declare class SqlSessionStore implements SessionStore {
     private readonly db;
     /** 座(引擎座表的唯一写者)。 */
@@ -63,8 +60,10 @@ export declare class SqlSessionStore implements SessionStore {
     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>;
+    /** 出生回执面(座逐字转发,种类一并转 —— 漏一层 = 种类在 SQL 上静默丢;`plugins/session-birth.ts`)。 */
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: SessionKind): Promise<RegisterReceipt>;
+    /** 按 id 的种类读(`session-kind.ts` 的 `SessionKindFace`):一条 PK SELECT —— 根行的化身 + 旁表的种类(同一次读;旁表行不在 = 无种类)。不在 ⇒ `undefined`。 */
+    sessionKindOf(sessionId: string): Promise<SessionKindReading | undefined>;
     /** 条件撤回面:座的条件删除 + 本部署的判据(启用标记 / 客户端写计数 / 别的 run / 本次 run 的部署行;同一事务)。 */
     withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
@@ -99,6 +98,22 @@ export declare class SqlSessionStore implements SessionStore {
      * 写序与旁表的其余格写者同一条(根行 → 旁表;根行先 ⇒ 与认领事务、座的删除 / 导入同一锁序)。
      */
     private fenceDeletion;
+    /**
+     * 老化条件的锁内判({@link SessionAgeOutExpectation};调用方持根行锁、旁表行已补并锁定 —— `readDeletingTokenOn` 之后):住客仍是候选那一位 ∧ 最后活动仍早于视界
+     * ∧ 种类仍是它 ∧ 当下无活引用(与托管留存同一只谓词;认领那一腿随后由围栏自己的判官再判一次,结局 `active`)。
+     * **全部是当前读**:住客与最后活动来自根行的锁定读;种类与活引用两读也带 `FOR UPDATE` —— MySQL 协议的可重复读下普通 SELECT 读的是一份快照(TiDB:事务起点的快照),
+     * 等根行锁期间别的事务提交的待决检查点 / 子代 / workflow 行会被它漏掉;锁定读读最新提交(与托管留存执行器的候选锁读同一形)。
+     */
+    private ageOutHoldsOn;
+    /**
+     * 老化候选面(`OwnerAwareSessionStore.listIdleOfKind`;律 `src/session-kind.ts`):`session_meta` JOIN 旁表 —— 视图谓词同一只片段({@link sessionKindSql})∧ 最后活动早于视界
+     * ∧ 当下无活引用(与托管留存同一只谓词),**在删的行也交**(一次失败的自动删除撂下的在删行,两只 lister 都读不到它 —— 交给围栏:持有者已死 ⇒ 接管收完)。
+     * 最老先出,`(updated_at, session_id)` 升序 keyset 续页;走 `idx_session_ext_kind`。每读带语句期限(过期 ⇒ 这一句自己拒,调用方本拍停、下拍再来)。
+     */
+    listIdleOfKind(kind: SessionKind, idleBefore: Date, page: {
+        readonly after?: IdleSessionCursor;
+        readonly limit: number;
+    }): Promise<IdleSession[]>;
     get size(): number;
     dispose(): void;
     /**
@@ -135,9 +150,10 @@ export declare class SqlSessionStore implements SessionStore {
     /** 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>;
+    /** 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`)
+     *  AND the session row is still `landed` (the occupant the titler read at acceptance) — judged in the landed section (`withLandedRow`: lock the root row,
+     *  the row-write judge). Returns whether this call set it. No session row / another occupant / being deleted ⇒ `false`, zero bytes. */
+    setTitleIfNull(sessionId: string, title: string, landed: SessionFace): Promise<boolean>;
     /** 换源通告的基线读(一行 PK 读;列的三态读法见 `instruction-source-notice.ts`)。旁表行不在 ⇒ 读作「没记过」。语句期限 {@link BASELINE_IO_DEADLINE_MS}(过期 ⇒ 查询自己拒、连接销毁)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**