@sema-agent/server 7.147.0 → 7.148.0

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

@@ -15,6 +15,8 @@
  * 件事的两种写法**,任一在场即可判定 —— 认并集不会造出假阳性,而认单键会漏掉任何只保留另一个键的
  * 形(驱动版本差异、代理/包装层、序列化往返)。这正是收编前两个真漏判的成因,门钉在
  * `test/sql-dup-key-single-source.test.ts`。
+ * 同一条道理的最后一种形:错误对象**不是驱动原错**(调用方递进来的 query 包装把键丢了、只剩 `message`)⇒ 另有一只**宽读法** {@link isDupKeyErrorOfWrappedQuery},
+ * 只给吃这种 query 函数的站点(`ensureIndex`)用;持驱动原错的店走严格读法,不按散文改判。两只读法都住在这里(站点不自带文案正则),钉同一个文件。
  *
  * ## 为什么是 `Reflect.get` 而不是属性访问/展开
  * 驱动错误类在某些版本把这两个键挂在**原型链**上:`{...err}` 只拷自有可枚举键,会**静默**丢掉它们,
@@ -36,12 +38,19 @@ export declare const MYSQL_ER_DUP_ENTRY_ERRNO = 1062;
 export declare const MYSQL_ER_DUP_ENTRY_CODE = "ER_DUP_ENTRY";
 /** PostgreSQL `unique_violation` 的 SQLSTATE。 */
 export declare const PG_UNIQUE_VIOLATION_SQLSTATE = "23505";
-/** MySQL/TiDB 的唯一键冲突:`code === "ER_DUP_ENTRY"` **或** `errno === 1062`(同一件事的两种写法)。 */
+/** MySQL/TiDB 的唯一键冲突:`code === "ER_DUP_ENTRY"` **或** `errno === 1062`(同一件事的两种写法)。只读结构化归因键,不读 `message` 散文。 */
 export declare function isMysqlDupKeyError(err: unknown): boolean;
 /** PostgreSQL 的唯一键冲突:SQLSTATE `23505`(node-pg 挂在 `code` 上)。 */
 export declare function isPgUniqueViolation(err: unknown): boolean;
 /** 方言分派口——双方言店的调用形(`isDupKeyError(this.db.dialect, e)`)。 */
 export declare function isDupKeyError(dialect: SqlDialect, err: unknown): boolean;
+/**
+ * **宽读法**:{@link isDupKeyError} 之外,MySQL 协议另认 `message` 里的 `Duplicate entry` 句子 —— 给**错误对象不是驱动原错**的站点用:`ensureIndex` 吃调用方递进来的 `query`
+ * 函数(`IndexQueryFn`),那层包装可能把结构化键丢了(或写成 `null`)、给句子加前缀,只剩 `message`。持驱动原错的店(十余处,走 {@link isDupKeyError})**不**用它:
+ * 它们拿得到带 `code` / `errno` 的原错,按散文改判会把一句碰巧带这两个词的非唯一键错读成「已存在」(例:`mark` 的 `existed` 回执)。
+ * 宽读法 ⊇ 严格读法;PG 臂没有散文臂(只认 SQLSTATE `23505`)。散文臂只住在这里 —— 站点不自带文案正则。
+ */
+export declare function isDupKeyErrorOfWrappedQuery(dialect: SqlDialect, err: unknown): boolean;
 /** PostgreSQL `undefined_column` 的 SQLSTATE。⚠️ 与 `42P01`(`undefined_table`)刻意分开。 */
 export declare const PG_UNDEFINED_COLUMN_SQLSTATE = "42703";
 /** MySQL/TiDB `ER_BAD_FIELD_ERROR`(未知列)的数字 errno。 */
