@sema-agent/server 7.136.0 → 7.138.0

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

@@ -3,7 +3,8 @@
  *
  * ## 规则(一句)
  * 「fork 拷到哪一条」只有引擎一只判官:`settledForkOptions(源会话)` 答 `{}`(整份日志)或 `{ entryId: <在飞轮的父>, position: "at" }`(拷到那一条为止)。
- * 本仓的店不写第二份「什么算在飞」—— local 店把它的答案原样交给引擎自己的 `repo.fork`;两只 SQL 孪生没有 `repo.fork`(它们按行搬字节),所以这里只管**按答案拷**:
+ * 本仓的店不写第二份「什么算在飞」—— local 店把它的答案原样交给引擎自己的 `repo.fork`;两只 SQL 孪生没有 `repo.fork`(它们按行搬字节),按答案挑行也是引擎的一只
+ * (`selectForkRows`,引擎 7.59.0 包根导出:同一条父链走法、同一组拒词);本文件只给它这两只孪生的行形(`entry_id` / `parent_id` 两列):
  *  · `{}` ⇒ 整份日志(含别的分支),叶 = 源会话的叶(与引擎 `getEntriesToFork` 的无 `entryId` 臂同);
  *  · `at` 点 ⇒ 根到分叉点那一条**路径**上的条目(与引擎 `getPathToRoot(entryId)` 同:路径,不是日志前缀,别的分支不随),叶 = 分叉点。
  *
@@ -11,24 +12,20 @@
  * 拷贝要的是**整份**持久日志(压缩地板绕过 —— 唤醒只装 `[地板..叶]`,从唤醒里拷会丢地板之前的全部历史);判官要的只是叶链上最近几条(它是引擎的一份纯函数,
  * 吃一只 `Session`):唤醒出来的会话 `getEntry` 在地板之下会回读持久日志,所以判官在压缩过的会话上也看得见整条叶链。
  */
-import { settledForkOptions, type SessionStorage } from "@sema-agent/core";
-/** 引擎答的分叉点(`{}` = 整份;`entryId` + `position: "at"` = 拷到这一条为止)。 */
-export type ForkPoint = Awaited<ReturnType<typeof settledForkOptions>>;
+import { type ForkPoint, type ForkRowShape, type SessionStorage } from "@sema-agent/core";
 /** 问引擎:这只(已唤醒的)源会话从哪里拷。SQL 孪生用它;local 店手里就是引擎的 `Session`,直接调 `settledForkOptions`。 */
 export declare function forkPointOf(storage: SessionStorage): Promise<ForkPoint>;
-/** 整份日志里一行的父链两键(其余列原样搬,不读内容)。 */
+/** 两只 SQL 孪生整份日志里的一行(两孪生选同一组列):父链两键交引擎挑行,其余三列原样搬进新会话、不读内容。 */
 export interface ForkLogRow {
     readonly entry_id: string;
     readonly parent_id: string | null;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly ts: unknown;
 }
 /**
- * 按引擎的分叉点从整份日志(oldest-first)里挑出要拷的行,与新会话的叶。行的相对顺序保留(调用方按顺序重铸 seq)。
- *
- * 分叉点不在日志里 ⇒ `invalid_fork_target`、路径中途的父不在日志里 ⇒ `invalid_session`(引擎 `getEntriesToFork` / `getPathToRoot` 同词同句);分叉点之上的父链成环 ⇒ `invalid_session`、
- * 句子与引擎的父链守卫同(守卫类不在包根,走法是同一个意思:走过的条目再踩一次 = 环;沿用它的句子,让同一件事在三种后端上说同一句话);`position` 不是 `at` ⇒ 响亮拒(本函数只认引擎今天答的两形)。
+ * 两只 SQL 孪生的行怎么交给引擎的 `selectForkRows`(按答案挑行 + 新会话的叶;分叉点不在日志里 ⇒ `invalid_fork_target`、路径中途悬空父 / 父链成环 ⇒ `invalid_session`,
+ * 引擎的原词原句)。本仓不再自写父链走法 —— 那曾是与引擎 `getPathToRoot` 同义的第二份。
  */
-export declare function forkCopyOf<R extends ForkLogRow>(rows: readonly R[], sourceLeafId: string | null, point: ForkPoint): {
-    rows: R[];
-    leafId: string | null;
-};
+export declare const FORK_LOG_ROW_SHAPE: ForkRowShape<ForkLogRow>;
 //# sourceMappingURL=session-fork.d.ts.map

package/dist/plugins/session-fork.js

@@ -1,29 +1,9 @@
-import { SessionError, StoredSession, settledForkOptions } from "@sema-agent/core";
+import { StoredSession, settledForkOptions } from "@sema-agent/core";
 export async function forkPointOf(storage) {
     return settledForkOptions(new StoredSession(storage));
 }
