@sema-agent/server 7.145.0 → 7.147.0

package/dist/plugins/shared-memory-store-sql.js

@@ -1,11 +1,10 @@
-import { isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
+import { isOrgScopeKey, isSharedMemoryDocumentPath, isSharedMemoryStoreId, SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
 const isDupKey = isDupKeyError;
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
 export const SHARED_MEMORY_ENTRY_TABLE = "shared_memory_entry";
-const ORG_SCOPE_RE = /^org:\S{1,185}$/;
 const PATH_MAX_CHARS = 512;
 const DESCRIPTION_MAX_CHARS = 512;
 const DEFAULT_MAX_LIST_LIMIT = 500;
@@ -15,10 +14,14 @@ export function assertStoreId(storeId) {
     }
 }
 export function assertScopeKey(scopeKey) {
-    if (!ORG_SCOPE_RE.test(scopeKey)) {
-        throw new Error(`shared-memory scope key ${JSON.stringify(scopeKey)} is not usable: it must match /^org:\\S{1,185}$/`);
+    if (!isOrgScopeKey(scopeKey)) {
+        throw new Error(`shared-memory scope key ${JSON.stringify(scopeKey)} is not usable: core's org scope key rule refuses it (spell the org with core's formatOrgScope: "org:" plus the name's percent-encoded segment)`);
     }
 }
+function ownedExactly(rows, scopeKey) {
+    const row = rows[0];
+    return row !== undefined && String(row.scope_key) === scopeKey;
+}
 export function assertDocumentPath(path) {
     const refuse = (why) => {
         throw new Error(`shared-memory document path ${JSON.stringify(path)} is not usable: ${why}`);
@@ -267,7 +270,6 @@ export class SqlSharedMemoryStore {
     }
     async putDocument(record) {
         assertStoreId(record.storeId);
-        assertScopeKey(record.scopeKey);
         assertDocumentPath(record.path);
         const sizeBytes = Buffer.byteLength(record.content, "utf8");
         if (sizeBytes > SHARED_MEMORY_READ_CAP_BYTES) {
@@ -278,8 +280,8 @@ export class SqlSharedMemoryStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [record.storeId, record.scopeKey]);
-            if (registered.rows.length === 0) {
+            const registered = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [record.storeId, record.scopeKey]);
+            if (!ownedExactly(registered.rows, record.scopeKey)) {
                 unregistered = true;
                 await conn.rollback();
             }
@@ -303,14 +305,13 @@ export class SqlSharedMemoryStore {
     }
     async deleteDocument(storeId, scopeKey, path) {
         assertStoreId(storeId);
-        assertScopeKey(scopeKey);
         let unregistered = false;
         let deleted = false;
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
-            if (registered.rows.length === 0) {
+            const registered = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (!ownedExactly(registered.rows, scopeKey)) {
                 unregistered = true;
                 await conn.rollback();
             }
@@ -334,13 +335,12 @@ export class SqlSharedMemoryStore {
     }
     async deleteStore(storeId, scopeKey) {
         assertStoreId(storeId);
-        assertScopeKey(scopeKey);
         let notOwned = false;
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const owned = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
-            if (owned.rows.length === 0) {
+            const owned = await conn.query(this.q(`SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id, scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (!ownedExactly(owned.rows, scopeKey)) {
                 notOwned = true;
                 await conn.rollback();
             }

package/dist/plugins/snapshot-bucket-presence.js

@@ -58,7 +58,7 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock, role =
 export async function ensureSnapshotBuckets(config, logger) {
     const wanted = [
         ["session", config.snapshotBlobStore],
-        ["workspace", config.remoteExec?.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
+        ["workspace", config.remoteExec.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
     ];
     for (const [role, store] of wanted) {
         if (store)

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

@@ -21,9 +21,13 @@
  *     ⚠️ The dup-key predicate ITSELF is NOT store-specific and no longer lives at the call sites:
  *     `sql-errors.ts` owns it ([ref] P1-①; 7+ hand-rolled copies had drifted into three different
  *     recognition sets, so the same driver error got opposite verdicts in different stores).
- *   - per-query timeouts: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig` with
- *     `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
- *     exec; this seam stays on the plain (sql, params) form.
+ *   - per-query timeouts on the POOL form: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig`
+ *     with `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
+ *     exec; the pool form of this seam stays on the plain (sql, params) form.
+ *     A LENT connection ({@link SqlTxConn.query}) takes one optional per-statement deadline
+ *     ({@link SqlStatementOptions}): past it the statement rejects ({@link SqlStatementDeadlineExceeded}) and the lease
+ *     is destroyed first (its session / transaction state is unknown — it never goes back to the pool; the server
+ *     rolls the open transaction back when the connection closes). Same rule on both dialects, one implementation.
  *
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
  * @contract txn.read-semantics — 本仓「事务里的读看到什么」的**唯一**成文处([ref] / [ref] / [ref])
@@ -127,8 +131,20 @@ export interface SqlResult {
 export interface SqlExec {
     query(sql: string, params?: unknown[]): Promise<SqlResult>;
 }
+/** Per-statement options of a lent connection's {@link SqlTxConn.query}. */
+export interface SqlStatementOptions {
+    /** The statement rejects ({@link SqlStatementDeadlineExceeded}) if it has not settled within this many ms; the lease is destroyed first. */
+    readonly deadlineMs?: number;
+}
+/** A lent connection's statement did not settle within its deadline: the connection was destroyed (never pooled again), the statement rejected. Typed so callers triage it without reading the message. */
+export declare class SqlStatementDeadlineExceeded extends Error {
+    readonly deadlineMs: number;
+    constructor(deadlineMs: number);
+}
 /** A pooled connection with transaction control (released by the caller in a `finally`). */
 export interface SqlTxConn extends SqlExec {
+    /** {@link SqlExec.query}, with an optional per-statement deadline (see the file header). */
+    query(sql: string, params?: unknown[], opts?: SqlStatementOptions): Promise<SqlResult>;
     /**
      * The ONE transaction verb ([ref]). What its reads see is NOT decided here — it is decided once per
      * pooled connection at initialization and reported by {@link SqlDriver.facts}. Read the
@@ -200,7 +216,7 @@ export interface SqlEngineFacts {
      *    ({@link PACKET_CAP_UNREAD_LANDING_BYTES}), recorded through `recordFailOpen("server.sql.packet-cap-unread")` (a per-hit
      *    count and one warn line naming the reason). Never `null`: on these engines the wall exists, only its size may be unread.
      *  · **`null`** — PostgreSQL: the extended protocol has no statement-size wall.
-     * Its final judge: the SQL snapshot-blob cap (`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`), which borrows the connection
+     * Its final judge: the SQL snapshot-blob cap (`stores-sql/blob-index-sql.ts` `SqlBlobIndex.put`, the SQL-kept arm), which borrows the connection
      * it will write on through {@link connectJudged}, reads this off it ({@link sqlConnectionFacts}), judges, and writes on that
      * same connection — and when it refuses on a connection opened before the DBA raised the wall, that stale connection is
      * replaced and the write judged once more ({@link connectJudged}). On {@link SqlDriver.facts} the value is the most recently
@@ -305,7 +321,7 @@ export interface SqlWallsReading extends SqlWalls {
 }
 /**
  * 一只 SQL 池的**引擎读口**:方言(SQL 文本轴,装配事实,恒在)+ 此刻的引擎事实(`null` = 没建立)。墙的方言只从这里来 —— 与事实同出一只驱动
- * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobBackend`)各读本池的这一只。
+ * ({@link SqlDriver} 结构上就是它;`facts` 是活的,池重连后随之换)。HTTP 面的读口(`ServiceDeps.sqlEngine`)与店的写前帽(`SqlBlobIndex`)各读本池的这一只。
  */
 export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
 /**
@@ -317,7 +333,7 @@ export type SqlEngineReading = Pick<SqlDriver, "dialect" | "facts">;
 export declare const SQL_FACTS_ABSENT_WALLS: SqlWallsReading;
 /**
  * 🔴 **此刻一份写入要装进的墙 —— 唯一判官**。两个读者同调它、不各读 `facts`:提交受理口(`http/request-guards.ts` `refuseSubmitBody`)与 SQL 快照 blob 的缺省帽
- * (`plugins/blob-backend.ts` `sqlBlobCapOf`:店的写前判,读的是**将要执行写入的那条连接**的读口 —— 方言 + 它自己那次初始化的事实;受理口读本池驱动的读口)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出),一种读法:
+ * (`stores-sql/blob-index-sql.ts` `sqlBlobCapOf`:店的写前判,读的是**将要执行写入的那条连接**的读口 —— 方言 + 它自己那次初始化的事实;受理口读本池驱动的读口)。输入是一只引擎读口({@link SqlEngineReading}:方言与事实同出),一种读法:
  *  · 读口缺席 = 没有 SQL 后端 ⇒ 没有墙(「忘了给」读不成这一臂:后端交出了 SQL 池而没给读口 ⇒ `createHttpServer` 起服拒,见 `ServiceDeps.sqlEngine`);
  *  · 事实在场 ⇒ 事实里的两位,出处逐墙取事实里记的那一份({@link SqlEngineFacts.wallSources}:读到的 `reported`,读失败退文档缺省的 `assumed`);
  *  · 事实缺席(`null`)⇒ 按读口的方言:PG 没有墙(扩展协议没有这两堵墙 —— 方言事实,不随引擎事实缺席);MySQL 协议 ⇒ {@link SQL_FACTS_ABSENT_WALLS}(两堵都 `assumed`;
@@ -373,7 +389,7 @@ export interface SqlDriver extends SqlExec {
 }
 /**
  * 一条**借出的**连接自己的引擎事实 —— 它的初始化回读到的那一份(包墙 `maxPacketBytes` 是这条连接的会话值)。判一条语句装不装得下的地方
- * 只读这里:借出连接 → 读它的墙 → 判 → 在同一条连接上执行(`plugins/blob-backend.ts` `SqlBlobBackend.putBlob`)。
+ * 只读这里:借出连接 → 读它的墙 → 判 → 在同一条连接上执行(`stores-sql/blob-index-sql.ts` `SqlBlobIndex.put`)。
  * 只认本模块的 `mysqlDriver` / `pgDriver` 的 `connect()` 借出的连接;别的连接(测试替身、包装体)没有经过初始化,墙没人读过 ⇒ **响亮抛**,不猜一个数。
  */
 export declare function sqlConnectionFacts(conn: SqlTxConn): SqlEngineFacts;

package/dist/plugins/sql-driver.js

@@ -2,6 +2,30 @@ import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js"
 import { recordFailOpen } from "../observability/fail-open.js";
 import { errorKindOf } from "../observability/err-text.js";
 import { isConnectionUnusableError } from "./sql-errors.js";
+export class SqlStatementDeadlineExceeded extends Error {
+    deadlineMs;
+    constructor(deadlineMs) {
+        super(`SQL statement did not settle within ${deadlineMs}ms — the connection was destroyed (its transaction rolls back when it closes)`);
+        this.deadlineMs = deadlineMs;
+        this.name = "SqlStatementDeadlineExceeded";
+    }
+}
+function withStatementDeadline(run, opts, destroy) {
+    const deadlineMs = opts?.deadlineMs;
+    if (deadlineMs === undefined)
+        return run();
+    const running = run();
+    running.catch(() => undefined);
+    let timer;
+    const expired = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            destroy();
+            reject(new SqlStatementDeadlineExceeded(deadlineMs));
+        }, deadlineMs);
+        timer.unref?.();
+    });
+    return Promise.race([running, expired]).finally(() => clearTimeout(timer));
+}
 export const TIDB_DEFAULT_TXN_ENTRY_SIZE_LIMIT = 6_291_456;
 export const ROW_WALL_ALLOWANCE_BYTES = { json: 64 * 1024, blob: 1024 };
 export const STATEMENT_ALLOWANCE_BYTES = 1024;
@@ -299,15 +323,20 @@ function leaseOf(raw) {
     if (GUARDED_LEASES.has(raw))
         return raw;
     let destroyed = false;
+    let leaveQueue = () => undefined;
+    const gone = new Promise((resolve) => {
+        leaveQueue = resolve;
+    });
     const destroy = () => {
         if (destroyed)
             return;
         destroyed = true;
+        leaveQueue();
         raw.destroy();
     };
     let turn = Promise.resolve();
     const guard = (run) => {
-        const result = turn.then(async () => {
+        const result = Promise.race([turn, gone]).then(async () => {
             try {
                 return await run();
             }
@@ -388,7 +417,7 @@ export function mysqlDriver(pool) {
             if (broken !== undefined)
                 throw broken.error;
             const conn = {
-                query: (sql, params) => mysqlQuery(c, sql, params),
+                query: (sql, params, opts) => withStatementDeadline(() => mysqlQuery(c, sql, params), opts, () => c.destroy()),
                 begin: () => c.beginTransaction(),
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
@@ -440,8 +469,14 @@ export function pgDriver(pool) {
             const c = await pool.connect();
             const { facts, initOrdinal } = await establishSession(session, c, c, initPgSession);
             let destroyed = false;
+            const destroy = () => {
+                if (destroyed)
+                    return;
+                destroyed = true;
+                c.release(true);
+            };
             const conn = {
-                query: (sql, params) => pgQuery(c, sql, params),
+                query: (sql, params, opts) => withStatementDeadline(() => pgQuery(c, sql, params), opts, destroy),
                 begin: async () => {
                     await c.query("BEGIN");
                 },
@@ -449,7 +484,8 @@ export function pgDriver(pool) {
                     await c.query("COMMIT");
                 },
                 rollback: async () => {
-                    await c.query("ROLLBACK");
+                    if (!destroyed)
+                        await c.query("ROLLBACK");
                 },
                 release: () => {
                     if (!destroyed)
@@ -461,10 +497,7 @@ export function pgDriver(pool) {
                 facts,
                 initOrdinal,
                 id: typeof pid === "number" ? pid : null,
-                destroy: () => {
-                    destroyed = true;
-                    c.release(true);
-                },
+                destroy,
                 readGlobalPacketWall: async () => null,
             });
             return conn;

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

@@ -193,12 +193,15 @@ 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)只可能出在建表 / 改表上,读写路径上的读者见不到它们 —— 加进本表对那几处零变化。
  *
  * 识别集 = 本表一张,按归因键登记:`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 自己的忙 / 区域不可用一族(同连接类表的登记)。
+ * **不在表里**(认不出一律不是;今天收缺表、权限拒与外键建不成三形,其余是登记在案的未收项,不是「已裁定不判」):缺列(1054 / `42703`:升级前置断言 `assert*Schema` 族有自己的判据与出路)、
+ * 认证类拒连(MySQL 1045、PG `28xxx`:凭据 / 白名单)、库级与列级的权限拒(MySQL 1044 / 1143)、语法错(1064:多半是我方的语句,不是库的形)、
+ * TiDB 自己的忙 / 区域不可用 / 结构变更冲突一族(9001 / 9005 / 8028,同连接类表的登记)、锁等待超时(1205)。
  */
 export declare const DEPLOYMENT_FAULT_ERRORS: ReadonlyArray<{
     readonly code: string;

package/dist/plugins/sql-errors.js

@@ -148,6 +148,10 @@ 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 盘满):修库之前重试同一句仍被拒" },
 ];
 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])));

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

@@ -69,7 +69,7 @@ export interface JsonColumnMember {
  *
  * 🔴 存在的唯一理由是「别名位在那里不合法」,**不是**给读腿留第二条路:读腿一律用 {@link jsonColumnText}
  * (别名是它的产物的一部分,理由见那只函数)。今天整仓**三处**消费方,各自的「别名位不合法」都是真的:
- *  · `one-time-migrations.ts` 的几条改写(M8 / M17 / M18 / M21 的候选扫描与按原文 CAS 回写)——
+ *  · `one-time-migrations.ts` 的几条改写(M17 / M18 / M21 的候选扫描与按原文 CAS 回写)——
  *    它们要在 `WHERE` 里判这一列的**文本**,而 `WHERE` 没有别名位;
  *  · `workflow-journal-store-sql.ts` 的 `loadPage`([ref] 车③a)—— 那一列的投影裹在一条
  *    `CASE WHEN LENGTH(result) > ? THEN NULL ELSE <expr> END AS result_json` 里:**别名属于整条 CASE**
@@ -202,6 +202,10 @@ export declare class StoreCorruptError extends Error {
     /** 出事的坐标(`<table>.<column> for <identity>`,由 {@link SqlJsonColumnError.where} 原样带过来)——
      *  进 wire 的 `where` 字段,人按它去找那一行。 */
     readonly where: string;
+    /** 构造函数交进来的就是这一只列错误(类型面如实:折码只在体问题上产出本类,见 {@link foldJsonColumn});子类想在同一份因由上再带一格事实时按它再构造,不必断言。 */
+    readonly cause: SqlJsonColumnError & {
+        readonly problem: SqlJsonColumnBodyProblem;
+    };
     constructor(cause: SqlJsonColumnError & {
         readonly problem: SqlJsonColumnBodyProblem;
     }, sentence: string);

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

@@ -20,7 +20,7 @@ import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-stor
 import { type SessionPolicyStoreLogger } from "../stores-sql/session-policy-store-sql.js";
 import type { ServiceConfig } from "../config-types.js";
 import { TiDBRunStore, PgRunStore } from "./run-store-sql.js";
-import { TiDBCheckpointStore, PgCheckpointStore } from "./checkpoint-store-sql.js";
+import { TiDBCheckpointStore, PgCheckpointStore } from "../stores-sql/checkpoint-store-sql.js";
 import { TiDBImageIndex, PgImageIndex } from "./image-index-sql.js";
 import { TiDBImageBake, PgImageBake } from "./image-bake-store-sql.js";
 import { TiDBLeaderRunStore, PgLeaderRunStore } from "./leader-run-store-sql.js";
@@ -33,9 +33,12 @@ import type { CounterDegradeHook } from "./write-behind-counter.js";
 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 SqlRetentionStore, type SqlRetentionStoreOptions } from "./retention-store-sql.js";
+import { type SqlTransactionHooks } from "../stores-sql/retention-store-sql.js";
+import type { EndedSpace } from "../workspace-space.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";
+import { type SqlDriver } from "./sql-driver.js";
 import { type StoreDegradedReason } from "../store-posture.js";
 /** boot 期的一条日志座(级别由**座位**决定,不由参数携带):`createStoreBackend` 的 `onWarn` / `onError`
  *  两参与 `LocalBackend` 的同名字段共用此形。装配层把它们分别接到 `logger.warn` / `logger.error` 上。 */
@@ -65,7 +68,7 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  * The SQL twins' blob exchange — core's {@link FileHistoryBlobExchange} group (`put` / `get` / `has`, all three or none, read only
  * through `blobExchangeOf` in `session-sync.ts`, which defers to core's judge) with ONE narrowing: a `put` refusal may carry
  * `blobCap`, the SQL blob judge's refusal on the connection that would have written the blob
- * ({@link import("./blob-backend.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
+ * ({@link import("../stores-sql/blob-index-sql.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
  * `blob_too_large_for_sql` (the judge's sentence, plus the machine-readable `wallSource` = where the cap came from). The content-address
  * refusal is core's own (`adopt_failed`, `permanence: "terminal"`, nothing stored); every other failure is a write fault the route answers 502.
  */
@@ -75,7 +78,7 @@ export type SqlBlobPutResult = {
     readonly ok: false;
     readonly error: FileHistoryError & {
         readonly blobCap?: {
-            readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+            readonly wallSource: import("../stores-sql/blob-index-sql.js").SqlBlobCapReading["source"];
         };
     };
 };
@@ -92,7 +95,7 @@ export type ServiceFileHistoryStore = FileHistoryStore & {
      *  protected — never a synchronous external-store delete). Reaper-driven; SQL twins only. */
     sweepOrphanBlobs?(): Promise<number>;
 };
-/** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service `deleteByRun` (GC extra). tidb/pg =
+/** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service read page and age sweep below. tidb/pg =
  *  durable SQL twins (cross-replica resume journal); local = the service {@link FileWorkflowJournalStore}
  *  (single-box but RESTART-durable crash-safe JSONL, replacing core's InMemory). The shared equivalence suite keeps
  *  all three byte-matched (scope guard / idempotent-per-ordinal / oversize **refusal** —— [ref] / core 7.12.0
@@ -111,11 +114,14 @@ export type ServiceWorkflowJournalStore = WorkflowJournalStore & {
         resultJson: string | null;
         resultBytes: number;
     }>>;
-    deleteByRun?(runId: string): Promise<number>;
-    /** SVC-2 GC sweep (durable twins only): purge entries older than `maxAgeMs` — wired into the reaper to bound the
-     *  TaskResult-bearing table (the per-run deleteByRun has no run-store reap hook). Local InMemory omits it. */
+    /** SVC-2 GC sweep (durable twins only): purge entries older than `maxAgeMs` — the `workflow-journal-expired` leg of the backend sweep verb
+     *  (`plugins/store-sweep.ts`, composed in `boot/stores.ts`) bounds the TaskResult-bearing table with it; the journal's one delete path (no per-run
+     *  delete: the engine contract never had one). Local File / InMemory omit it. */
     reapExpired?(now: number, maxAgeMs: number): Promise<number>;
 };
+/** 本部署有没有 workflow journal 店、是哪一只 —— 唯一读法:开了 self-orchestration 且有后端 ⇒ 后端的 journal 店,否则无。
+ *  两处读者同读它:workflow 编排段(交 Runner 与 journal HTTP 读面的那只)与持久层组合点(按龄清扫动词的 `workflow-journal-expired` 腿)。 */
+export declare function workflowJournalOf(config: Pick<ServiceConfig, "selfOrchestrationEnabled">, backend: Pick<StoreBackend, "workflowJournal"> | undefined): ServiceWorkflowJournalStore | undefined;
 export type ImageIndex = TiDBImageIndex | PgImageIndex;
 export type ImageBake = TiDBImageBake | PgImageBake;
 /** [ref] 车4 件1:durable leader-run 登记表的双方言孪生(union 同族——TS 私有字段让具体类名义上不同)。 */
@@ -160,7 +166,8 @@ export interface StoreBackend {
      *  schema that the one-time migrations of server 7.74.0–7.125.x retired and **refuses** with `RetiredSchemaPresentError`
      *  (code `config.schema_mismatch`, exported from the package root) before it issues the first CREATE; only then does it create.
      *  The check lives in this method itself, so the public sequence `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()`
-     *  needs no step of its own. The LOCAL backend has no SQL pool and nothing to probe. */
+     *  needs no step of its own. The LOCAL backend has no SQL pool: its data root's engine high-water is judged when the backend is opened (before any store is built),
+     *  and a data root refused there surfaces here, as that refusal; otherwise this runs the local reconciliation (strict sidecars, archive snapshots). */
     ensureSchema(): Promise<void>;
     close(): Promise<void>;
     run(): RunStore;
@@ -280,9 +287,9 @@ export interface StoreBackend {
      *  until a 2026-07-25 doc-rot sweep caught it). core 1.145.0 added the seam this comment was waiting for:
      *  `RunnerDeps.workflowJournalStore` (now `@sema-agent/core` `dist/core/types.d.ts`) + `journalStore` on the
      *  run_workflow tool deps (`dist/orchestration/run-workflow-tool.d.ts`), and the boot chain consumes it
-     *  end-to-end: built in `boot/workflow-orchestration.ts` (`const workflowJournalStore = …backend.workflowJournal()`),
-     *  threaded into RunnerDeps (`boot/runner-deps.ts` 的 `workflowJournalStore`), reaped on the maintenance tick
-     *  (`boot/reapers.ts` 同名字段), and read by `GET /v1/workflows/:id/journal` (`http/routes/workflows.ts`, [ref]). */
+     *  end-to-end: selected by {@link workflowJournalOf} (self-orchestration on ∧ a backend), built in `boot/workflow-orchestration.ts`,
+     *  threaded into RunnerDeps (`boot/runner-deps.ts` 的 `workflowJournalStore`), aged out by the backend sweep verb's `workflow-journal-expired`
+     *  leg (`boot/stores.ts`, same selector), and read by `GET /v1/workflows/:id/journal` (`http/routes/workflows.ts`, [ref]). */
     workflowJournal(): ServiceWorkflowJournalStore;
     /** [ref] §1 consumption sink for `RunnerDeps.onTaskOutcome` facts. REQUIRED on all backends:
      *  tidb/pg = the outcome-ledger twins (SQL rows, mapped via coreOutcomeToLedgerRow + verbatim core_outcome
@@ -351,7 +358,7 @@ export interface StoreBackend {
      * `local` 刻意省略 —— 与 {@link leaderRun} 逐字同一条理由:config 层已经把「`REMOTE_EXEC=device` 且
      * 无外部 SQL 店」整个组合拒启了(`device-durable-store` 不变量),所以 local 车道上根本不存在一个需要
      * 这四张表的 device worker。消费点按 `backend?.device?.()` 取,缺席 ⇒ `boot/device-lane.ts` 的
-     * `assertDeviceLaneWired` 响亮拒启(**不是**静默落进程内 stub)。
+     * `assertDeviceLaneWired` 响亮拒启(**不是**静默跑成无手)。
      */
     device?(): DeviceStore;
     /**
@@ -361,9 +368,9 @@ export interface StoreBackend {
      *
      * `taskAttachmentTable` 必填、无默认值 —— boot 只在配了对象存储时才 ensure 那张表,一条盲发的
      * DELETE 在无 MinIO 的部署上会以 unknown-table 打红整轮 sweep(理由逐字见
-     * `retention-store-sql.ts` 的 `SqlRetentionStoreOptions`)。
+     * `retention-deployment.ts` 的 `RetentionExecutorOptions`)。组合形见 {@link createSqlRetentionExecutor}。
      */
-    retention?(opts: SqlRetentionStoreOptions): SqlRetentionStore;
+    retention?(opts: RetentionExecutorOptions): RetentionExecutor;
     /**
      * [ref] 车2 —— 留存执行面的**非破坏性**半场:sweep 租约、legal-hold 的放置/解除、审计表的读与
      * 非破坏行的写。同样 SQL 专有(它写的三张表只在 SQL schema 里)。
@@ -400,6 +407,23 @@ export interface StoreBackend {
      *  `new FileUsageWindowStore(root)` 第二只实例、不接座 ⇒ 坏值只拒不披露,运维找不到是哪只文件。SQL 后端省略(它们有自己的 usage-window 双方言店)。 */
     fileUsageWindowStore?(): UsageWindowStore;
 }
+/**
+ * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十一张部署表,
+ * `plugins/retention-deployment.ts`,经 K4 事务内钩参与同一事务)。
+ *
+ * 破坏性三方法**每次调用**铸一只执行器、钩表绑这一次调用(`createRetentionDeploymentHooks` 的头注:审计行的判定时点三格与
+ * `checkpoint_ctx` 属主门的域是这一次调用的事实)。会话树删除的 `endedSpaces` 由部署从 `beforeDelete` 收到的行自算,
+ * 只在执行器**提交成功返回之后**挂上回执(回滚 ⇒ 执行器抛,不挂)。非破坏两口(域枚举 / 预览)不经钩。
+ */
+/**
+ * 一次破坏性调用的整张事务内钩表:部署的 `retention` 组(按这一次调用铸,`createRetentionDeploymentHooks`)+ 会话座的钩
+ * (`createSqlSessionWriteHooks`,会话店用的同一只工厂;留存删除走它的 `retention-delete` 臂)。`endedSpaces` 读部署那一半收到的行。
+ */
+export declare function createSqlRetentionCallHooks(db: SqlDriver, opts: RetentionExecutorOptions, input: RetentionDestructiveInput): {
+    readonly hooks: SqlTransactionHooks;
+    endedSpaces(): readonly EndedSpace[];
+};
+export declare function createSqlRetentionExecutor(db: SqlDriver, opts: RetentionExecutorOptions): RetentionExecutor;
 /** (c)(clay 拍 a+c,2026-07-27;[ref] 换店后域=file_history_blob,门与旋钮名不变)云形 blob 姿势门——
  *  boot 时调用(boot/stores.ts),纯函数可单测。SQL 后端(mysql|pg)把 blob 字节落单行的形已被两役
  *  实证撞 mysql-协议包墙(D-1 附件 → 对象存储裁定):大字节归对象存储。per-file 历史的 blob=单文件
@@ -468,7 +492,13 @@ export declare function createStoreBackend(config: ServiceConfig, onWarn?: BootL
  *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
  *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
  *
- *  **降级臂只有一条:缺省推导的 local**(`dbBackend=local && !dbBackendExplicit`)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
+ *  **降级臂只有一条:缺省推导的 local 且数据根上什么都没有**(`dbBackend=local && !dbBackendExplicit`,数据根不存在或是空目录 —— 开店之前判)。
+ *  判据看的是**数据根的状态**,不是错误的种类:数据根上已有东西 ⇒ 这台部署有过持久面,开它时的**任何**失败(权限 / 只读挂载 / 子目录建不出 /
+ *  另一实例持锁 / adoption 在飞 / 账本重放不了 …)都按显式 `DB_BACKEND=local` 同待遇 —— 原样抛、拒启,不退内存(退了 = 已有的会话 / run 账本 /
+ *  问账整片看不见、新写只进内存,而 `/health` 照样 200)。只有「数据根不存在 / 空」那一形是「这台机器存不了盘」的诚实等价物,才许退内存 + 一行 warn。
+ *  修前按错误种类逐个豁免(adoption 一条、File 店族拒启一条、再往各店构造器里逐处包),漏一处就是一条 fail-open;按状态判之后,新店的新失败默认落在拒启一侧。
+ *  1.292 的口径据此收窄:只读挂载 / 建不出的根**在空 / 不存在时**仍退内存;已有数据的根拒启(出路:修好权限 / 挂载 / 停掉持锁的另一实例;要内存就显式写
+ *  `DB_BACKEND=memory`;要另起一个空根就把 `LOCAL_DATA_ROOT` 指过去)。🔴 **SQL 族没有降级臂** —— 配了 DSN 就是要这只库:
  *  `SESSION_BACKEND=auto` 与显式 `DB_BACKEND=mysql|pg` 同一待遇,库当下打不开 ⇒ 在 `STORE_LOCK_WAIT_MS` 的窗内重试
  *  ({@link openWithinWait}),到窗仍打不开 ⇒ 拒启(拒句 {@link buildSqlStoreOpenRefusal} 点名后端与库的显示安全形)。修前 `auto` 在这里
  *  静默落内存(只留一行 warn):会话 / 停驻 / run 账本进进程内存、重启即丢,而 `/health` 照样 200 —— [ref] P 类 fail-open。