@@ -194,25 +203,43 @@ export declare function isConnectionFaultError(err: unknown): boolean;
  * (与连接类互为反面:那一类是「什么都不改稍后再试可能成」)。读者:整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf` 的 `deployment` 一词 ——
  * 文件历史店的折点与会话同步拉取口(`503 state.file_history_unreadable`)据它判 `permanence: "terminal"`;审批队列读口并入「此刻读不出」的 503;各读者各自表态,**不在自己那里写码**。
  * 起服建表(`session-ext-table.ts` 的 `ensureSessionExtTableMysql`)问的也是这一只:「库确定拒了这条 DDL」= 本表认得 ⇒ 当场拒启;认不出 ⇒ 原样上抛、开库等待窗重试 —— 不自带第二份分类。
- * 外键四码(3780 / 1215 / 1822 / 1005)只可能出在建表 / 改表上,读写路径上的读者见不到它们 —— 加进本表对那几处零变化。
+ * 建外键被库确定拒的十码(1005 / 1215 / 1821 / 1822 / 1824 / 1825 / 1826 / 3734 / 3780 / 6125)只可能出在建表 / 改表上,读写路径上的读者见不到它们 —— 加进本表对那几处零变化。
+ * **为什么按码逐个登记、不按语义区段判**:MySQL 错误参考里这一族的 SQLSTATE 一律是 `HY000`(与一切未分类的服务端错误同一格,SQLSTATE 不分类);errno 也不成连续区段 ——
+ * 1821–1826 / 3734 / 3780 / 6125 之间夹着同族而**不属于**建表形不符的码(运行期的 1451 / 1452 / 3008、删列改列的 1828–1834、删父表的 3730),按区段或 `ER_FK_` 前缀判会把它们一并收进来;
+ * 而 mysql2 的码表是旧的(6125 没有符号,`code` 缺席),所以数字 `errno` 是必认的键。出处按码写在各行的 `why` 里:判据是码,不是散文。
+ * **唯一一行按内层号分:1005(建表被存储引擎拒)是包装码** —— 库答的消息模板 `Can't create table '%s' (errno: %d - %s)` 的**内层**号才是成因:150(外键形不成)/ 121(约束名已占)是确定拒,
+ * 28(盘满)等资源类清了盘重试即成。外层 SQLSTATE 恒 `HY000`、驱动不把内层号挂成字段 ⇒ 没有语义 / 结构化的键可判,只能读库自己的消息模板:这一行带 `innerErrnos`,
+ * 判据 = 外层码(`code` / `errno` 任一)是 1005 ∧ 消息是以 `Can't create table ` 开头、以 `(errno: <数字>…)` 收尾的整句 ∧ 内层号在 `innerErrnos` 里;读不出 / 不在册 /
+ * 外层不是这一码 ⇒ 不是(认不出一律不是;失败方向 = 进开库等待窗重试,不当场拒)。其余各行整码判、不读消息。
  *
  * 识别集 = 本表一张,按归因键登记:`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)、语法错(1064:多半是我方的语句,不是库的形)、
- * TiDB 自己的忙 / 区域不可用 / 结构变更冲突一族(9001 / 9005 / 8028,同连接类表的登记)、锁等待超时(1205)。
+ * TiDB 自己的忙 / 区域不可用 / 结构变更冲突一族(9001 / 9005 / 8028,同连接类表的登记)、锁等待超时(1205)、
+ * 外键的运行期拒(1451 / 1452 / 3008:行违反外键 / 级联深度,出在读写路径上、不是库的形)、`ER_FK_FAIL_ADD_SYSTEM`(1823:写系统表失败,成因混着字典写入失败而非逐因都是形不符 —— 推断,未读实现,故不登记)。
  */
 export declare const DEPLOYMENT_FAULT_ERRORS: ReadonlyArray<{
     readonly code: string;
     readonly errno?: number;
+    readonly innerErrnos?: readonly number[];
     readonly why: string;
 }>;
 /**
- * 「这个错误**是**部署错配类故障吗」—— {@link DEPLOYMENT_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
- * 只读被抛出的**这一只**对象身上的结构化字段(`code` 字符串 / `errno` 数字),不沿 `cause` 链找、不读散文里的在册词。
+ * 「这个错误**是**部署错配类故障吗」—— {@link DEPLOYMENT_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词;认不出的一律不是。
+ * 整码行只读被抛出的**这一只**对象身上的结构化字段(`code` 字符串 / `errno` 数字),不沿 `cause` 链找、不读散文里的在册词;唯一例外是包装码 1005:外层码在册之后还要读库自己的
+ * 消息模板里的内层号(头注),内层号不在册 / 读不出 ⇒ 不是。
  */
 export declare function isDeploymentFaultError(err: unknown): boolean;
+/**
+ * 库对一条语句的**答**里的原码,读成一小段(起服拒句读库答的唯一读法 —— `session-ext-table.ts` 的建表拒与 `store-backend.ts` 的开库拒同读这一只,不各写各的):
+ *  · MySQL 协议:`errno <数字> <符号>, SQLSTATE <五位>`(`errno` / `code` / `sqlState` 三格,哪一格不在就缺哪一格;mysql2 的码表没有新号时 `code` 缺席,只剩 errno;只有符号没有 errno ⇒ `code <符号>`);
+ *  · PostgreSQL:SQLSTATE 就挂在 `code` 上(node-pg),没有 errno / sqlState 键 ⇒ `SQLSTATE <五位>`。
+ * 只读被抛出的这一只对象身上的结构化字段、不读散文;每一格过闭字符形(数字 / `[A-Za-z0-9_]{1,64}` / 五位 SQLSTATE),形不对的格不进句子 —— 句子里不会出现驱动交来的任意串。
+ * 一格都读不到 ⇒ `undefined`(拒句不加这一段)。读字段经本文件同一只 `keyOf`(与本文件其余谓词同一读法:驱动错对象是普通对象,没有读取时才抛的访问器 / 代理那种形;真遇上就原样上抛,不在这里吞)。
+ */
+export declare function databaseAnswerCodesOf(dialect: SqlDialect, err: unknown): string | undefined;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -15,6 +15,15 @@ export function isPgUniqueViolation(err) {
 export function isDupKeyError(dialect, err) {
     return dialect === "mysql" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
 }
+const MYSQL_ER_DUP_ENTRY_SENTENCE = /duplicate entry/i;
+export function isDupKeyErrorOfWrappedQuery(dialect, err) {
+    if (isDupKeyError(dialect, err))
+        return true;
+    if (dialect !== "mysql")
+        return false;
+    const message = keyOf(err, "message");
+    return typeof message === "string" && MYSQL_ER_DUP_ENTRY_SENTENCE.test(message);
+}
 export const PG_UNDEFINED_COLUMN_SQLSTATE = "42703";
 export const MYSQL_ER_BAD_FIELD_ERRNO = 1054;
 export const MYSQL_ER_BAD_FIELD_CODE = "ER_BAD_FIELD_ERROR";
@@ -148,19 +157,58 @@ export const DEPLOYMENT_FAULT_ERRORS = [
     { 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`" },