-export function forkCopyOf(rows, sourceLeafId, point) {
-    if (point.entryId === undefined)
-        return { rows: [...rows], leafId: sourceLeafId };
-    if (point.position !== "at") {
-        throw new SessionError("invalid_fork_target", `fork point ${point.entryId} comes with a position this store does not copy (${String(point.position)}) — only the engine's "at" point is read here`);
-    }
-    const byId = new Map();
-    for (const r of rows)
-        byId.set(r.entry_id, r);
-    const onPath = new Set();
-    let cursor = point.entryId;
-    while (cursor !== null) {
-        if (onPath.has(cursor)) {
-            throw new SessionError("invalid_session", `Entry ${cursor} is its own ancestor (parent chain cycles at ${cursor}) — start a new session, or fork from an entry above the loop`);
-        }
-        const row = byId.get(cursor);
-        if (row === undefined) {
-            throw new SessionError(cursor === point.entryId ? "invalid_fork_target" : "invalid_session", `Entry ${cursor} not found`);
-        }
-        onPath.add(cursor);
-        cursor = row.parent_id;
-    }
-    return { rows: rows.filter((r) => onPath.has(r.entry_id)), leafId: point.entryId };
-}
+export const FORK_LOG_ROW_SHAPE = {
+    idOf: (row) => row.entry_id,
+    parentOf: (row) => row.parent_id,
+};
 //# sourceMappingURL=session-fork.js.map

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

@@ -1,11 +1,32 @@
+/**
+ * 「谁也不指的串」的描述句 —— 拒句里「给的是什么」那一格的串形(从不回显值:一个谁也不指的串可能就是一段被粘进来的凭据)。
+ * 本模块的属主拒与鉴权边界的主体拒(`security.ts` `assertPrincipalShape` 的 `principal_not_a_name`)读这同一句:判官同一只,描述也同一句。
+ */
+export declare const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty, blank, or holding a control, separator or invisible format character)";
+/**
+ * 「这个值能不能作一只会话行的属主格」—— core 7.56.0 [ref] 起只有一只判官 `principalNameOf`:主体名(有可见内容、不含控制 / 分隔 / 非连接符格式字符,
+ * 原样保存不规整)或 `null`(匿名)。空串、空白串、带不可见字符的串与一切非串都不是属主(它们谁也不指 —— 读成匿名会放行每一位主体)。
+ *
+ * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`security.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
+ * 经过边界的请求到不了这里的拒臂;这里是纵深(嵌入方直调店、别的写者),规则只有引擎那一只,不在本仓另写。
+ */
+export declare function isSessionOwnerValue(owner: unknown): owner is string | null;
 /**
  * fork 拷贝的属主 —— core `SessionStore.fork` 契约的唯一读法:
- * 显式串 ⇒ 该串;无参 / 显式 `null` ⇒ 源会话记下的属主(`undefined` = 源会话没记,拷贝也不记)。
+ * 显式主体名 ⇒ 该名;无参 / 显式 `null` ⇒ 源会话记下的属主(`undefined` = 源会话没记,拷贝也不记)。
+ * 显式给了却不是主体名(空串 / 空白 / 带不可见字符,core 7.56.0 [ref])⇒ 响亮拒(`SessionError("storage")`,不留行)—— 与 `register` 首写同一只判官。
  */
 export declare function forkOwnerOf(requested: string | null | undefined, sourceOwner: string | null | undefined): string | null | undefined;
 /**
- * `register` 首写的 owner 守卫 —— core `SessionStore.register` 契约的唯一读法(三只店同调):首写的 owner 既不是串也不是 `null` ⇒ 响亮拒(不留行);
- * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。
+ * `register` 首写的 owner 守卫 —— core `SessionStore.register` 契约的唯一读法(三只店同调):首写的 owner 既不是主体名也不是 `null` ⇒ 响亮拒(不留行);
+ * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。判官 = {@link isSessionOwnerValue}(core 7.56.0 [ref] `principalNameOf`)。
  */
 export declare function assertFirstOwnerWritable(sessionId: string, owner: unknown): asserts owner is string | null;
+/**
+ * 导入者的属主 —— 换装的写腿(公开 `importEntries` / `replaceEntries` 与暂存提交)把调用方给的属主重戳进会话行之前的唯一读法:
+ * 主体名或 `null`(匿名)⇒ 原样交回;别的一切(空串、空白串、带控制 / 分隔 / 非连接符格式字符的串、非串)⇒ `TypeError` 响亮拒 ——
+ * 与引擎导入口拒同一类值时同一类错、同一句开头(引擎那一判只作用于交给它的属主,而换装交给引擎的是存档自己的戳,所以这一判在本仓)。
+ * 调用方在读写任何东西之前判,拒了就一个字节没写。判官 = {@link isSessionOwnerValue}(core `principalNameOf`),不在本仓另写规则。
+ */
+export declare function importerOwnerOf(owner: unknown): string | null;
 //# sourceMappingURL=session-ownership.d.ts.map

