@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/shell-sentinel-owner-m48.d.ts

@@ -0,0 +1,42 @@
+import type { SqlDialect } from "./sql-driver.js";
+/**
+ * 一次性迁移 **M48** 的唯一属主(窗、删法与删后谁接住:窗口见 `plugins/one-time-migrations.ts` 登记表;随 M48 删整个文件)。
+ *
+ * cli ≤ 1.0.70 在本地单用户形下对每次请求自发主体头 `anon:shell-live`,于是那段时间写下的会话行 / run 行 / leader run 行的属主列是这一个字面量
+ * (不是真租户键:它与「不带主体的同一位本地用户」是同一个人的两种写法)。此前属主面表为它留了一格按字面量互认的资格;
+ * 本版起这一格退役 —— 存量行由本迁移改写成无主(`null`),之后它们与任何无主行同读(普通无主行一格),属主读法里不再有字面量。
+ *
+ * **改写的部署形**:「哨兵 ≡ 不带主体的本地单用户」只在没有身份边界的部署(dev-open)上成立 ⇒ 改写只在那里执行。判据 = 部署形表行 `identityBoundary`(只读配置:
+ * `REQUIRE_PRINCIPAL`、service 凭据、鉴权桥 issuer —— 含中心回退、直连门、只读 trace 凭据,任一在 ⇒ 有边界),dev-open 判据 `devOpenDeployment` 读同一行。
+ * 有身份边界的部署上哨兵是一位普通的具名属主,行只对字面相等的主体可见;改成无主 = 过了凭据门的任何主体都够得着 ⇒ 那里零改写、读数 0,行原样(本条照样记完成)。
+ * 读数由调用方读部署形表交进迁移段(`one-time-migrations.ts` 的 `ShellSentinelOwnerInput`),两条腿同读。
+ *
+ * 改写面 = 曾放那一格的读面读属主的那几处:SQL `session_meta` / `task_run` / `leader_run` 的 `owner` 列;local 会话元数据边档那一格的 `owner`、
+ * `FileRunStore` 的 run 行 `owner`(local 没有 leader run 店)。不改的(如实):规则行(存在哨兵键下的规则此前也不对无主体任务生效,改键 = 放宽,不做)、
+ * 收件箱条目 / 问账行 / 检查点 scope(这些读面从没放过那一格)。
+ *
+ * **有身份边界的部署不改写,但不零信号**:部署形读数取自**起服的那一个进程**的配置,而改写落在整只库 / 数据根上、不可逆 ⇒ 同一只库 / 根被身份配置不同的进程打开
+ * (`run-local` 不带服务凭据 / 桥、嵌入方先于验签器装配的起服序列、连着共享库的临时进程)时,一样身份键都不带的那个进程先起,会替有边界的服务进程把行改成无主(边界是任一身份来源在的并 —— 改写只在一样都没有时发生)。
+ * 有边界的进程自己只看见「零改写」,不数一数就不知道库里还留着多少行 ⇒ 那一臂对**同一批改写面**用**同一个比较**数一遍(不写,不改),读数 {@link ShellSentinelOwnerRowsRetained}
+ * 逐面列非零的计数,起服日志一行 warn(`shell_sentinel_rows_retained`)。比较只有一份:SQL 的 {@link shellSentinelOwnerWhereM48}(改写的 `UPDATE` 与计数的 `SELECT COUNT(*)` 共用),
+ * local 的 {@link isShellSentinelOwnerM48}(会话元数据格与 run 行的改写和计数共用)。
+ */
+export declare const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
+/** SQL 腿改写 `owner` 列的表(曾放那一格的读面读属主的表;local 腿的对应面见文件头)。 */
+export declare const SHELL_SENTINEL_OWNER_TABLES_M48: readonly ["session_meta", "task_run", "leader_run"];
+/** 改写面的词(留存读数与日志的逐面计数键):SQL = 表名;local 腿借同一组词 —— `session_meta` = 会话元数据格、`task_run` = run 行(local 没有 leader run 店 ⇒ 不出 `leader_run`)。 */
+export type ShellSentinelOwnerSurfaceM48 = (typeof SHELL_SENTINEL_OWNER_TABLES_M48)[number];
+/** 留存读数的一只:有身份边界的部署上,这一面还留着多少行哨兵属主(只列非零的面)。 */
+export interface ShellSentinelOwnerRowsRetained {
+    readonly surface: ShellSentinelOwnerSurfaceM48;
+    readonly rows: number;
+}
+/**
+ * SQL 腿「这一行是哨兵属主」的比较(**唯一一份**;改写的 `UPDATE … SET owner = NULL WHERE <此>` 与留存计数的 `SELECT COUNT(*) … WHERE <此>` 共用,绑定参数同为 {@link SHELL_SENTINEL_OWNER_M48})。
+ * 值**逐字节**比:MySQL 协议的 `utf8mb4_bin` 是 PAD SPACE(`'a' = 'a '`),普通等值会把只差尾空格的另一位属主(合法主体名)也当哨兵 ——
+ * 与 M17 / M18 的 CAS 同一写法 `CAST(… AS BINARY)`;PG `text` 等值本就逐字节。
+ */
+export declare function shellSentinelOwnerWhereM48(dialect: SqlDialect): string;
+/** local 腿「这一行 / 格的属主是哨兵」的比较(**唯一一份**;会话元数据格与 run 行的改写、留存计数共用 —— 严格相等,与 SQL 腿的逐字节比同义)。 */
+export declare function isShellSentinelOwnerM48(owner: string | null | undefined): boolean;
+//# sourceMappingURL=shell-sentinel-owner-m48.d.ts.map