-    { code: "ER_FK_INCOMPATIBLE_COLUMNS", errno: 3780, why: "MySQL 协议外键两侧列不相容(类型 / 字符集 / 排序规则对不上):被引表的形与外键要求不符,重试同一句仍不相容" },
-    { code: "ER_CANNOT_ADD_FOREIGN", errno: 1215, why: "MySQL 协议加不上外键(如被引表不是 InnoDB):库的形不收这条约束,改表之前重试注定失败" },
-    { code: "ER_FK_NO_INDEX_PARENT", errno: 1822, why: "MySQL 协议外键的被引列上缺索引:被引表的形不符,建索引之前重试注定失败" },
-    { code: "ER_CANT_CREATE_TABLE", errno: 1005, why: "MySQL 协议建表被存储引擎拒(errno 150 外键形不成 / 121 约束名已占 / 28 盘满):修库之前重试同一句仍被拒" },
+    { code: "ER_FK_INCOMPATIBLE_COLUMNS", errno: 3780, why: "MySQL 协议外键两侧列不相容(类型 / 字符集 / 排序规则对不上):被引表的形与外键要求不符,重试同一句仍不相容。出处:MySQL 9.0 错误参考 3780;TiDB `ErrFKIncompatibleColumns`" },
+    { code: "ER_CANNOT_ADD_FOREIGN", errno: 1215, why: "MySQL 协议加不上外键(统称码,如被引表不是 InnoDB):库的形不收这条约束,改表之前重试注定失败。出处:MySQL 9.0 错误参考 1215;TiDB `ErrCannotAddForeign`" },
+    { code: "ER_FK_NO_INDEX_CHILD", errno: 1821, why: "MySQL 协议外键的子表侧(建表句里的这张)缺索引:建表句的形不符,重试同一句仍被拒。出处:MySQL 9.0 错误参考 1821;TiDB `ErrFkNoIndexChild`;MariaDB 1800–1899 页同号" },
+    { code: "ER_FK_NO_INDEX_PARENT", errno: 1822, why: "MySQL 协议外键的被引列上缺索引:被引表的形不符,建索引之前重试注定失败。出处:MySQL 9.0 错误参考 1822;TiDB `ErrForeignKeyNoIndexInParent`;MariaDB 1800–1899 页同号" },
+    { code: "ER_FK_CANNOT_OPEN_PARENT", errno: 1824, why: "MySQL 协议外键的被引表打不开(库答「Failed to open the referenced table」;被引表不是 InnoDB 时 9.x 以此码拒,真库读数见 db 组钉):改引擎之前重试注定失败。出处:MySQL 9.0 错误参考 1824;TiDB `ErrForeignKeyCannotOpenParent`;MariaDB 1800–1899 页同号" },
+    { code: "ER_FK_INCORRECT_OPTION", errno: 1825, why: "MySQL 协议外键的选项在这张表上不成立(库答「Incorrect options in FOREIGN KEY constraint」):建表句的形不符,重试同一句仍被拒。出处:MySQL 9.0 错误参考 1825;TiDB `ErrFkIncorrectOption`;MariaDB 1800–1899 页同号" },
+    { code: "ER_FK_DUP_NAME", errno: 1826, why: "MySQL 协议外键约束名重复(库答「Duplicate foreign key constraint name」):改掉占用同名的那一只之前重试注定失败。出处:MySQL 9.0 错误参考 1826;TiDB `ErrFkDupName`;MariaDB 1800–1899 页同号" },
+    { code: "ER_FK_NO_COLUMN_PARENT", errno: 3734, why: "MySQL 协议外键的被引表上没有被引的那一列:被引表的形不符,补列之前重试注定失败。出处:MySQL 9.0 错误参考 3734;TiDB `ErrForeignKeyNoColumnInParent`" },
+    { code: "ER_FK_NO_UNIQUE_INDEX_PARENT", errno: 6125, why: "MySQL 协议外键的被引列上没有唯一键(库答「Missing unique key」;被引表无主键时 9.x 以此码拒,真库读数见 db 组钉):加主键 / 唯一键之前重试注定失败。出处:MySQL 9.0 错误参考 6125(mysql2 的码表没有这一号,驱动错的 `code` 缺席,按 errno 认;TiDB 无此号)" },
+    { code: "ER_CANT_CREATE_TABLE", errno: 1005, innerErrnos: [150, 121], why: "MySQL 协议建表被存储引擎拒(包装码,只认内层错误号 150 外键形不成 / 121 约束名已占:修库之前重试同一句仍被拒;28 盘满等资源类清盘后重试即成,不是确定拒,见头注)。出处:MySQL 9.0 错误参考 1005(消息模板 `Can't create table '%s' (errno: %d - %s)`,参考页注明消息里的 errno 150 = 外键形不成);TiDB `ErrCantCreateTable`" },
 ];