package/dist/plugins/session-ownership.js

@@ -1,11 +1,30 @@
-import { SessionError } from "@sema-agent/core";
+import { SessionError, principalNameOf } from "@sema-agent/core";
+export const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty, blank, or holding a control, separator or invisible format character)";
+function ownerValueFault(owner) {
+    if (typeof owner === "string")
+        return NOT_A_PRINCIPAL_NAME;
+    return owner === undefined ? "undefined" : typeof owner;
+}
+export function isSessionOwnerValue(owner) {
+    return owner === null || principalNameOf(owner) !== undefined;
+}
 export function forkOwnerOf(requested, sourceOwner) {
-    return typeof requested === "string" ? requested : sourceOwner;
+    if (requested === undefined || requested === null)
+        return sourceOwner;
+    if (principalNameOf(requested) === undefined) {
+        throw new SessionError("storage", `fork: session owner must be a principal name or null, got ${ownerValueFault(requested)} — refusing, nothing written`);
+    }
+    return requested;
 }
 export function assertFirstOwnerWritable(sessionId, owner) {
-    if (typeof owner === "string" || owner === null)
+    if (isSessionOwnerValue(owner))
         return;
-    throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal (string) or null (anonymous), got ${owner === undefined ? "undefined" : typeof owner} — ` +
-        "a stored value that the head read reads back as 'no row' would leave the session claimable forever and ownable never; refusing, nothing written");
+    throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal name or null (anonymous), got ${ownerValueFault(owner)} — ` +
+        "a value that names nobody would leave the session claimable by anyone or ownable by no one; refusing, nothing written");
+}
+export function importerOwnerOf(owner) {
+    if (isSessionOwnerValue(owner))
+        return owner;
+    throw new TypeError(`session owner must be a principal name or null (anonymous), got ${ownerValueFault(owner)} — an import stamps it as the session's owner; refusing, nothing written`);
 }
 //# sourceMappingURL=session-ownership.js.map

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

@@ -0,0 +1,17 @@
+import type { SessionWorkspace } from "../session-workspace.js";
+import { type JsonColumnReader } from "./sql-json-column.js";
+/** 列定义的唯一属主(两方言 DDL 内插它;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由建表语句生成)。 */
+export declare const SESSION_META_WORKSPACE_COLUMN: {
+    readonly name: "workspace";
+    readonly tidb: "workspace JSON NULL";
+    readonly pg: "workspace JSONB";
+};
+/** 这一格的形读者(三只店与帧投影同一只;写前也过它 —— 写得进的就是读得出的)。 */
+export declare const readSessionWorkspaceCell: JsonColumnReader<SessionWorkspace>;
+/** 这一格的失败留痕 tag(F 类;登记行在 `observability/fail-open.ts`)。记录座(写 / 帧)与本文件(读)同一只。 */
+export declare const SESSION_WORKSPACE_DEGRADED: "server.session-workspace.record-degraded";
+/** 值 → 这一格的文本。`encode` 是该承载的编码器(MySQL 协议与 local:`JSON.stringify`;PG:`pgSafeJsonStringify`)。写前过形读者,不合形响亮抛、什么都不写。 */
+export declare function encodeSessionWorkspaceCell(workspace: SessionWorkspace, encode: (value: unknown) => string, sessionId: string): string;
+/** 一格(已按文本投影;SQL NULL / local 缺键 ⇒ 调用方传 `null`)→ 值。坏体 ⇒ 读作没有记录并计一次(见文件头);读腿漏投影 ⇒ 抛。 */
+export declare function decodeSessionWorkspaceCell(cell: unknown, sessionId: string): SessionWorkspace | undefined;
+//# sourceMappingURL=session-workspace-cell.d.ts.map

package/dist/plugins/session-workspace-cell.js

