@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/schema-live-columns.js

@@ -1,8 +1,8 @@
 export async function readLiveColumns(read, dialect) {
     const live = new Map();
     if (dialect !== "pg") {
-        for (const row of await read("SELECT table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = DATABASE()")) {
-            addColumn(live, row["t"], row["c"], "fold");
+        for (const row of await read("SELECT table_name AS t, column_name AS c, is_nullable AS n FROM information_schema.columns WHERE table_schema = DATABASE()")) {
+            addColumn(live, row["t"], row["c"], row["n"], "fold");
         }
         return live;
     }
@@ -13,7 +13,7 @@ export async function readLiveColumns(read, dialect) {
             order.set(s, Number(row["ord"]));
     }
     const winner = new Map();
-    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
+    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c, is_nullable AS n FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
         const t = String(row["t"] ?? "");
         const rank = order.get(String(row["s"] ?? "")) ?? Number.MAX_SAFE_INTEGER;
         const held = winner.get(t);
@@ -23,20 +23,20 @@ export async function readLiveColumns(read, dialect) {
             winner.set(t, rank);
             live.delete(t);
         }
-        addColumn(live, t, row["c"], "verbatim");
+        addColumn(live, t, row["c"], row["n"], "verbatim");
     }
     return live;
 }
-function addColumn(live, table, column, mode) {
+function addColumn(live, table, column, isNullable, mode) {
     const t = mode === "fold" ? String(table ?? "").toLowerCase() : String(table ?? "");
     const c = mode === "fold" ? String(column ?? "").toLowerCase() : String(column ?? "");
     if (t === "" || c === "")
         return;
-    let set = live.get(t);
-    if (set === undefined) {
-        set = new Set();
-        live.set(t, set);
+    let columns = live.get(t);
+    if (columns === undefined) {
+        columns = new Map();
+        live.set(t, columns);
     }
-    set.add(c);
+    columns.set(c, { nullable: String(isNullable ?? "").toUpperCase() === "YES" });
 }
 //# sourceMappingURL=schema-live-columns.js.map

package/dist/plugins/send-user-file.js

@@ -3,6 +3,7 @@ import { uuidv7 } from "@sema-agent/core";
 import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
+import { createEgressFetch } from "../egress-redirect.js";
 export const PRESIGN_MAX_TTL_SEC = 604_800;
 export function scopeSegment(secretKey, scope) {
     if (scope === undefined || scope === "")
@@ -27,7 +28,7 @@ export function sanitizeSendFileName(name) {
     return clean.length > 0 ? clean : "file";
 }
 export function createSendUserFileIssuer(cfg, deps) {
-    const f = deps?.fetchImpl ?? fetch;
+    const f = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", deps?.fetchImpl);
     const bounded = () => ({ signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
     const upload = deps?.upload ??
         (async (bucket, key, bytes) => {

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

@@ -0,0 +1,37 @@
+/**
+ * **会话的出生回执与条件撤回** —— 会话店交给提交出口(`src/submission-exit.ts`)的两张窄面。引擎的 `SessionStore` 接口一个字节不动
+ * (`register(): Promise<void>` 照旧);本服务的店在它旁边各多一只方法,包装 / 转发层逐个转发。
+ *
+ * ## 出生回执({@link SessionBirthFace.registerWithReceipt})
+ * 与 `register` 同一笔写、同一条首写律;**只有这一笔真建了新行**时交回候选化身({@link SessionBirth}:这一次 INSERT 的入参里铸的那一只,
+ * 不是登记之后的复读)。已在的行、并发登记里输的那一只 ⇒ 不交候选。出生事实不在这里判:撤回事务锁住根行之后读到的
+ * 化身**等于**候选,才是「这一次提交铸下了这只会话」(两只同属主的并发登记只有赢家的候选进了行)。
+ *
+ * ## 条件撤回({@link SessionWithdrawFace.withdrawBirth})
+ * 一只事务 / 一把根锁里:锁根行 → 行不在 ⇒ `absent`;化身或属主不是候选那一位 ⇒ `incarnation` → 有可撤集合之外的会话条目 ⇒ `content`
+ * → 认领在(判官 `judgeSessionWrite` 的 `delete` 臂)⇒ `claim` → 客户端写过(计数 > 0)⇒ `client_writes` → 有本次 run 之外的 run 行 ⇒ `runs`
+ * → 撤回出口还没启用(一次性迁移的标记未落)⇒ `upgrade_pending` → 否则删本次 run 的部署行 + 会话行(旁表随外键级联)。每一读都是**锁定读**
+ * (TiDB 悲观事务里普通 SELECT 读的是事务开始时的快照,看不到等锁期间提交的写;两方言一律 `FOR UPDATE`)。
+ */
+import type { SessionTreeEntry } from "@sema-agent/core";
+import type { RegisterReceipt, SessionBirth, WithdrawOutcome } from "../session-incarnation.js";
+/** 出生回执面(会话店的窄面;`register` 的同笔写形)。 */
+export interface SessionBirthFace {
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+}
+/** 条件撤回面(会话店的窄面;部署装配在店上,一只事务里判完、删完)。`ownTaskId` = 本次提交认领赢的那条 run(没有 ⇒ 缺)。 */
+export interface SessionWithdrawFace {
+    withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
+}
+/** 店上的出生回执面(没有 ⇒ `undefined`:登记照走 `register`,不交候选 ⇒ 这只会话永不撤回)。 */
+export declare function birthFaceOf(store: unknown): SessionBirthFace | undefined;
+/** 店上的条件撤回面(没有 ⇒ `undefined`:候选不交给出口 ⇒ 永不撤回)。 */
+export declare function withdrawFaceOf(store: unknown): SessionWithdrawFace | undefined;
+/**
+ * 可撤集合的 A 组:引擎在受理之前 / 收尾时写下的记账条目(不进模型上下文的那些型)。引擎的条目型闭集逐型判 —— 引擎加一型 ⇒ 这里编译红,
+ * 新型归哪一边由人定。`false` 的五型(消息 / 会进上下文的自定义消息 / 压缩 / 标签 / 会话信息)= 内容:有一条 ⇒ 留(`content`)。
+ */
+export declare function entryTypeWithdrawable(type: SessionTreeEntry["type"]): boolean;
+/** A 组的型名单(SQL 锁定读的 `NOT IN` 参数;由 {@link entryTypeWithdrawable} 派生,不手写第二份)。 */
+export declare const WITHDRAWABLE_ENTRY_TYPES: readonly SessionTreeEntry["type"][];
+//# sourceMappingURL=session-birth.d.ts.map

package/dist/plugins/session-birth.js

@@ -0,0 +1,38 @@
+export function birthFaceOf(store) {
+    const s = store;
+    return typeof s?.registerWithReceipt === "function" ? { registerWithReceipt: s.registerWithReceipt.bind(s) } : undefined;
+}
+export function withdrawFaceOf(store) {
+    const s = store;
+    return typeof s?.withdrawBirth === "function" ? { withdrawBirth: s.withdrawBirth.bind(s) } : undefined;
+}
+export function entryTypeWithdrawable(type) {
+    switch (type) {
+        case "thinking_level_change":
+        case "model_change":
+        case "custom":
+        case "leaf":
+        case "prompt_epoch":
+        case "announced_listing":
+        case "git_announcement":
+        case "workspace_state":
+        case "session_checkout":
+        case "reminder_mark":
+            return true;
+        case "message":
+        case "custom_message":
+        case "compaction":
+        case "label":
+        case "session_info":
+            return false;
+        default: {
+            const unknownType = type;
+            throw new Error(`entryTypeWithdrawable: no entry type ${JSON.stringify(unknownType)}`);
+        }
+    }
+}
+export const WITHDRAWABLE_ENTRY_TYPES = [
+    "message", "thinking_level_change", "model_change", "compaction", "custom", "custom_message", "label", "session_info",
+    "leaf", "prompt_epoch", "announced_listing", "git_announcement", "workspace_state", "session_checkout", "reminder_mark",
+].filter(entryTypeWithdrawable);
+//# sourceMappingURL=session-birth.js.map

package/dist/plugins/session-epoch-anchor.d.ts

@@ -10,30 +10,58 @@
  * storage for the nearest carrier BELOW the floor and reads it itself. The storage returns that record **as stored**:
  *  · a `prompt_epoch` entry ⇒ the whole entry (the engine's branch walk reads the whole entry too);
  *  · a compaction whose `details.promptEpoch` is present ⇒ that restatement;
- *  · a compaction without a restatement carries nothing ⇒ the scan pages past it, to exhaustion (a session that lived
+ *  · a compaction without a restatement carries nothing ⇒ the scan walks past it, to exhaustion (a session that lived
  *    across the release that introduced epochs can hold any number of them between the floor and its pin).
  * The storage never judges the record's shape. The engine answers a current-shape record as a pin and a retired-shape
  * record by name (`legacy`, with whether it pinned a center artifact) — a storage that normalized the record first would
  * turn a session pinned under a retired shape into one with no pin, and the engine would then skip the center source's
  * handling of that pin. A record that is neither is the engine's to read as well (it reads as no record).
  *
- * `floorSeq <= 0` (a full load: the walk already reaches the root) or no carrier below the floor ⇒ `undefined`
- * (a session that predates epochs).
+ * ## "Below the floor" is the branch, not the log
+ * "Nearest below the floor" means nearest on the branch the run reads: the floor entry's parent, its parent, … to the root — the walk the
+ * engine's own `getPathToRoot` makes. The log also holds abandoned branches (a resumeAt moves the leaf in place and the next entries hang
+ * off an earlier entry): a record on one of them is not the run's, however near it is by position. So the scan follows parent links — a
+ * row is read only when it is the next ancestor; every other row is off the branch and passed. A log is append-only, so every ancestor sits
+ * at a lower position than its child: one newest-first pass over the positions below the floor meets the ancestors in order, and the scan
+ * stops at the first carrier on them (or at the root). The three storages share this walk; what they page differs only in where the rows
+ * live — the SQL twins page their `session_event` rows by `seq` (every row below the floor, the payload only on the two carrier types),
+ * the local window pages the branch it was cut from.
  *
- * What "below the floor, newest first" walks is the storage's: the SQL twins page their `session_event` rows by `seq` (their
- * window is cut by `seq` too); the local window pages the branch path it was cut from.
+ * No floor, or a floor at the root (a full load: the walk already reaches the root), or no carrier on the branch below the floor ⇒
+ * `undefined` (a session that predates epochs).
  */
 import type { SessionTreeEntry } from "@sema-agent/core";
-/** One row of a scan: its position (`seq`, the keyset cursor). What else the row holds is the storage's — it reads the entry
- *  out of the row itself ({@link scanEpochAnchor}'s `entryOf`), so a row is read only when the scan reaches it. */
+import type { SqlDialect } from "./sql-driver.js";
+/** One row of a scan: its position (`seq`, the keyset cursor), its entry id, its parent and its type. The entry itself is read out of the row
+ *  by the storage ({@link scanEpochAnchor}'s `entryOf`) only when the row is an ancestor of the floor and of a carrier type. */
 export interface EpochAnchorRow {
     readonly seq: string | number;
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly type: string;
 }
+/** Where the walk starts: the floor's position (rows below it have `seq < floor.seq`) and the floor entry's parent (`null` = the floor is the root). */
+export interface EpochFloor {
+    readonly seq: number;
+    readonly parentId: string | null;
+}
+/** The walk's start, from the window's floor entry and its position (no floor entry = a full load ⇒ no walk) — the one construction all three
+ *  storages use. */
+export declare function epochFloorOf(seq: number, floorEntry: SessionTreeEntry | undefined): EpochFloor | undefined;
+/** Page the rows `seq < beforeSeq`, newest first (an empty page = no older row). Rows off the branch may be in a page — the scan passes them. */
+export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
+/** The nearest epoch carrier on the branch below the floor, as stored; see the file header. */
+export declare function scanEpochAnchor<R extends EpochAnchorRow>(floor: EpochFloor | undefined, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
 /**
- * Page the rows `seq < beforeSeq` that may carry an epoch record, newest first (an empty page = no older row). A page may hold
- * other rows too — they carry nothing and the scan passes them.
+ * The SQL twins' page (one statement, two dialect spellings): every `session_event` row below `?` newest first, 100 a page, keyset on the
+ * primary key `(session_id, seq)`; the payload — projected as text, the one reading of a JSON column — only on the two carrier types
+ * (`carrier_payload`; `NULL` elsewhere), so the walk carries ids and parents and reads a payload only where a record can be.
  */
-export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
-/** The nearest epoch carrier below `floorSeq`, as stored; see the file header. */
-export declare function scanEpochAnchor<R extends EpochAnchorRow>(floorSeq: number, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
+export declare function epochAnchorPageSql(dialect: SqlDialect): string;
+/** One row of {@link epochAnchorPageSql}, read by both twins (BIGINT `seq` may arrive as a string). */
+export interface SqlEpochAnchorRow extends EpochAnchorRow {
+    readonly payload: unknown;
+}
+/** A driver row of {@link epochAnchorPageSql} → a scan row (the one mapping both twins use). */
+export declare function sqlEpochAnchorRowOf(r: Readonly<Record<string, unknown>>): SqlEpochAnchorRow;
 //# sourceMappingURL=session-epoch-anchor.d.ts.map

package/dist/plugins/session-epoch-anchor.js

@@ -1,22 +1,44 @@
-export async function scanEpochAnchor(floorSeq, page, entryOf) {
-    if (floorSeq <= 0)
+import { jsonColumnTextExpr } from "./sql-json-column.js";
+export function epochFloorOf(seq, floorEntry) {
+    return floorEntry === undefined ? undefined : { seq, parentId: floorEntry.parentId ?? null };
+}
+const CARRIER_TYPES = new Set(["prompt_epoch", "compaction"]);
+export async function scanEpochAnchor(floor, page, entryOf) {
+    if (floor === undefined || floor.seq <= 0)
         return undefined;
-    let cursor = floorSeq;
-    for (;;) {
+    let want = floor.parentId;
+    let cursor = floor.seq;
+    while (want !== null) {
         const rows = await page(cursor);
         if (rows.length === 0)
             return undefined;
         for (const row of rows) {
-            const entry = entryOf(row);
-            if (entry.type === "prompt_epoch")
-                return entry;
-            if (entry.type === "compaction") {
-                const details = entry.details;
-                if (typeof details === "object" && details !== null && "promptEpoch" in details && details.promptEpoch !== undefined)
-                    return details.promptEpoch;
+            if (row.id !== want)
+                continue;
+            if (CARRIER_TYPES.has(row.type)) {
+                const entry = entryOf(row);
+                if (entry.type === "prompt_epoch")
+                    return entry;
+                if (entry.type === "compaction") {
+                    const details = entry.details;
+                    if (typeof details === "object" && details !== null && "promptEpoch" in details && details.promptEpoch !== undefined)
+                        return details.promptEpoch;
+                }
             }
+            want = row.parentId;
+            if (want === null)
+                return undefined;
         }
         cursor = Number(rows[rows.length - 1].seq);
     }
+    return undefined;
+}
+export function epochAnchorPageSql(dialect) {
+    const carrier = `CASE WHEN type IN ('prompt_epoch','compaction') THEN ${jsonColumnTextExpr(dialect, "payload")} END AS carrier_payload`;
+    const [sessionParam, seqParam] = dialect === "pg" ? ["$1", "$2"] : ["?", "?"];
+    return `SELECT seq, entry_id, parent_id, type, ${carrier} FROM session_event WHERE session_id = ${sessionParam} AND seq < ${seqParam} ORDER BY seq DESC LIMIT 100`;
+}
+export function sqlEpochAnchorRowOf(r) {
+    return { seq: r["seq"], id: String(r["entry_id"]), parentId: r["parent_id"] ?? null, type: String(r["type"]), payload: r["carrier_payload"] };
 }
 //# sourceMappingURL=session-epoch-anchor.js.map

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

@@ -13,8 +13,24 @@ export interface SessionExtColumn {
  * 全部可空:NULL = absent / 非键控 fork。一次性迁移 M32(7.139–7.146 形:这八列在 `session_meta` 上)读同一份定义。
  */
 export declare const EXECUTION_PLACEMENT_COLUMNS: readonly SessionExtColumn[];
-/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的就是这一组。 */
+/**
+ * 客户端写计数(提交出口的撤回判据,`plugins/session-birth.ts`):**客户端可见会话态**的每一个写者(标题 / 置顶、导入、会话规则、附件绑定)在锁住根行之后、
+ * 自己的写之前同一事务 +1。读的是**写过几次**,不是格的当前值 —— 标题改回空、置顶改回 false、规则写了又删,这只会话都已经被人写过。不可空、缺省 0
+ * (行不在与行在而零写同读)。存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`(中央建表句生成)。
+ */
+export declare const CLIENT_WRITES_COLUMN: SessionExtColumn;
+/** 计数 +1 的那一句的 SET 片段(四个写者同读这一份)。 */
+export declare const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
+/**
+ * **在删令牌** —— 会话行的三态(活 → 在删 → 没了)在 SQL 上的那一格:`NULL` = 活;非空 = 一次删除已经立了围栏、还没删完,值是那一次删除尝试的令牌(uuidv7,36 字符)。
+ * 只有删除面写它(`plugins/session-store-sql.ts`:围栏写、接管换写;终刀随根行一起删掉 —— 旁表行走外键级联),读者只比等。
+ * 在删对删除门之外的一切读者与写者读作「行不在」(头读 / 列表 / 规则 L 的认领);存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`。
+ */
+export declare const DELETING_TOKEN_COLUMN: SessionExtColumn;
+/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格与在删令牌不在 `session_meta` 上出现过,不搬)。 */
 export declare const SESSION_EXT_COLUMNS: readonly SessionExtColumn[];
+/** M41 从 `session_meta` 搬进本表的那一组(计数格之前的全部格)。 */
+export declare const SESSION_EXT_MOVED_COLUMNS: readonly SessionExtColumn[];
 /** 外键约束名(两方言同名;起服探针与迁移的后置条件按名读)。 */
 export declare const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
 /** 被引列 `session_meta.session_id` 的字符集与排序规则(MySQL 协议方言;外键列逐字带上,见顶注「外键列的字符集与排序规则取自被引列」)。 */
@@ -38,8 +54,8 @@ export declare class SessionExtTableRefusedError extends StoreBootRefusalError {
 }
 /**
  * MySQL 协议方言建旁表(中央 `ensureSchema` 在 `session_meta` 建好之后调):读被引列的字符集 / 排序规则 → 按它铸建表句 → 建。`query` = 那条 DDL 连接上的一次查询(交回行)。
- * 读不出被引列 ⇒ {@link SessionExtTableRefusedError};「库确定拒了这条建表句」只按本仓唯一判官的闭集认(`sql-errors.ts` 的 `isDeploymentFaultError`:外键两侧不相容 / 加不上外键 /
- * 被引列缺索引 / 建表被存储引擎拒 / 表级权限拒 …)⇒ 同一只拒,原句随拒句;认不出的错(连接类故障、TiDB 的瞬时错、锁等待超时 …,带不带 SQL 状态码都一样)原样上抛 —— 开库等待窗重试它。
+ * 读不出被引列 ⇒ {@link SessionExtTableRefusedError};「库确定拒了这条建表句」只按本仓唯一判官的闭集认(`sql-errors.ts` 的 `isDeploymentFaultError`:建外键被库确定拒的一族 —— 两侧不相容 / 加不上外键 /
+ * 被引表缺索引、缺唯一键、缺列、打不开(不是 InnoDB)/ 约束名重复 / 选项不成立 —— 与建表被存储引擎拒 / 表级权限拒 …)⇒ 同一只拒,库答的原句与原码(errno / SQLSTATE)随拒句;认不出的错(连接类故障、TiDB 的瞬时错、锁等待超时 …,带不带 SQL 状态码都一样)原样上抛 —— 开库等待窗重试它。
  * 本模块不自带分类:判官加一码,这里随之。
  */
 export declare function ensureSessionExtTableMysql(query: (sql: string) => Promise<readonly unknown[]>): Promise<void>;
@@ -71,4 +87,12 @@ export declare class SessionExtCascadeAbsentError extends StoreBootRefusalError
  * 读不到 / 写不进 ⇒ 原样上抛(证不出级联 ≠ 通过)。调用点:起服序列在建表之后、一次性迁移之前(`boot/stores.ts`)。
  */
 export declare function assertSessionExtCascadeOn(db: Pick<SqlDriver, "dialect" | "connect">): Promise<void>;
+/** 一条连接上的行读口(本事务的语句面:SQL 文本 + 参数 → 行)。 */
+export type SessionExtRowsOn = (text: string, values: readonly unknown[]) => Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+/**
+ * 锁定读这一行的在删令牌({@link DELETING_TOKEN_COLUMN};`null` = 活)。只在根 `session_meta` 行已被本事务锁住之后调(写序:根行 → 旁表)。
+ * **先补行、再锁定读**(与执行席的 `readCellOn` 同一条理由:InnoDB 可重复读下锁定读一只不在的键拿间隙锁,两只事务随后各自补行即互等);锁定读 = 最新已提交
+ * (TiDB 悲观事务的普通读读事务起点快照,读不到在本事务取锁之前刚提交的围栏)。读者:删除面的围栏 / 终刀判官、规则 L 的认领事务。
+ */
+export declare function readDeletingTokenOn(conn: SessionExtRowsOn, dialect: SqlDialect, sessionId: string): Promise<string | null>;
 //# sourceMappingURL=session-ext-table.d.ts.map

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

@@ -1,7 +1,7 @@
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
 import { SESSION_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
 import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
-import { isDeploymentFaultError } from "./sql-errors.js";
+import { databaseAnswerCodesOf, isDeploymentFaultError } from "./sql-errors.js";
 export const SESSION_EXT_TABLE = "session_ext";
 export const EXECUTION_PLACEMENT_COLUMNS = [
     { name: "execution_role", mysql: "execution_role VARCHAR(16) NULL", pg: `execution_role VARCHAR(16) COLLATE "C"` },
@@ -19,7 +19,11 @@ const PRODUCT_COLUMNS = [
     { name: "instruction_source", mysql: "instruction_source VARCHAR(64) NULL", pg: `instruction_source VARCHAR(64) COLLATE "C"` },
     SESSION_WORKSPACE_COLUMN,
 ];
-export const SESSION_EXT_COLUMNS = [...PRODUCT_COLUMNS, ...EXECUTION_PLACEMENT_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_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'";
 const COLLATION_NAME_RE = /^[A-Za-z0-9_]{1,64}$/;
@@ -47,8 +51,9 @@ export class SessionExtTableRefusedError extends StoreBootRefusalError {
     constructor(detail) {
         super(`${SCHEMA_MISMATCH_ERROR_CODE}: this MySQL-protocol database cannot create table ${SESSION_EXT_TABLE} — refusing to start. ${detail} ` +
             `The table's foreign key ${SESSION_EXT_FOREIGN_KEY} references session_meta (session_id) with ON DELETE CASCADE; its key column copies the character set and collation of session_meta.session_id. ` +
-            "Check that session_meta is an InnoDB table on MySQL (foreign keys need InnoDB on both sides), that the database supports foreign keys (TiDB from v6.6.0), " +
-            "and that session_meta.session_id is a character column. This check changed nothing in the database.");
+            "Next: fix session_meta so that foreign key can be formed — on MySQL it must be an InnoDB table (foreign keys need InnoDB on both sides), and session_id must be a character column " +
+            "and its PRIMARY KEY or a UNIQUE key (MySQL 9.x refuses a foreign key to a non-unique column with errno 6125); on TiDB foreign keys need v6.6.0 or later; the account needs the CREATE grant. " +
+            "This is the database's definite answer, so waiting or changing the MYSQL_* coordinates will not change it. This check changed nothing in the database.");
         this.name = "SessionExtTableRefusedError";
     }
 }
@@ -64,9 +69,10 @@ export async function ensureSessionExtTableMysql(query) {
     catch (err) {
         if (!isDeploymentFaultError(err))
             throw err;
-        const { sqlState, sqlMessage: said } = err;
+        const { sqlMessage: said } = err;
         const sentence = typeof said === "string" ? said : err instanceof Error ? err.message : String(err);
-        throw new SessionExtTableRefusedError(`The foreign key column was declared CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} (read from session_meta.session_id); the database answered: ${sentence.split(/\r?\n/, 1)[0] ?? ""}${typeof sqlState === "string" ? ` (SQLSTATE ${sqlState})` : ""}.`);
+        const codes = databaseAnswerCodesOf("mysql", err);
+        throw new SessionExtTableRefusedError(`The foreign key column was declared CHARACTER SET ${referenced.characterSet} COLLATE ${referenced.collation} (read from session_meta.session_id); the database answered: ${sentence.split(/\r?\n/, 1)[0] ?? ""}${codes !== undefined ? ` (${codes})` : ""}.`);
     }
 }
 export function ensureSessionExtRowStatement(dialect, sessionId) {
@@ -118,4 +124,11 @@ export async function assertSessionExtCascadeOn(db) {
         conn.release();
     }
 }
+export async function readDeletingTokenOn(conn, dialect, sessionId) {
+    const ensure = ensureSessionExtRowStatement(dialect, sessionId);
+    await conn(ensure.text, ensure.values);
+    const row = (await conn(`SELECT ${DELETING_TOKEN_COLUMN.name} FROM ${SESSION_EXT_TABLE} WHERE session_id = ${dialect === "pg" ? "$1" : "?"} FOR UPDATE`, [sessionId]))[0];
+    const token = row?.[DELETING_TOKEN_COLUMN.name];
+    return token === null || token === undefined ? null : String(token);
+}
 //# sourceMappingURL=session-ext-table.js.map

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

@@ -20,8 +20,22 @@
  * fork 的创建那一笔就是一次建行:带元组的 fork 与带 placement 的 acquire 落**同一组**元组(六列 / 存档行头,first-write 不可变,`placedAt` 由店铸),
  * 此后这一行欠 placed 行的每一条义务(不上宿主列表 · claim 形 acquire 拒 · 进分区枚举 · release = 真删除)。元组不带属主:行的属主仍是 fork 的属主参数
  * 按 `forkOwnerOf` 的那一读(core 句:元组没有属主)。没声明分区的店照常 fork、不落元组(core 句:忽略合法,拒 fork 不合法)。
+ *
+ * ## fork 谱系(三店同一读法)
+ * fork 行的谱系两格 = core `forkRowCells` 从**源行**(fork 那一刻,建行之前那一读)铸出的 `forkedFrom`(源 id)与 `forkedFromIncarnation`(源行那一刻的住客令牌;
+ * 源行没有令牌 ⇒ 缺)—— 三店的建行都读 `forkRowCells`,本仓不写第二份谱系读法。两格落在**行上**(SQL:`session_meta` 的两列,列定义属主 `session-incarnation.ts` 的 `SESSION_META_LINEAGE_COLUMNS`;
+ * local:会话元数据边档那一格的两位),同一笔写;交出的会话元数据与列表行(`forkedFrom`)从行上读回(`session-incarnation.ts` 的 `forkLineageOfRow`)。
+ * 缺 = 不是 fork 建的行,或谱系落地之前建的 fork(源已不可知,不回填)。属主不读 `forkRowCells` 那一格:本仓的 fork 属主律是 `forkOwnerOf`(差异见 `test/session-incarnation.test.ts` 的对拍格)。
+ * **一只 fork 拷一代源**:谱系的住客那一半说的就是拷贝所读的那一代。源在这一次 fork 的几次读之间换了代(删掉后同 id 重建 —— 令牌永不复现)⇒ 这一次 fork 读到的不是一代源,
+ * 与「源不在」同答(`null`,零写):SQL 两孪生在叶 / 属主那一读、唤醒、整日志读之后各问一次住客({@link sameSourceGeneration});local 店的首次拷贝在源的写锁里读(一代),
+ * 崩在格与拷贝之间的同键补拷照这一律比格上记下的来源住客与此刻的源。
  */
 import { type ForkPoint, type ForkRowShape, type SessionStorage, type SessionStore } from "@sema-agent/core";
+/**
+ * SQL 两孪生 fork 的「一代源」判(见头注「一只 fork 拷一代源」):唤醒交出的源住客(`woke`)与整日志读之前、之后两次读到的那一格(`before` / `after`,行上原值;行不在 ⇒ `undefined`)
+ * 三者相同才是一代 —— 令牌永不复现,首尾两读与唤醒同 ⇒ 夹在中间的整日志读读的也是这一代。不是一代 ⇒ 调用方按「源不在」答。
+ */
+export declare function sameSourceGeneration(woke: string | undefined, before: unknown, after: unknown): boolean;
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
 export declare function forkPointOf(storage: SessionStorage): Promise<ForkPoint>;
 /** 两只 SQL 孪生整份日志里的一行(两孪生选同一组列):父链两键交引擎挑行,其余三列原样搬进新会话、不读内容。 */
@@ -40,7 +54,7 @@ export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
 /**
  * fork 进委派分区时落的元组 —— core `SessionStore.fork` 第三参 `opts.placement` 的那一形,**直接取 core 的型、不复述**(core 当前写作 `SessionPlacement` 去掉属主:行的属主是
  * fork 的属主参数的那一读)。本仓里这个元组型只有这一处定义:三店(local · pg · tidb)、路由店、`forkByFreshId`、引擎面声明的 fork 形参,以及建行绑定值
- * `placementInsertValues`(`session-placement.ts`)都读它 —— core 再改 `fork` 的第三参,型面在这里一处跟着动(`SessionStore.fork` 是可选成员,所以取参数前先 `NonNullable`)。
+ * `placementInsertCells`(`session-placement.ts`)都读它 —— core 再改 `fork` 的第三参,型面在这里一处跟着动(`SessionStore.fork` 是可选成员,所以取参数前先 `NonNullable`)。
  */
 export type ForkPlacement = NonNullable<NonNullable<Parameters<NonNullable<SessionStore["fork"]>>[2]>["placement"]>;
 /**

package/dist/plugins/session-fork.js

@@ -1,5 +1,8 @@
 import { SessionError, StoredSession, settledForkOptions, uuidv7 } from "@sema-agent/core";
 import { createHash } from "node:crypto";
+export function sameSourceGeneration(woke, before, after) {
+    return woke !== undefined && before === woke && after === woke;
+}
 export async function forkPointOf(storage) {
     return settledForkOptions(new StoredSession(storage));
 }

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

@@ -7,7 +7,7 @@ export declare const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty,
  * 「这个值能不能作一只会话行的属主格」—— core 7.56.0 [ref] 起只有一只判官 `principalNameOf`:主体名(有可见内容、不含控制 / 分隔 / 非连接符格式字符,
  * 原样保存不规整)或 `null`(匿名)。空串、空白串、带不可见字符的串与一切非串都不是属主(它们谁也不指 —— 读成匿名会放行每一位主体)。
  *
- * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`security.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
+ * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`principal-shape.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
  * 经过边界的请求到不了这里的拒臂;这里是纵深(嵌入方直调店、别的写者),规则只有引擎那一只,不在本仓另写。
  */
 export declare function isSessionOwnerValue(owner: unknown): owner is string | null;

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

@@ -22,7 +22,7 @@
  *
  * 本仓成文教训(`memory-origin-law.ts` 顶注同族、`key-resolver.ts` 顶注「链只有一条」):两支方言各
  * 抄一份准入判据,迟早在某一支上少一个分支——而少掉的那一支**没有任何报错面**,表现只是「这台机器上
- * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名、行→元组的映射都在
+ * 一个陌生人可以把自己接到别人子代的转录上」。所以准入判据(两个方向)、列名(读侧投影与写侧建行同一张表)、行→元组的映射都在
  * 这一处;两支后端只负责在自己的 I/O 点上调用它。
  *
  * ## 判据的两个方向(缺一不可,core `TtlSessionStore.assertPlacementAdmission` 的镜像)
@@ -37,8 +37,9 @@ import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementReco
 import type { ForkPlacement } from "./session-fork.js";
 /**
  * 三只持久会话店(SQL 两孪生 + local 后端)的**会话耐久声明**(core `SessionStore.durability`:未 placed 的会话活不活过进程重启)——
- * **单源**:三处声明(两孪生类上的顶层 `durability`、`LocalBackend` 交给店的顶层 `durability`)与委派分区的 {@link SESSION_PLACEMENTS}
- * 引用的都是这一只常量,源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
+ * **单源**:两孪生类上的顶层 `durability` 与委派分区的 {@link SESSION_PLACEMENTS} 引用的都是这一只常量;local 后端交给两半店(会话店顶层、
+ * 检查点店)的声明由 `local-store-declaration.ts` 的读者定,它的「店型的设计声明」一臂就是这一只常量(运维声明易失 / 店落在调用方自己那块易失盘上 ⇒ `process-local`)。
+ * 源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
  *
  * 为什么必须声明:core 的静态装配对**缺席**折 `"process-local"`(它不能替没表态的店猜),接线清单 `session.store` 与起服自检读的就是它 ——
  * 不声明 ⇒ 一个真持久的 SQL 部署读成「重启即丢」,没有任何一处报错。依据同下面分区声明那一段:两孪生的会话史落在 `session_meta` + `session_event` 两张真表,
@@ -47,8 +48,8 @@ import type { ForkPlacement } from "./session-fork.js";
  */
 export declare const SESSION_DURABILITY: "durable";
 /**
- * 三只持久会话店的 placement **声明**(core `SessionStore.placements`):两支 SQL 孪生(类上的字段)与 local 后端
- * (`LocalBackend` 装配 `LocalSessionStore` 时交进去 —— 值与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
+ * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`,类上的字段)。local 后端装配 `LocalSessionStore` 时交进去的分区声明与它同形,
+ * 耐久取 local 店的那一份声明(`local-store-declaration.ts`;设计声明一臂与这里同值,与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
  *
  * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
  * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在
@@ -64,20 +65,19 @@ export declare const SESSION_PLACEMENTS: {
     };
 };
 /**
- * `session_meta` 上承载 placement 元组的六列,**两方言同名**(单点定义:列名手抄两份必漂,而漂掉的
- * 那一支只会表现为「这台机器上 placed 行读不出来」——静默,不报错)。
+ * `session_meta` 上承载 placement 元组的六列,**两方言同名** —— 列名只住这一张表:读侧投影 {@link PLACEMENT_SELECT_COLUMNS}、行形
+ * {@link PlacementColumns}、写侧建行的列段与绑定值 {@link placementInsertCells} 都从它派生,源码里没有第二份手写列表
+ * (列名手抄一份必漂,而漂掉的那一支只会表现为「这台机器上 placed 行读不出来」—— 静默,不报错)。
  * `placed_at` 是 GC 的年龄锚(core `PlacedSessionRow.placedAt`);其余五列是元组本身。
  */
-export declare const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
-/** 一行 `session_meta` 的 placement 列(两方言的驱动都把列名原样带回,故一份形)。 */
-export interface PlacementColumns {
-    placement_kind?: unknown;
-    placement_scope?: unknown;
-    placement_parent_session_id?: unknown;
-    placement_root_session_id?: unknown;
-    placement_handle?: unknown;
-    placed_at?: unknown;
-}
+declare const PLACEMENT_COLUMN_NAMES: readonly ["placement_kind", "placement_scope", "placement_parent_session_id", "placement_root_session_id", "placement_handle", "placed_at"];
+type PlacementColumnName = (typeof PLACEMENT_COLUMN_NAMES)[number];
+/** 读侧投影:六列按表序逗号拼接(`SELECT …, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta …`)。 */
+export declare const PLACEMENT_SELECT_COLUMNS: string;
+/** 一行 `session_meta` 的 placement 列(两方言的驱动都把列名原样带回,故一份形;键集 = 那张表)。 */
+export type PlacementColumns = {
+    [K in PlacementColumnName]?: unknown;
+};
 /**
  * 行 → 持久化的 placement 元组(`undefined` = 这是一只普通会话)。
  *
@@ -94,9 +94,15 @@ export declare function placementFromRow(row: PlacementColumns | undefined): Ses
  * 消费方对它 fail-closed(永不按年龄收割)。一个「无行」与「另一个租户有行」分不清的 join 不许删东西。
  */
 export declare function placedRowFromRow(sessionId: string, row: PlacementColumns, lastActivityMs?: number): PlacedSessionRow;
-/** 创建时一次落行的六个绑定值(顺序 = {@link PLACEMENT_SELECT_COLUMNS});无 placement ⇒ 六个 NULL。读的只是元组(属主不在元组里 —— 它是行的属主格,建行那一笔另记):
- *  带 placement 的 acquire 与带元组的 fork 两个建行点同调。 */
-export declare function placementInsertValues(placement: ForkPlacement | undefined, placedAt: Date): [string | null, string | null, string | null, string | null, string | null, Date | null];
+/** 建行 INSERT 的放置六列:列段与绑定值出自同一张表、同序(调用方把 `columns` 接在自己的列之后、`values` 接在自己的绑定值之后,占位符按方言自写)。 */
+export interface PlacementInsertCells {
+    /** 列段(= {@link PLACEMENT_SELECT_COLUMNS}:读写同一张表)。 */
+    readonly columns: string;
+    /** 与 `columns` 同序的六个绑定值;无 placement ⇒ 六个 NULL。 */
+    readonly values: readonly (string | Date | null)[];
+}
+/** 写侧唯一导出:创建时一次落行的放置列与绑定值。两店(PG / MySQL 协议)的两个建行点 —— 带 placement 的 acquire、带元组的 fork —— 同调这一只。 */
+export declare function placementInsertCells(placement: ForkPlacement | undefined, placedAt: Date): PlacementInsertCells;
 /** `acquire` 的 opts 面(core `SessionStore.acquire` 的第二参,窄成本模块要判的两键)。 */
 export interface PlacementAcquireOpts {
     requireExisting?: boolean;
@@ -123,4 +129,5 @@ export declare function placementCapabilityOf(store: {
  * 接着收」,而不是「有些行永远看不见」。判据消费方(core 的分区收割腿)本就是每 tick 重新枚举的。
  */
 export declare const LIST_PLACED_BATCH = 1000;
+export {};
 //# sourceMappingURL=session-placement.d.ts.map

package/dist/plugins/session-placement.js

@@ -1,7 +1,8 @@
 import { SessionError } from "@sema-agent/core";
 export const SESSION_DURABILITY = "durable";
 export const SESSION_PLACEMENTS = { subagent: { durability: SESSION_DURABILITY } };
-export const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
+const PLACEMENT_COLUMN_NAMES = ["placement_kind", "placement_scope", "placement_parent_session_id", "placement_root_session_id", "placement_handle", "placed_at"];
+export const PLACEMENT_SELECT_COLUMNS = PLACEMENT_COLUMN_NAMES.join(", ");
 function toEpochMs(v) {
     if (v == null)
         return undefined;
@@ -34,17 +35,19 @@ export function placedRowFromRow(sessionId, row, lastActivityMs) {
         ? { sessionId, placedAt, scope, handle }
         : { sessionId, placedAt, tupleIncomplete: true };
 }
-export function placementInsertValues(placement, placedAt) {
-    if (placement === undefined)
-        return [null, null, null, null, null, null];
-    return [
-        placement.kind,
-        placement.scope ?? null,
-        placement.parentSessionId ?? null,
-        placement.rootSessionId ?? null,
-        placement.handle ?? null,
-        placedAt,
-    ];
+const PLACEMENT_CELL_OF = {
+    placement_kind: (p) => p.kind,
+    placement_scope: (p) => p.scope ?? null,
+    placement_parent_session_id: (p) => p.parentSessionId ?? null,
+    placement_root_session_id: (p) => p.rootSessionId ?? null,
+    placement_handle: (p) => p.handle ?? null,
+    placed_at: (_p, placedAt) => placedAt,
+};
+export function placementInsertCells(placement, placedAt) {
+    return {
+        columns: PLACEMENT_SELECT_COLUMNS,
+        values: PLACEMENT_COLUMN_NAMES.map((column) => (placement === undefined ? null : PLACEMENT_CELL_OF[column](placement, placedAt))),
+    };
 }
 export function placementCapabilityOf(store) {
     return { subagentPlacement: store.placements?.subagent !== undefined };

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

@@ -11,6 +11,17 @@
  *  ③ `write` ⇒ 补旁表行(行在不动)、按 `session_id` 写格(根行已被本事务锁住)→ 提交。`updated_at` 不动(改名不是活动 —— 列表的新近序不变)。
  * 应答行在**提交 / 回滚之后**由调用方的列表行读另读(新语句、新快照 —— 不在事务内用普通 `SELECT` 读:TiDB 悲观事务的普通读钉 `start_ts`,
  * 等锁之后会读回判定之前的旧值),再交 `settleSessionRowWrite` 复核住客。
+ *
+ * ## 结局 `absent` 的三种去向(一个词不说「写没写」)
+ * 调用方把 `absent` 答成「无此会话」(PATCH = 404),但**写落没落**按住客是在哪一刻对不上的分三种(契约「会话行可写位」一节 `PATCH` 一行同表):
+ *  ① 判官在锁下答 `absent`(行期望不中 / 没有行 / 委派分区行):回滚,一个字节没写;
+ *  ② 判官答 `changed`(行标签不中,回滚,一个字节没写),回滚之后另读应答行时那一行已换了住客、或读不到:仍是 `absent` 而不是 `changed`
+ *     (应答行属于另一位住客,不交给这位调用方),写同样一个字节没落;
+ *  ③ 判官答 `write`、事务**已提交**,提交之后另读应答行时那一行才换了住客:
+ *     · 会话被删(之后同一 id 被重新登记与否)⇒ 这一笔写随旧行的 `ON DELETE CASCADE` 一并删掉(级联是旁表的承重前提:`session-ext-table.ts` 头注、起服级联探针),重新登记的新住客的标题 / 置顶是缺省;
+ *     · 只换了属主、化身没变(同一化身被认领 / 同步重戳)⇒ 这一笔写**留在那一行上**:写落下那一刻判官判过的那位住客仍是行主(两笔都先锁根行、串行),
+ *       之后这一行连同标题换了主 —— 是行的历史,不是越权写。
+ * 应答不在事务内读(理由见上),所以③这一窗在;不取「事务内应答」。
  * 全局锁序:根 `session_meta` 一行 → 它的旁表行(→ 读日志 mark 时它的末条事件),不碰 `task_*`(与旁表的每个写者同序:根行先)。
  */
 import type { SqlDriver } from "./sql-driver.js";
@@ -18,6 +29,7 @@ import { type SessionRowAnswer, type SessionRowPatch, type SessionRowWrite, type
 /**
  * 写原语(头注):一只事务里锁根行 → 判官 → 写 / 不写;提交 / 回滚之后经 `readAnswer`(调用方店的列表行读 + 行上的住客)另读应答行。
  * `db` = 店自己的池包成的 SqlDriver(连接经它的初始化);`readAnswer` 只在判官答 `write` / `changed` 时被调。
+ * 结局 `absent` 并不都是「一个字节没写」:判官在锁下答 `absent` / 答 `changed` 之后应答复核对不上,都是零写;答 `write` 且已提交之后应答复核对不上,写已落(去向见头注)。
  */
 export declare function writeSessionRowCellsSql<Row>(db: Pick<SqlDriver, "dialect" | "connect">, sessionId: string, cells: SessionRowPatch, how: SessionRowWrite, readAnswer: (sessionId: string) => Promise<SessionRowAnswer<Row> | undefined>): Promise<SessionRowWriteOutcome<Row>>;
 //# sourceMappingURL=session-row-sql.d.ts.map