-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])));
+const WHOLE_CODE_ROWS = DEPLOYMENT_FAULT_ERRORS.filter((r) => r.innerErrnos === undefined);
+const DEPLOYMENT_FAULT_CODES = new Set(WHOLE_CODE_ROWS.map((r) => r.code));
+const DEPLOYMENT_FAULT_ERRNOS = new Set(WHOLE_CODE_ROWS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])));
+const INNER_DISCRIMINATED_ROWS = DEPLOYMENT_FAULT_ERRORS.flatMap((r) => (r.innerErrnos === undefined ? [] : [{ ...r, innerErrnos: r.innerErrnos }]));
+const CREATE_TABLE_REFUSAL_SENTENCE = /^Can't create table (?:`[^`]*`(?:\.`[^`]*`)?|'[^']*') \(errno: (\d{1,5})(?: [^()]*)?\)\s*$/;
+function engineInnerErrnoOf(err) {
+    const said = keyOf(err, "sqlMessage");
+    const text = typeof said === "string" ? said : keyOf(err, "message");
+    if (typeof text !== "string" || text.length > 2000)
+        return undefined;
+    const m = CREATE_TABLE_REFUSAL_SENTENCE.exec(text);
+    return m === null ? undefined : Number(m[1]);
+}
 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));
+    if ((typeof code === "string" && DEPLOYMENT_FAULT_CODES.has(code)) || (typeof errno === "number" && DEPLOYMENT_FAULT_ERRNOS.has(errno)))
+        return true;
+    const wrapper = INNER_DISCRIMINATED_ROWS.find((r) => (typeof code === "string" && code === r.code) || (typeof errno === "number" && errno === r.errno));
+    if (wrapper === undefined)
+        return false;
+    const inner = engineInnerErrnoOf(err);
+    return inner !== undefined && wrapper.innerErrnos.includes(inner);
+}
+export function databaseAnswerCodesOf(dialect, err) {
+    const code = keyOf(err, "code");
+    const symbol = typeof code === "string" && /^[A-Za-z0-9_]{1,64}$/.test(code) ? code : undefined;
+    if (dialect === "pg")
+        return symbol !== undefined && /^[0-9A-Z]{5}$/.test(symbol) ? `SQLSTATE ${symbol}` : undefined;
+    const errno = keyOf(err, "errno");
+    const sqlState = keyOf(err, "sqlState");
+    const parts = [];
+    if (typeof errno === "number" && Number.isInteger(errno))
+        parts.push(symbol !== undefined ? `errno ${errno} ${symbol}` : `errno ${errno}`);
+    else if (symbol !== undefined)
+        parts.push(`code ${symbol}`);
+    if (typeof sqlState === "string" && /^[0-9A-Za-z]{5}$/.test(sqlState))
+        parts.push(`SQLSTATE ${sqlState}`);
+    return parts.length === 0 ? undefined : parts.join(", ");
 }
 export class StoreRowTooLargeError extends Error {
     row;

package/dist/plugins/sql-json-column.d.ts

@@ -53,15 +53,16 @@ import type { SqlDialect } from "./sql-driver.js";
  */
 export declare function jsonColumnText(dialect: SqlDialect, column: string, member?: JsonColumnMember): string;
 /**
- * 一列 JSON 的**一个顶层成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树时用它,整只文档不出引擎。
- *  · `key` = 成员名(裸标识符;进 MySQL 路径 `'$.<key>'` 与 PG 字面 `'<key>'`,所以只认裸标识符,不转义不猜);
+ * 一列 JSON 的**一个成员**(NP-3,7.100.0)—— 读腿只要文档里的一棵子树 / 一格时用它,整只文档不出引擎。
+ *  · `path` = 自顶层往下的成员名(一段或多段,每段裸标识符;进 MySQL 路径 `'$.<a>.<b>'` 与 PG 链 `-> '<a>' -> '<b>'`,所以只认裸标识符,不转义不猜)。
+ *    一段 = 顶层成员(`["pendingAction"]`),多段 = 成员里的成员(`["state", "rowTaskId"]`);一段的产物与多段形之前的写法逐字节同;
  *  · `as` = 行上的键(**小写**裸标识符:PG 把不带引号的别名折成小写,别的拼法会让两方言的行键不同)。
- * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),成员缺席 / 文档不是对象 ⇒ SQL NULL(两引擎同答),
- * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这棵子树」,JSON `null` 字面 = 一个值(交形读者判)。
- * 首个读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)只取 `pendingAction`。
+ * 产物仍是**文本**(同一条「按文本投影、恰好解一次」),路径上任一段缺席 / 不是对象 ⇒ SQL NULL(两引擎同答),
+ * 所以读腿用 {@link decodeNullableJsonColumn}:NULL = 「这份文档没有这一格」,JSON `null` 字面 = 一个值(交形读者判)。
+ * 读者:`checkpoint-store-sql.ts` 的 `listPending`(运维队列 / `/v1/approvals/stream` 热读)与 `one-time-migrations.ts` 的 M21。
  */
 export interface JsonColumnMember {
-    readonly key: string;
+    readonly path: readonly [string, ...string[]];
     readonly as: string;
 }
 /**
@@ -82,7 +83,7 @@ export interface JsonColumnMember {
  * 子树,本函数的插值对它是一个不透明表达式。所以「误用进 SELECT 投影且没给别名」这一形没有机器门 ——
  * 误用的落点是真库上当场的 `SqlJsonColumnError("not-text")` 响亮抛(行上没有那个键 ⇒ `undefined`),不是静默。
  */
-export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberKey?: string): string;
+export declare function jsonColumnTextExpr(dialect: SqlDialect, column: string, memberPath?: JsonColumnMember["path"]): string;
 /**
  * 一列 JSON 的**投影文本的 sha256**(十六进制小写,引擎内算 —— 整只文档不出库),带别名。输入恰是 {@link jsonColumnTextExpr} 那一只投影:
  * 同一行、同一次读里,本表达式的摘要就是 {@link jsonColumnText} 交给读腿的那串字节的摘要,于是「字节没变 ⇒ 摘要没变」只有一种读法。

package/dist/plugins/sql-json-column.js

@@ -6,19 +6,23 @@ export function jsonColumnText(dialect, column, member) {
     if (!MEMBER_ALIAS_RE.test(member.as)) {
         throw new Error(`jsonColumnText: member alias ${JSON.stringify(member.as)} must be a lower-case bare identifier — PostgreSQL folds unquoted aliases to lower case, so any other spelling would give the two dialects different row keys`);
     }
-    return `${jsonColumnTextExpr(dialect, column, member.key)} AS ${member.as}`;
+    return `${jsonColumnTextExpr(dialect, column, member.path)} AS ${member.as}`;
 }
 const MEMBER_ALIAS_RE = /^[a-z_][a-z0-9_]*$/;
-export function jsonColumnTextExpr(dialect, column, memberKey) {
+export function jsonColumnTextExpr(dialect, column, memberPath) {
     if (!COLUMN_NAME_RE.test(column)) {
         throw new Error(`jsonColumnTextExpr: ${JSON.stringify(column)} is not a bare column identifier — refusing to splice it into SQL text`);
     }
-    if (memberKey === undefined)
+    if (memberPath === undefined)
         return dialect === "pg" ? `${column}::text` : `CAST(${column} AS CHAR)`;
-    if (!COLUMN_NAME_RE.test(memberKey)) {
-        throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(memberKey)} is not a bare identifier — refusing to splice it into a JSON path`);
+    for (const segment of memberPath) {
+        if (!COLUMN_NAME_RE.test(segment)) {
+            throw new Error(`jsonColumnTextExpr: member ${JSON.stringify(segment)} is not a bare identifier — refusing to splice it into a JSON path`);
+        }
     }
-    return dialect === "pg" ? `(${column}::jsonb -> '${memberKey}')::text` : `CAST(JSON_EXTRACT(${column}, '$.${memberKey}') AS CHAR)`;
+    return dialect === "pg"
+        ? `(${column}::jsonb ${memberPath.map((segment) => `-> '${segment}'`).join(" ")})::text`
+        : `CAST(JSON_EXTRACT(${column}, '$.${memberPath.join(".")}') AS CHAR)`;
 }
 export function jsonColumnTextSha256(dialect, column, as) {
     if (!MEMBER_ALIAS_RE.test(as)) {

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

@@ -1,10 +1,14 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { SessionStore, SessionPolicyStore, FileHistoryStore, FileHistoryBlobExchange, FileHistoryError, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
+import { FileStorageBackend } from "@sema-agent/core";
 import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
-import { type OneTimeMigrationReport } from "./one-time-migrations.js";
+import { type RunStallWiring } from "./store-contracts.js";
+import { type StoreOpenLane } from "./store-open-refusal.js";
+import { type OneTimeMigrationReport, type SqlOneTimeMigrationInput } from "./one-time-migrations.js";
+import { LocalSessionStore } from "./local-session-store.js";
 import type { LocalSessionRows } from "./local-session-window.js";
 import type { SessionHeadReader } from "./caching-session-store.js";
 import { LocalCheckpointStore } from "./local-checkpoint-store.js";
@@ -34,7 +38,7 @@ import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
 import { type AdoptionLogStore } from "./adoption-log-sql.js";
 import { type SqlTransactionHooks } from "../stores-sql/retention-store-sql.js";
-import type { EndedSpace } from "../workspace-space.js";
+import type { SessionEraser } from "../session-erase.js";
 import { type RetentionDestructiveInput, type RetentionExecutor, type RetentionExecutorOptions } from "./retention-deployment.js";
 import { type RetentionLaneStore } from "./retention-lane-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
@@ -43,12 +47,23 @@ import { type StoreDegradedReason } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
 export type BootLogSink = (msg: string, meta?: Record<string, unknown>) => void;
+/**
+ * 后端交给店的**观测座**(加项、可缺席:嵌入方 / 测试不给 ⇒ 不计数)。今天一格:run 店每落下 n 条死亡判决(收割器 / 观察口 / 认领冲突同一只)
+ * ⇒ `runStallVerdicts(n)`(生产装配 = `runs_reaped_total{kind:"stale"}`,`boot/stores.ts`)。
+ */
+export interface StoreBackendObservers {
+    readonly runStallVerdicts?: (landed: number) => void;
+}
+/** run 店落死亡判决的两样:窗 = 后端持有的配置对象的 `runStaleSec`(热发布原地改写 ⇒ getter 读到热值;判活窗只有这一个来源)+ 计数座。 */
+export declare function createRunStallWiring(config: Pick<ServiceConfig, "runStaleSec">, observers: StoreBackendObservers | undefined): RunStallWiring;
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
 /** E18 resume-at eventId→entryId anchor map — tidb/pg/local 3-backend (works LOCAL; needs only the session tree +
  *  this map, no cloud-only checkpoint). Union = the three nominal twins; consumers use put/resolve/deleteBySession.
  *  FileResumeAnchorStore is the FILE-backed local twin (P0.5 variant-1; survives restart). */
 export type ResumeAnchorStore = TiDBResumeAnchorStore | PgResumeAnchorStore | FileResumeAnchorStore;
 export type { ApprovalExemptionStore } from "./approval-exemption-store.js";