package/dist/plugins/shell-sentinel-owner-m48.js

@@ -0,0 +1,9 @@
+export const SHELL_SENTINEL_OWNER_M48 = "anon:shell-live";
+export const SHELL_SENTINEL_OWNER_TABLES_M48 = ["session_meta", "task_run", "leader_run"];
+export function shellSentinelOwnerWhereM48(dialect) {
+    return dialect === "mysql" ? "CAST(owner AS BINARY) = CAST(? AS BINARY)" : "owner = $1";
+}
+export function isShellSentinelOwnerM48(owner) {
+    return owner === SHELL_SENTINEL_OWNER_M48;
+}
+//# sourceMappingURL=shell-sentinel-owner-m48.js.map

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -20,7 +20,8 @@
  *    `workspace` = k8s 车道的 `config.remoteExec.s3Snapshot.bucket`(`WORKSPACE_SNAPSHOT_BUCKET`,缺省 `workspaces`)—— 车道没开 / 没配对象存储 ⇒ 没有这只桶,不核。
  *    拒句的旋钮名跟着桶走(缺的是哪只桶就只点哪只的旋钮)。公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
  *  · 运行期的对应臂:工作区 `latest` 指针读答 404 `NoSuchBucket`(同一条「桶不在」判据 `isNoSuchBucketAnswer`)⇒ 那条 run 响亮拒绝,不再读成「空间头一回」