@@ -0,0 +1,38 @@
+import { PROJECT_ID_REGEX } from "@sema-agent/core";
+import { z } from "zod";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { assertJsonColumnWritable, createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
+export const SESSION_META_WORKSPACE_COLUMN = {
+    name: "workspace",
+    tidb: "workspace JSON NULL",
+    pg: "workspace JSONB",
+};
+const SESSION_WORKSPACE_SHAPE = z.object({
+    cwd: z.string().min(1),
+    root: z.string().min(1),
+    entered: z.object({ dir: z.string().min(1), byPath: z.literal(true).optional() }).optional(),
+    project: z.object({ id: z.string().regex(PROJECT_ID_REGEX), source: z.enum(["marker", "declared"]) }).optional(),
+    remote: z.boolean(),
+});
+export const readSessionWorkspaceCell = createZodColumnReader(SESSION_WORKSPACE_SHAPE);
+export const SESSION_WORKSPACE_DEGRADED = "server.session-workspace.record-degraded";
+const where = (sessionId) => `session_meta.workspace for session ${sessionId}`;
+export function encodeSessionWorkspaceCell(workspace, encode, sessionId) {
+    const text = encode(workspace);
+    assertJsonColumnWritable(text, readSessionWorkspaceCell, where(sessionId));
+    return text;
+}
+export function decodeSessionWorkspaceCell(cell, sessionId) {
+    if (cell === null)
+        return undefined;
+    try {
+        return decodeJsonColumn(cell, readSessionWorkspaceCell, where(sessionId));
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        recordFailOpen(SESSION_WORKSPACE_DEGRADED, `op=read ${e.where} problem=${e.problem}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=session-workspace-cell.js.map

package/dist/plugins/sql-errors.d.ts

@@ -145,7 +145,7 @@ export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
 export declare function isConnectionUnusableError(err: unknown): boolean;
 /**
  * **连接类故障**的识别表(闭集;逐行登记「为什么」)—— 「到库的那条连接坏了 / 库此刻不接」:与这一条语句的内容无关、什么都不改稍后再试可能成。
- * 读者(整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,三处同读):审批队列读口、文件历史店的折点(`permanence: "transient"`)、会话同步拉取口(`503`)。
+ * 读者(整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,三处同读):审批队列读口、文件历史店的折点(`permanence: "transient"`)、会话同步拉取口(`503` + `permanence: "transient"`)。
  *
  * 识别集 = 三张表的并集,**没有第四处**:
  *  · 本表(下):套接字层与协议层的断连 / 拒连 / 连接数满 / 库的关停与只读切换,按 `code` 登记(MySQL 协议的数字 errno 在场的并登 —— 同本文件其余谓词的姿势:`errno` 与 `code` 是同一件事的两种写法);
@@ -153,7 +153,7 @@ export declare function isConnectionUnusableError(err: unknown): boolean;
  *  · {@link CONNECTION_FAULT_DRIVER_SENTENCES}:驱动自己抛的**无 `code` 的裸 `Error`**(node-pg 的断连在这一形),按整句相等认。
  *
  * **不在识别集里**(认不出一律不是 —— 错判成连接类的代价是调用方被劝「再试」去撞一个注定失败的语句):
- *  · 语句级的错:唯一键冲突、CHECK 被拒、缺表缺列、语法错、权限错、行 / 包超墙(1153 / 8025 / `54000`);
+ *  · 语句级的错:唯一键冲突、CHECK 被拒、缺列、语法错、行 / 包超墙(1153 / 8025 / `54000`);缺表与权限拒也不是连接类 —— 它们是**部署错配类**(判官的另一个词,识别表 {@link DEPLOYMENT_FAULT_ERRORS},与本表互斥);
  *  · 死锁(引擎的仲裁产物,重试的前提在调用方的整事务重来,见 {@link isDeadlockError})与锁等待 / 语句超时(延迟信号,重试只把长等待乘上次数);
  *  · 认证类拒连(MySQL 1045、PG `28xxx`、`08004`:凭据 / 白名单要人去改)与协议违例(PG `08P01`、mysql2 `PROTOCOL_ERROR`:我方的码病);
  *  · TiDB 自己的忙 / 区域不可用(9001 / 9005 一族)—— 候真库逐码读数再登,今天不在表里(登记在案的未收项);
@@ -180,6 +180,27 @@ export declare const CONNECTION_FAULT_DRIVER_SENTENCES: ReadonlyArray<{
  * 归因键三种:`code`(字符串)、`errno`(数字)、无 `code` 的驱动裸 `Error` 的整句 —— 只读被抛出的这一只对象身上的结构化字段 / 整句,**不读散文里的在册词**。
  */
 export declare function isConnectionFaultError(err: unknown): boolean;
+/**
+ * **部署错配类故障**的识别表(闭集;逐行登记「为什么」)—— 到库的连接是好的、语句也是对的,是这套库的形与本部署的要求不符:**重试注定失败**,修表 / 授权之前什么都不会变
+ * (与连接类互为反面:那一类是「什么都不改稍后再试可能成」)。读者:整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf` 的 `deployment` 一词 ——
+ * 文件历史店的折点与会话同步拉取口(`503 state.file_history_unreadable`)据它判 `permanence: "terminal"`;审批队列读口并入「此刻读不出」的 503;各读者各自表态,**不在自己那里写码**。
+ *
+ * 识别集 = 本表一张,按归因键登记:`code`(字符串)与 MySQL 协议的数字 `errno`(两键是同一件事的两种写法,代理 / 序列化往返可能只留一个;同本文件其余谓词的姿势)。
+ * **与连接类互斥**:本表的任何一码都不在 {@link CONNECTION_FAULT_ERRORS} / {@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 的识别集里,反之亦然(`test/store-fault-judge.test.ts` 钉两个方向)—— 同一只错只落一个词。
+ *
+ * **不在表里**(认不出一律不是;本批只收缺表与权限拒两形,其余是登记在案的未收项,不是「已裁定不判」):缺列(1054 / `42703`:升级前置断言 `assert*Schema` 族有自己的判据与出路)、
+ * 认证类拒连(MySQL 1045、PG `28xxx`:凭据 / 白名单)、库级与列级的权限拒(MySQL 1044 / 1143)、TiDB 自己的忙 / 区域不可用一族(同连接类表的登记)。
+ */
+export declare const DEPLOYMENT_FAULT_ERRORS: ReadonlyArray<{
+    readonly code: string;
+    readonly errno?: number;
+    readonly why: string;
+}>;
+/**
+ * 「这个错误**是**部署错配类故障吗」—— {@link DEPLOYMENT_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
+ * 只读被抛出的**这一只**对象身上的结构化字段(`code` 字符串 / `errno` 数字),不沿 `cause` 链找、不读散文里的在册词。
+ */
+export declare function isDeploymentFaultError(err: unknown): boolean;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -130,6 +130,21 @@ export function isConnectionFaultError(err) {
         return true;
     return err instanceof Error && code === undefined && CONNECTION_FAULT_SENTENCES.has(err.message);
 }
+export const DEPLOYMENT_FAULT_ERRORS = [
+    { code: "42P01", why: "PG undefined_table(缺表:库没按本版的表结构建好 / 迁移没跑 —— 重试不会让表长出来)" },
+    { code: "42501", why: "PG insufficient_privilege(权限拒:库账号缺这张表 / 这类语句的授权 —— 授权之前重试注定失败)" },
+    { code: "ER_NO_SUCH_TABLE", errno: 1146, why: "MySQL 协议(MySQL / MariaDB / TiDB)缺表:同 PG `42P01`" },
+    { code: "ER_TABLEACCESS_DENIED_ERROR", errno: 1142, why: "MySQL 协议表级权限拒:库账号对这张表缺这类语句的授权,同 PG `42501`" },
+];
+const DEPLOYMENT_FAULT_CODES = new Set(DEPLOYMENT_FAULT_ERRORS.map((r) => r.code));
+const DEPLOYMENT_FAULT_ERRNOS = new Set(DEPLOYMENT_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])));
+export function isDeploymentFaultError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = keyOf(err, "code");
+    const errno = keyOf(err, "errno");
+    return (typeof code === "string" && DEPLOYMENT_FAULT_CODES.has(code)) || (typeof errno === "number" && DEPLOYMENT_FAULT_ERRNOS.has(errno));
+}
 export class StoreRowTooLargeError extends Error {
     row;
     wall;

package/dist/plugins/store-backend.js

@@ -53,7 +53,7 @@ import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
 import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
 import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
-import { TiDBRetentionStore, PgRetentionStore } from "./retention-store-sql.js";
+import { TiDBRetentionStore, PgRetentionStore, sqlStoreRetention } from "./retention-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
 import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
@@ -149,9 +149,9 @@ class TiDBBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
+    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     checkpointReadView() { return this.checkpoint(); }
-    toolResult() { return new TiDBToolResultStore(this.pool); }
+    toolResult() { return new TiDBToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
     imageBake() { return new TiDBImageBake(this.pool); }
     leaderRun() { return new TiDBLeaderRunStore(this.pool); }
@@ -161,7 +161,7 @@ class TiDBBackend {
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new TiDBSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
+    session() { return new TiDBSessionStore(this.pool, { log: createLogger(this.config.logLevel), retention: sqlStoreRetention(this.config.retentionSweep) }); }
     adoptionLog() { return new TiDBAdoptionLogStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
@@ -203,9 +203,9 @@ class PgBackend {
     workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
+    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     checkpointReadView() { return this.checkpoint(); }
-    toolResult() { return new PgToolResultStore(this.pool); }
+    toolResult() { return new PgToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new PgImageIndex(this.pool); }
     imageBake() { return new PgImageBake(this.pool); }
     leaderRun() { return new PgLeaderRunStore(this.pool); }
@@ -215,7 +215,7 @@ class PgBackend {
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new PgSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
+    session() { return new PgSessionStore(this.pool, { log: createLogger(this.config.logLevel), retention: sqlStoreRetention(this.config.retentionSweep) }); }
     adoptionLog() { return new PgAdoptionLogStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }

package/dist/plugins/store-contracts.d.ts

@@ -19,6 +19,7 @@
  *    code should import from this file.
  */
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
+import type { RunIdentity } from "../identity-source.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -212,8 +213,13 @@ export interface RunRecord {
      *  (MCP façade / portal). null when the caller didn't supply one. */
     jobId: string | null;
     /** Which SYSTEM's credential submitted the run (oa/cc-mcp/portal…), derived at the auth gate — never
-     *  self-declared. null = legacy single-token deployment (authenticated, no system identity). */
+     *  self-declared. null = legacy single-token deployment (authenticated, no system identity).
+     *  **归因用,不是认证来源**:任何凭据判都不读它(认证来源 = {@link RunRecord.identity});系统名是运维写的任意串,`"sso"` 也只是归因值。 */
     source: string | null;
+    /** 🔴 **run 行身份元组**(三列 `identity_source` / `identity_scope` / `identity_principal_inc`):受理时在凭据门上铸、建行时写入、之后只读 ——
+     *  续跑认领 / 挂起 / 终局 / 重启都不改它,没有按当前状态重算的读者。`null` = 这一行没有「属主在受理时验过的凭据」的记录(三列之前的行 /
+     *  无鉴权写面的受理 / 别人替属主按下的那一跑),一律不合格。律与形的唯一属主 = `identity-source.ts`。不上 wire(run 读面是显式投影,不带它)。 */
+    identity: RunIdentity | null;
     /** The replica currently HOLDING this run — written at createRun and TAKEN OVER by markResuming ([ref]: a
      *  cross-replica resume moves the seat, so a reader comparing it with its own instanceId is asking "is the
      *  live leg here NOW", not "who minted the row"). Lets a preempt/cancel/steer handler tell "this run is on
@@ -263,6 +269,9 @@ export interface RunIdemBinding {
 export interface NewRunMeta {
     jobId?: string | null;
     source?: string | null;
+    /** 这一行的身份元组(`RunRecord.identity` 的写口)。缺席 = `null`(没有记录;不合格)。`src/http/**` 的每个建行点都显式写它(机器门
+     *  `test/run-identity-tuple.test.ts`),取值只经凭据门铸下的那一份(`principal-gate.ts` 的 `runIdentityOf`)。 */
+    identity?: RunIdentity | null;
     objectivePreview?: string | null;
     idem?: RunIdemBinding | null;
 }

package/dist/plugins/store-fault.d.ts

@@ -1,4 +1,4 @@
-export type StoreFaultClass = "corrupt" | "connection" | "unclassified";
-/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。 */
+export type StoreFaultClass = "corrupt" | "connection" | "deployment" | "unclassified";
+/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。两张识别表互斥,判序不影响结果(`test/store-fault-judge.test.ts` 钉互斥)。 */
 export declare function storeFaultClassOf(err: unknown): StoreFaultClass;
 //# sourceMappingURL=store-fault.d.ts.map

package/dist/plugins/store-fault.js

@@ -1,8 +1,10 @@
-import { isConnectionFaultError } from "./sql-errors.js";
+import { isConnectionFaultError, isDeploymentFaultError } from "./sql-errors.js";
 import { StoreCorruptError } from "./sql-json-column.js";
 export function storeFaultClassOf(err) {
     if (err instanceof StoreCorruptError)
         return "corrupt";
-    return isConnectionFaultError(err) ? "connection" : "unclassified";
+    if (isConnectionFaultError(err))
+        return "connection";
+    return isDeploymentFaultError(err) ? "deployment" : "unclassified";
 }
 //# sourceMappingURL=store-fault.js.map

package/dist/plugins/tidb-pool.js

@@ -7,6 +7,8 @@ import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
+import { SESSION_META_WORKSPACE_COLUMN } from "./session-workspace-cell.js";
+import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
 import { PRINCIPAL_MAX_UTF8_BYTES } from "../security.js";
@@ -72,6 +74,11 @@ export const SCHEMA_STATEMENTS = [
      -- (CLAUDE.md / .claude/CLAUDE.md / AGENTS.md / .claude/AGENTS.md)。服务端元数据:不进模型上下文、不进 wire
      -- 会话面;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL(新会话首 run 同样只写不发)。
      instruction_source VARCHAR(64) NULL,
+     -- workspace:本会话上一条腿**自己的**最后一帧 workspace_changed(引擎 7.58.0 的整份快照:cwd / root / entered / project / remote)。
+     -- NULL = 还没有任何腿记过;唯一写者 = 腿的记录座(src/session-workspace.ts),列属主 = src/plugins/session-workspace-cell.ts
+     -- (列定义、形读者、编解码;存量库缺这一列 ⇒ 起服列册对账拒启,拒句里给出 ALTER)。下一条腿的 TaskSpec.projectId 读它的 project.id。
+     -- 服务端元数据:不进 wire 会话面、不进模型上下文;住在会话行上 ⇒ 随会话删除 / 留存清扫一起消失,fork 出的新行为 NULL。
+     ${SESSION_META_WORKSPACE_COLUMN.tidb},
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组,**创建时一次落行、
      -- first-write 不可变**(register 的 ON DUPLICATE 臂永不重写这六列)。判别位 = placement_kind:
      -- 在场 ⇒ 该会话住在 placement 分区里(不上宿主枚举、claim 形 acquire 恒拒、release=真删除、
@@ -155,6 +162,12 @@ export const SCHEMA_STATEMENTS = [
      -- source (credential-derived system identity, clay 2026-06-12): which door submitted the run
      -- (oa / cc-mcp / portal).
      source      VARCHAR(64)  NULL,
+     -- identity_source / identity_scope / identity_principal_inc: the run's identity tuple, minted ONCE at the credential gate when the
+     -- run is accepted and never rewritten (no UPDATE touches them). NULL = no record of a credential the owner presented at acceptance
+     -- (rows from before these columns, unauthenticated-write acceptance, a run someone else accepted on the owner's behalf) ⇒ not
+     -- qualified. Column definitions' single owner = src/identity-source.ts RUN_IDENTITY_COLUMNS (the boot column probe derives its
+     -- ALTER suggestion from this statement). \`source\` above is attribution only, never an authentication source.
+     ${RUN_IDENTITY_COLUMNS.tidb},
      -- objective_preview: the list's "what is this task" glance — redacted + truncated at write.
      objective_preview VARCHAR(160) NULL,
      -- cancel_requested: durable cross-replica CANCEL flag. The running instance's heartbeat tick honors it

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

@@ -13,6 +13,8 @@
 import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
+import type { SessionWorkspace } from "../session-workspace.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 import { type SessionFace } from "../session-incarnation.js";
 import type { SessionSummary } from "./store-contracts.js";
 import type { SessionRowPatch } from "../session-row.js";
@@ -21,9 +23,9 @@ import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class TiDBSessionStore implements SessionStore {
     private readonly pool;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而实现体在别处」逐字见
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法逐字见
      *  `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement **声明**。六条义务的实装点逐条见
      *  {@link SQL_SESSION_PLACEMENTS} 顶注与本类的 acquire / listSessions / release / listPlaced /
      *  placementOf 各处的 `[ref]` 注。 */
@@ -38,6 +40,7 @@ export declare class TiDBSessionStore implements SessionStore {
     private readonly log;
     constructor(pool: Pool, opts?: {
         readonly log?: OrphanOwnerLog;
+        readonly retention?: RetentionDeclaration;
     });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
@@ -165,6 +168,18 @@ export declare class TiDBSessionStore implements SessionStore {
      * 在期限内拒。⚠️ mysql2 的超时是客户端侧的 —— 拒之后那条连接仍被挂着的命令占到服务端结束(S-9 同形,如实披露)。
      */
     recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
+    /**
+     * 会话行的位置与项目那一格(`session_meta.workspace`;域律 `src/session-workspace.ts`,列属主 `session-workspace-cell.ts`)。
+     * 一行 PK 读,按文本投影、恰好解一次;行不在 / 格为 NULL ⇒ `undefined`;格读不出 ⇒ 读作没有记录并计一次(F 类,见列属主头注)。
+     */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜;唯一调用方 = 腿的记录座,它在腿的流循环里一笔一笔等写完)。**住客围栏**:只写化身仍是 `incarnation` 的那一行 ——
+     * 行不在、或同 id 已换了住客 ⇒ 0 行、不抛(那一行不是这条腿的)。**不**碰 `updated_at`(那是会话活动时刻,留存腿按它判龄;记下站在哪里不是一次会话活动)。
+     * 走店的一般查询面(与腿循环里的账本追加同一形,不另设每查询的客户端超时):mysql2 的客户端超时只是不再等,服务端照把那条 UPDATE 跑完 ——
+     * 一笔「放弃等待却仍会落地」的写正是这条腿离开之后还能盖掉下一条腿的那一形。卡住的上界归服务端(锁等待超时)与部署的池策略。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /**
      * E17 — fork a session: copy its WHOLE durable history to a NEW uuidv7 session owned by `owner`, mirroring
      * core's `PgSessionRepo.fork`. Entry ids / parent links are per-session and copy VERBATIM; only `seq` is

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

@@ -4,24 +4,27 @@ import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { jsonColumnText } from "./sql-json-column.js";
 import { escapeLike } from "./sql-escape.js";
 import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { MANAGED_RETENTION } from "./retention-store-sql.js";
+import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
 import { createLogger } from "../observability/logger.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
-import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
-import { forkCopyOf, forkPointOf } from "./session-fork.js";
+import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue } from "./session-ownership.js";
+import { selectForkRows } from "@sema-agent/core";
+import { FORK_LOG_ROW_SHAPE, forkPointOf } from "./session-fork.js";
 export class TiDBSessionStore {
     pool;
-    retention = MANAGED_RETENTION;
+    retention;
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
     log;
     constructor(pool, opts = {}) {
         this.pool = pool;
         this.log = opts.log ?? createLogger();
+        this.retention = opts.retention ?? UNMANAGED_RETENTION;
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -58,7 +61,7 @@ export class TiDBSessionStore {
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
-        if (typeof owner !== "string" && owner !== null) {
+        if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return;
             assertFirstOwnerWritable(sessionId, owner);
@@ -247,6 +250,14 @@ export class TiDBSessionStore {
             await this.pool.query({ sql: "UPDATE session_meta SET instruction_source = ? WHERE session_id = ? AND instruction_source IS NULL", timeout: BASELINE_IO_DEADLINE_MS }, [next, sessionId]);
         }
     }
+    async readSessionWorkspace(sessionId) {
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "workspace")} FROM session_meta WHERE session_id = ?`, [sessionId]);
+        const row = rows[0];
+        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
+    }
+    async recordSessionWorkspace(sessionId, incarnation, workspace) {
+        await this.pool.query("UPDATE session_meta SET workspace = ? WHERE session_id = ? AND incarnation = ?", [encodeSessionWorkspaceCell(workspace, JSON.stringify, sessionId), sessionId, incarnation]);
+    }
     async fork(sourceId, owner) {
         const [metaRows] = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = ?", [sourceId]);
         if (!metaRows[0])
@@ -258,7 +269,7 @@ export class TiDBSessionStore {
             return null;
         const point = await forkPointOf(storage);
         const [allRows] = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("tidb", "payload")}, ts FROM session_event WHERE session_id = ? ORDER BY seq ASC`, [sourceId]);
-        const { rows: eventRows, leafId: forkLeafId } = forkCopyOf(allRows, leafId, point);
+        const { rows: eventRows, leafId: forkLeafId } = selectForkRows(allRows, leafId, point, FORK_LOG_ROW_SHAPE);
         const newId = uuidv7();
         const now = new Date();
         const conn = await this.pool.getConnection();
@@ -353,7 +364,7 @@ export class TiDBSessionStore {
             }
             await conn.query("DELETE FROM session_event WHERE session_id = ?", [sessionId]);
             await conn.query("DELETE FROM session_meta WHERE session_id = ? AND owner <=> ? AND placement_kind IS NULL", [sessionId, owner]);
-            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRows[0] === undefined ? undefined : { owner: placedRows[0].owner, incarnation: placedRows[0].incarnation }, owner));
+            await this.insertValidatedLog(conn, sessionId, owner, validated, carriedIncarnation(sessionId, placedRows[0] === undefined ? undefined : { incarnation: placedRows[0].incarnation }));
             await conn.commit();
         }
         catch (err) {

package/dist/plugins/tool-result-store-sql.d.ts

@@ -2,6 +2,7 @@ import type { ToolResultProvenance, ToolResultStore, ToolResultSlice, ToolResult
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool, PoolClient as PgPoolClient } from "pg";
 import { type SqlDriver } from "./sql-driver.js";
+import type { RetentionDeclaration } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 /** PG schema for the tool_result table — the PG translation of tidb-pool.ts's tool_result DDL
  *  (LONGTEXT→TEXT, DATETIME(3)→TIMESTAMPTZ(3), inline KEY→separate CREATE INDEX). Disjoint from other stores'
@@ -29,10 +30,12 @@ export declare function assertToolResultProvenanceSchema(query: (sql: string) =>
 /** Dual-dialect durable ToolResultStore. See the file header for the dialect-delta ledger. */
 export declare class SqlToolResultStore implements ToolResultStore {
     protected readonly db: SqlDriver;
-    /** [ref] 车1:托管留存声明。读法与「为什么 SQL 店答 managed 而三方法的实现体在 `retention-store-sql.ts`」
-     *  逐字见 {@link MANAGED_RETENTION}(本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
-    readonly retention: import("@sema-agent/core").RetentionDeclaration;
-    constructor(db: SqlDriver);
+    /** 托管留存声明 = 装配交给它的词(后端按扫车道开不开给;不给 ⇒ `"none"`)。读法与「为什么 SQL 店答 managed 而三方法的实现体在
+     *  `retention-store-sql.ts`」逐字见 {@link MANAGED_RETENTION}(扫车道开着时本店的 `tool_result` 行由那只聚合店按期清:随会话树删 + 孤儿腿)。 */
+    readonly retention: RetentionDeclaration;
+    constructor(db: SqlDriver, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** D1(试剂盒揪出,[ref] 语义):ref 是主键,而 `deleteBySession` 只认**记录下来的出处**与单射的
@@ -97,10 +100,14 @@ export declare class SqlToolResultStore implements ToolResultStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBToolResultStore extends SqlToolResultStore {
-    constructor(pool: MySqlPool);
+    constructor(pool: MySqlPool, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgToolResultStore extends SqlToolResultStore {
-    constructor(pool: PgPool);
+    constructor(pool: PgPool, opts?: {
+        readonly retention?: RetentionDeclaration;
+    });
 }
 //# sourceMappingURL=tool-result-store-sql.d.ts.map