+/** 会话树根的写(事务内钩的写闭集,`stores-sql/session-write-hooks.ts`):本组合座转口给目录外的判官(`execution-placement.ts` 的 `judgeSessionWrite`;local 店的写锁内同一组词)。 */
+export type { SessionWrite } from "../stores-sql/session-write-hooks.js";
 export type { ApprovalNonceStore } from "./approval-nonce-store.js";
 /** [ref]([ref] v3.1 §3.0-§3.2 流内审批协议持久层):`ApprovalAskStore` 接口 + 行/补丁类型。
  *  车3 刀 3a 起 `StoreBackend.approvalAsk()` 已在(见接口体的那条注)。 */
@@ -160,7 +175,7 @@ export type SessionCaptureRecordSource = (plane?: {
 }) => SessionCaptureRecordStore;
 export interface StoreBackend {
     /** Protocol-truth kind (clay 2026-07-06 wording): "mysql" = any MySQL-protocol server (MySQL / TiDB /
-     *  MariaDB) behind the one mysql2 pool — the startup summary prints durable(mysql) for all of them. */
+     *  MariaDB) behind the one mysql2 pool — the startup summary prints `mysql` for all of them. */
     readonly kind: "mysql" | "pg" | "local";
     /** Connect + create schema (also the reachability probe). On the SQL backends it first checks the database for the
      *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
@@ -229,7 +244,7 @@ export interface StoreBackend {
     userInputLedger(): UserInputLedgerStore;
     /** E6 durable SessionPolicyStore (operator-tightened per-session tool rules). REQUIRED on all backends — works local
      *  (local = core's FileSessionPolicyStore), like resumeAnchor. Backs core's RunnerDeps.sessionPolicyStore.
-     *  `logger`:SQL 孪生抹除封键那一臂([ref])的点名口(缺席 ⇒ 店退回 `console.warn`);local(core 的 File 店)不收。 */
+     *  `logger`:SQL 孪生抹除封键那一臂([ref])的点名口(装配点缺省交日志出口接缝的 logger);local(core 的 File 店)不收。 */
     sessionPolicy(logger?: SessionPolicyStoreLogger): ServiceSessionPolicyStore;
     /** [ref] per-edited-file rewind FileHistoryStore (trackEdit/annulTrack/snapshot/restore over the tracked set;
      *  also the 2c history-transfer store). REQUIRED on all backends (local = core's file-backed
@@ -371,6 +386,11 @@ export interface StoreBackend {
      * `retention-deployment.ts` 的 `RetentionExecutorOptions`)。组合形见 {@link createSqlRetentionExecutor}。
      */
     retention?(opts: RetentionExecutorOptions): RetentionExecutor;