- *    (`remote-env-k8s.ts` `readPointer`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
+ *    (`remote-env-k8s.ts` `readPointer`);恢复时归档 GET 答同一只 404 `NoSuchBucket`(pod 原样交回存储的答复,同一只判据读)⇒ 两条车道同拒、同一行
+ *    (`restoreSnapshot`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
  */
 import type { ServiceConfig } from "../config-types.js";
 import { type StoreOpenWaitClock } from "./store-open-wait.js";

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

@@ -115,7 +115,7 @@
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { Logger } from "../observability/logger.js";
+import { type Logger } from "../observability/logger.js";
 /**
  * SQL **文本**的语法族(调用方说,不探):`mysql` = MySQL 协议(TiDB / MySQL InnoDB / MariaDB 同一套语句),`pg` = PostgreSQL。
  * 与 `@sema-agent/core-stores-sql` 公面的 `SqlDialect` 同词同集 —— 部署词 / 引擎词都不是它的别名:谁在答是另一轴 {@link SqlEngine}(驱动探)。

package/dist/plugins/sql-driver.js

@@ -1,6 +1,7 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
+import { writeLogText } from "../observability/logger.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
 export class SqlStatementDeadlineExceeded extends Error {
     deadlineMs;
@@ -229,7 +230,7 @@ async function establishSession(session, pooled, c, init) {
         session.facts = null;
         session.connections = new WeakMap();
         if (stale !== null)
-            console.warn(`[sql-driver] connection initialization REFUSED — SQL engine facts invalidated (was: ${stale ? `${stale.engine} ${stale.version} ${stale.isolation} txnMode=${stale.txnMode ?? "-"}` : "<absent>"}). GET /v1/diagnostics/wiring -> sqlEngine and GET /v1/capabilities -> sql now report ABSENT, which is the honest ` +
+            writeLogText("stderr", `[sql-driver] connection initialization REFUSED — SQL engine facts invalidated (was: ${stale ? `${stale.engine} ${stale.version} ${stale.isolation} txnMode=${stale.txnMode ?? "-"}` : "<absent>"}). GET /v1/diagnostics/wiring -> sqlEngine and GET /v1/capabilities -> sql now report ABSENT, which is the honest ` +
                 `reading: this pool cannot currently establish the read semantics every "SELECT … FOR UPDATE" in this repo assumes. Cause: ${err.message}`);
         c.release();
         throw err;

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/stop-then-start-sentence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 「停-迁-起」那一段的**唯一属主**。
+ *
+ * 一次性迁移里有几条(登记表 `stopThenStart` 一格点名的)改的是更早版本的副本还会继续写的形:改完之后它再写一笔,这一笔读不出 / 丢掉。它们没有运行期开关,
+ * 起服时由守卫判 —— 判活窗内(`REAP_RUN_STALE_SEC`,收割器判 run 持有者还活着的同一个窗)库里还有 `running` run 在心跳 ⇒ 拒启、一字节不写。
+ * 四只守卫(M40 · M41 · M42 · M51)的拒句和起服列册对账的升级清单**说同一件事**:先停光更早版本的副本、等满判活窗、再起本版。
+ * 这件事的句子只在这里写一遍;各守卫只讲「为什么这一条要停」,不各抄一份动作段。
+ *
+ * 叶子模块:零 import(守卫所在的一次性迁移文件、M42 的拒句文件与列册对账都静态 import 它,不成环)。
+ */
+/**
+ * 动作段:停光 → 等窗 → 再起。`after` = 全停之后可以再起的最早时刻(守卫读到的最新心跳 + 判活窗,人读形);
+ * 缺席 ⇒ 读不到具体心跳(列册对账的清单:此刻没有守卫在判),只说「等满判活窗」。
+ */
+export declare function stopThenStartAction(after?: string): string;
+//# sourceMappingURL=stop-then-start-sentence.d.ts.map

package/dist/plugins/stop-then-start-sentence.js

@@ -0,0 +1,7 @@
+export function stopThenStartAction(after) {
+    return ("Stop every replica of the earlier version, then start this version (stop, migrate, start — this release cannot be rolled across replicas of both versions). " +
+        (after === undefined
+            ? "Wait out the heartbeat window (REAP_RUN_STALE_SEC) after the last replica stops, then start this version."
+            : `If every replica is already stopped, those are the runs they left behind: start this version again after ${after}`));
+}
+//# sourceMappingURL=stop-then-start-sentence.js.map

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

@@ -1,10 +1,15 @@
 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 LocalStoreDeclaration } from "../local-store-declaration.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,21 +39,37 @@ 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 LocalDataRootAdmission } from "./local-data-root-admission.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import { type SqlDriver } from "./sql-driver.js";
-import { type StoreDegradedReason } from "../store-posture.js";
+import { type StoreDegradedReason, type StoreDurability as MediumDurability } 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;
+}
+/** 开店时递进来的起服事实(只 local 腿读):数据根介质的判定(起服第 2 段的取证;缺席 = 这条入口没有起服证据 ⇒ 按 `unknown` 读 —— 判不出的介质不放宽 local 店的声明)。 */
+export interface StoreOpenFacts {
+    readonly dataRootMedium?: MediumDurability;
+}
+/** 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 +181,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 +250,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 +392,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 里)。
@@ -406,31 +432,43 @@ export interface StoreBackend {
      *  拒绝句不带盘上位置)的同时,路径进本 backend 的 `file_store_corrupt_read` 披露座(逐命中 warn)。修前 `boot/stores.ts` 在同一数据根上自己
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
+    /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
+    localStoreDeclaration?(): LocalStoreDeclaration;
 }
 /**
- * 托管留存执行器的**组合**:引擎座表那一半(`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 +499,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 +514,44 @@ 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;
+    /** local 后端恒有(构造时交给两半店的声明;接口上可选的那一口在这里必在)。 */
+    localStoreDeclaration(): LocalStoreDeclaration;
+}
+/** 引擎 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;
+    /** 这只根的数据根准入读数(必填;{@link admitLocalDataRoot} 铸,调用方在它对这只根的第一笔写之前取 —— 打开就是第一笔写的调用方当场取,见 {@link createStoreBackend})。 */
+    readonly admission: LocalDataRootAdmission;
+    readonly onWarn?: BootLogSink;
+    readonly onError?: BootLogSink;
+    readonly observers?: StoreBackendObservers;
+    /** 起服事实(数据根介质的判定;HTTP 服务递第 2 段的取证,缺席 ⇒ `unknown`)。 */
+    readonly facts?: StoreOpenFacts;
+}
+/**
+ * **local 后端打开数据根**(唯一的路 —— 本仓每一条打开 local 数据根的入口都经它:`createStoreBackend` 的 local 腿(HTTP 服务)与 run-local;一个数据根一只会话行店、一份装配):
+ * 数据根准入(调用方交来的读数 `opts.admission`,判已在本进程第一笔写之前做完)→ 取锁(引擎 File 后端:建根、锁文件、引擎自己的店目录与空账本)→
+ * **锁内一步**({@link holdLocalDataRootAdmission}:核物理数据根与准入那一次观察都没动 → 跳版臂记 / 销账 → 抬引擎版本高水位)→ 本仓的店。
+ * 打开之后的公开序列两条入口相同:`ensureSchema()`(起服对账)→ `runOneTimeMigrations()` → 才读会话。
+ * 抬住在这里而不是 `ensureSchema()` 里,因为围栏以**第一笔落盘**界定:本仓的店在构造里就会写(撕裂的问账日志留证 + 压实、撕裂的 run 认领挪开、会话收尾的活跃边档落盘),
+ * 抬必须先于它们(写到一半崩了,水位已是本构建)。所以这一段之后才有店,没有任何一只店先于它。
+ * 锁内一步拒(准入判过的输入在准入之后被另一只引擎动过 / 记账或抬写不进)或本仓的店构造时抛 ⇒ 交回一只 {@link RefusedLocalBackend}:只握着锁,`ensureSchema()` 交出那一只拒
+ * (公开序列在它该在的那一步拒,降级臂按拒的族判),`close()` 只放锁 —— 没有店、没有收尾写。
+ */
+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 +562,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 +587,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, localAdmission?: LocalDataRootAdmission, facts?: StoreOpenFacts): Promise<{
     backend: StoreBackend | undefined;
     degradedReason: StoreDegradedReason | undefined;
 }>;
@@ -521,8 +601,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