+    /**
+     * 删净一只会话的**执行体**(`session-erase.ts` 的 `SessionEraser`;在线删除协调器调它)—— 与 {@link retention} 的会话树清扫同一段事务体(组合 `createSqlSessionEraser`)。
+     * **SQL 后端专有**:local 的执行体是会话店写锁一节(`session-erase.ts` 的 `createLocalSessionEraser`),各店在 boot 里才齐,由删除协调器自己组。
+     */
+    sessionEraser?(opts: RetentionExecutorOptions): SessionEraser;
     /**
      * [ref] 车2 —— 留存执行面的**非破坏性**半场:sweep 租约、legal-hold 的放置/解除、审计表的读与
      * 非破坏行的写。同样 SQL 专有(它写的三张表只在 SQL schema 里)。
@@ -408,29 +428,39 @@ export interface StoreBackend {
     fileUsageWindowStore?(): UsageWindowStore;
 }
 /**
- * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十一张部署表,
+ * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
  * `plugins/retention-deployment.ts`,经 K4 事务内钩参与同一事务)。
  *
  * 破坏性三方法**每次调用**铸一只执行器、钩表绑这一次调用(`createRetentionDeploymentHooks` 的头注:审计行的判定时点三格与
- * `checkpoint_ctx` 属主门的域是这一次调用的事实)。会话树删除的 `endedSpaces` 由部署从 `beforeDelete` 收到的行自算,
+ * `checkpoint_ctx` 属主门的域是这一次调用的事实)。会话树删除的 `erased`(交收尾的那一份)由执行器的行面回执 + 部署收集的附件哈希拼成,
  * 只在执行器**提交成功返回之后**挂上回执(回滚 ⇒ 执行器抛,不挂)。非破坏两口(域枚举 / 预览)不经钩。
  */
 /**
  * 一次破坏性调用的整张事务内钩表:部署的 `retention` 组(按这一次调用铸,`createRetentionDeploymentHooks`)+ 会话座的钩
- * (`createSqlSessionWriteHooks`,会话店用的同一只工厂;留存删除走它的 `retention-delete` 臂)。`endedSpaces` 读部署那一半收到的行。
+ * (`createSqlSessionWriteHooks`,会话店用的同一只工厂;留存删除走它的 `retention-delete` 臂)。`attachmentShas` 读部署那一半收到的行。
  */
 export declare function createSqlRetentionCallHooks(db: SqlDriver, opts: RetentionExecutorOptions, input: RetentionDestructiveInput): {
     readonly hooks: SqlTransactionHooks;
-    endedSpaces(): readonly EndedSpace[];
+    attachmentShas(): readonly string[];
 };
 export declare function createSqlRetentionExecutor(db: SqlDriver, opts: RetentionExecutorOptions): RetentionExecutor;
+/**
+ * **删净一只在删会话的 SQL 执行体**(`session-erase.ts` 的 `SessionEraser`):执行器的 `eraseSession` —— 与留存清扫同一段会话树事务体,前面是锁行 + 属主 +
+ * 会话座事务内钩的 `erase` 判(这一行处于这只令牌的在删态)。行不在 / 属主不是那一位 / 令牌不是它(`SessionDeletionSupersededError`)⇒ `superseded`,别的拒原样抛。
+ * 部署行那一半用与留存同一只钩(`createSessionRowsHook`,域 = 围栏判过的属主),附件哈希随回执交收尾。
+ * `opts` 与留存执行器同一份(附件 / 任务清单两张表在不在是 boot 的事实)。
+ */
+export declare function createSqlSessionEraser(db: SqlDriver, opts: RetentionExecutorOptions): SessionEraser;
 /** (c)(clay 拍 a+c,2026-07-27;[ref] 换店后域=file_history_blob,门与旋钮名不变)云形 blob 姿势门——
- *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形已被两役
+ *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形,mysql 腿已被两役
  *  实证撞 mysql-协议包墙(D-1 附件 → 对象存储裁定):大字节归对象存储。per-file 历史的 blob=单文件
  *  字节,同一堵墙(>6MiB 的被 track 文件在 TiDB 上落不进 SQL 行 ⇒ trackEdit 拒 ⇒ 默认 DV-14 下该次
- *  编辑被拒)。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
- *  显式接受 SQL 店 + per-blob 帽(单机/测试台形)。local 后端不经此门(file 店,无 SQL 包墙)。 */
+ *  编辑被拒);pg 腿本服务不建模这两堵墙(只有一个 bytea 值的 1 GB 硬上限、没有推出来的缺省帽),同一条裁定、拒句只说各自方言的事实
+ *  ({@link SQL_BLOB_POSTURE_FACTS})。云形缺 MinIO ⇒ fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` =
+ *  显式接受 SQL 店 + per-blob 帽(单机/测试台形;pg 上帽只来自 `SNAPSHOT_BLOB_SQL_MAX_BYTES`)。local 后端不经此门(file 店,无 SQL 包墙)。 */
 export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "local", config: Pick<ServiceConfig, "snapshotBlobStore" | "snapshotBlobAllowSql">): void;
+/** SQL 一次性迁移段的输入(两只 SQL 后端同一份;各条目那一半的来源见 `SqlOneTimeMigrationInput`):M32 的车道表 · M40 的判活窗 = 收割器的同一个窗 · M48 的部署形读数(表里那一行)。 */
+export declare function buildSqlOneTimeMigrationInput(config: ServiceConfig): SqlOneTimeMigrationInput;
 /**
  * LOCAL backend (clay 2026-06-25 seamless local↔cloud; P0.5 variant-2 + variant-1 file-backed 2026-06-26): a DB-less StoreBackend
  * so a locally-run HTTP service serves the SAME contract a cloud worker does (runs + trace + sessions + resume;
@@ -461,6 +491,8 @@ export declare function assertCloudSnapshotBlobPosture(kind: "mysql" | "pg" | "l
  * projection and its log export — and `undefined` on any other backend. The one place that answers "is there a local store to read rows from".
  */
 export declare function localSessionRowsOf(backend: StoreBackend | undefined): LocalSessionRows | undefined;
+/** local 车道的客户端写计数口(附件店绑定时计数,`session-birth.ts`):本地后端那一只会话店;别的后端 ⇒ `undefined`(SQL 附件店在自己的认领事务里计数)。 */
+export declare function localClientWritesOf(backend: StoreBackend | undefined): Pick<LocalSessionStore, "withClientWrite"> | undefined;
 /**
  * 启动日志里「跨副本 or 进程内」那一格的标签。
  *
@@ -474,6 +506,38 @@ export declare function localSessionRowsOf(backend: StoreBackend | undefined): L
  * 而兄弟行都写 `shared(${kind})`。)
  */
 export declare function counterStoreLabel(store: unknown, kind: string | undefined): string;
+/**
+ * 打开 local 数据根的那一只后端(打开成功的 {@link LocalBackend} 或打开那一刻被拒的 {@link RefusedLocalBackend}):`StoreBackend` 之外多一只口 ——
+ * 引擎 File 后端上**会话店之外**本仓没有自己一份的那几只店({@link LocalEngineFileStores};run-local 的 Runner 接它们)。会话行店不在其中:行只经本仓的会话店读(`session()`)。
+ */
+export interface LocalStoreBackend extends StoreBackend {
+    readonly kind: "local";
+    engineFileStores(): LocalEngineFileStores;
+    /** local 后端恒有(引擎 File 后端的工具结果店;接口上可选的那一口在这里必在)。 */
+    toolResult(): ToolResultStoreFull;
+    /** local 后端恒有(引擎 File 后端的用量窗账本;接口上可选的那一口在这里必在)。 */
+    fileUsageWindowStore(): UsageWindowStore;
+}
+/** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
+export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;
+/** 打开 local 数据根的入口参数:哪条路在开(只决定拒句的措辞 —— 表头与「换根」半句)与三只 boot 期日志座(见 {@link createStoreBackend})。 */
+export interface LocalBackendOpenOptions {
+    readonly lane: StoreOpenLane;
+    readonly onWarn?: BootLogSink;
+    readonly onError?: BootLogSink;
+    readonly observers?: StoreBackendObservers;
+}
+/**
+ * **local 后端打开数据根**(唯一的路 —— 本仓每一条打开 local 数据根的入口都经它:`createStoreBackend` 的 local 腿(HTTP 服务)与 run-local;一个数据根一只会话行店、一份装配):
+ * 取锁(引擎 File 后端)→ **判与抬引擎版本高水位**({@link holdEngineHighWater},同步一段;判前钩 = 判或记收令牌欠账 {@link holdArchiveTokenAdoptionDuty},抬之前)→ 本仓的店。
+ * 打开之后的公开序列两条入口相同:`ensureSchema()`(起服对账)→ `runOneTimeMigrations()` → 才读会话。
+ * 判与抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
+ * 判必须先于它们(被拒 = 本仓的店一只都没开、不抬、不改既有文件的字节;判拒发生在钥匙对与空账本已落、店尚未开之后;下一版改为判拒先于任何写),抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
+ * 拒(判拒 / 本构建版本读不出 / 抬写不进 / 本仓的店构造时抛)⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒(公开序列在它该在的那一步拒,降级臂按拒的族判),
+ * `close()` 只放锁 —— 没有店、没有收尾写。
+ * 残余(如实):引擎 `FileStorageBackend` 的构造把取锁与它自己的店放在同一步(建子目录、店目录锁、撕裂账本尾的收拢)—— 那几笔在判之前,本仓在两者之间没有座(要 core 给)。
+ */
+export declare function openLocalBackend(config: ServiceConfig, opts: LocalBackendOpenOptions): LocalStoreBackend;
 /** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily); the next
  *  step is `ensureSchema()` (retired-schema check, then the CREATEs; it is also the reachability probe), then
  *  `runOneTimeMigrations()`. Returns undefined when no DB is configured.
@@ -484,7 +548,9 @@ export declare function counterStoreLabel(store: unknown, kind: string | undefin
  *  `onError` (additive, optional; F-D) is the **error-level** twin of that seat — 件6 的
  *  `file_run_store_hydrate_unreadable` 按成文承诺是 error 级,warn 座满足不了那句话。两座都是**加项**:
  *  既有一/二参调用方逐字不变(缺席 ⇒ 该披露退回 warn 座 / 只剩 fail-open 遥测那一半)。 */
-export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootLogSink, onError?: BootLogSink): StoreBackend | undefined;
+export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootLogSink, onError?: BootLogSink, observers?: StoreBackendObservers): StoreBackend | undefined;
+/** local 后端的数据根(`createStoreBackend` 交给 `LocalBackend` 的那一只,与 {@link openStoreBackendWithFallback} 的降级判据、起服第 2 段的持久性取证读同一只)。 */
+export declare function localBackendRootOf(config: Pick<ServiceConfig, "localDataRoot">): string;
 /** boot 期打开 store 后端的**统一入口**:构造 + ensureSchema 同罩一层降级臂。
  *
  *  为什么必须把 `createStoreBackend()` 也罩进来(2026-07-28 修):clay 1.292 拍的口径是「裸 boot
@@ -507,7 +573,7 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
 export declare function openStoreBackendWithFallback(config: ServiceConfig, logger: {
     warn: (msg: string, meta?: Record<string, unknown>) => void;
     error?: (msg: string, meta?: Record<string, unknown>) => void;
-}): Promise<{
+}, observers?: StoreBackendObservers): Promise<{
     backend: StoreBackend | undefined;
     degradedReason: StoreDegradedReason | undefined;
 }>;
@@ -521,8 +587,11 @@ export declare function openStoreBackendWithFallback(config: ServiceConfig, logg
 export declare function sqlStoreCoordinatesAsUrl(config: Pick<ServiceConfig, "dbBackend" | "tidb" | "pg">): string;
 /**
  * SQL 族「配了 DSN 而店打不开(窗内重试过了)」的拒启句(唯一铸点)。点名 `DB_BACKEND=<引擎>`、库的显示安全形(`postgres://host:port` / `mysql://host:port`,经 {@link sqlStoreCoordinatesAsUrl} 拼出、再过 {@link buildDisplaySafeUrl},
- * 不带口令)、等了多久,出路两条:修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`);或**显式**内存部署(`DB_BACKEND=memory`)。🔴 没有第三条
- * 「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令)。
+ * 不带口令)、等了多久,出路按**失败类**走(判官 = 整仓一只的 {@link isDeploymentFaultError}),都含**显式**内存部署(`DB_BACKEND=memory`):
+ *  · 库**确定拒**了一条语句(部署错配类:缺表 / 权限拒 / 建外键被拒 …)⇒ 等与改坐标都改变不了答案,出路是库里被点名的那一件(表引擎 / 主键 / 外键相容 / 授权);拒句带库答的 errno / SQLSTATE 原码
+ *    ({@link databaseAnswerCodesOf});
+ *  · 其余(连不上 / 超时 / 认不出)⇒ 修坐标 / 连通性(窗是 `STORE_LOCK_WAIT_MS`)。
+ * 🔴 没有第三条「`SESSION_BACKEND=auto` 内存起服」—— 那一条就是被删掉的静默降级。驱动原文只取 message(与修前 `fatalExit` 打出的同一句),凭据不在其中(驱动不回显口令);原码段只经闭字符形读取。
  */
 export declare function buildSqlStoreOpenRefusal(engine: "mysql" | "pg", endpoint: string, waitedMs: number, err: unknown): string;
 //# sourceMappingURL=store-backend.d.ts.map