@sema-agent/server 7.145.0 → 7.147.0

package/dist/{plugins → stores-sql}/retention-store-sql.d.ts

@@ -1,21 +1,20 @@
 /**
- * 托管留存(managed retention)执行面的 **store 半场** —— SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;
- * 先例 = `leader-run-store-sql.ts` / `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
- * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的
- * `core/retention.d.ts`(`ManagedRetentionCapability` / `RetentionReceipt` / `RetentionDeclaration`)。
+ * 托管留存(managed retention)的**执行器** —— 引擎座表那一半(阶段三逐字搬进 `@sema-agent/core-stores-sql` 的那一半)。
+ * SINGLE-FILE DUAL-DIALECT([ref] A12 定型半场;先例 = `checkpoint-store-sql.ts`)。[ref] 车1,设计稿
+ * `docs/DESIGN-270-retention-lane.md` v1.2。上游契约真源 = `@sema-agent/core` 的 `core/retention.d.ts`
+ * (`ManagedRetentionCapability` / `RetentionReceipt`);事务内钩表的形 = core-stores-sql 的 `SqlTransactionHooks`(本文件的同名型是它的形,见下)。
  *
- * ── 为什么这四张表 + 一只**聚合**店 ─────────────────────────────────────────────────────────────────
- * core 把破坏性级联整个下沉成 store 方法(`expireCheckpoints` / `deleteExpiredSessions` /
- * `deleteOrphanToolResults`),并点名 server 的 session-purge 顺序契约(E21,`boot/session-faces.ts` 的
- * `purgeSession` 协调器)为参考实现。那条顺序契约横跨**十余张表**(run 账本 / checkpoint / tool_result /
- * anchor / exemption / policy / attachment / 用户输入受理账本 / snapshot / workflow inbox / session_meta+event),而设计稿
- * §6 的 F5 又要求「审计行与删除同一个 DB 事务」—— 一个事务 ⇒ 一条连接 ⇒ **一个属主**。
- *
- * ⇒ 布局裁定:本能力**不能**挂在 session / checkpoint / tool-result 任何一只店上(每只店只拥有自己的表,
- *   把跨表级联塞进其中一只 = 让它去写别人的表,且三只店各持自己的 driver ⇒ 三个事务,F5 当场破)。它是
- *   `purgeSession` 协调器的**事务化孪生**:协调器在应用层按序调各店,本店在**一个事务里**按同一顺序发同
- *   一组 DELETE。同一条顺序契约,两个属主(在线删除 = 协调器;留存删除 = 本店),等价性由
- *   `retention-store-db-integration.test.ts` 的 E21 同种子行集断言钉住。
+ * ── 一个事务、两个属主:执行器 + 部署钩 ─────────────────────────────────────────────────────────────
+ * core 把破坏性级联整个下沉成三只方法(`expireCheckpoints` / `deleteExpiredSessions` / `deleteOrphanToolResults`),且设计稿
+ * §6 F5 要求「审计行与删除同一个 DB 事务」—— 一个事务 ⇒ 一条连接 ⇒ **一个事务属主**,就是本执行器(开、提交、回滚)。
+ * 但事务里的表有两个属主:引擎座表(checkpoint / tool_result / session_policy / file_history_* / session_meta / session_event /
+ * 墓碑)归本执行器;部署的表(hold / 审计 / 运行账本 / 停驻 ctx / 续跑锚 / 审批豁免 / 附件 / 受理账本 / 任务清单 / 完成信箱)归部署。
+ * 部署经**一张闭集事务内钩表**({@link SqlTransactionHooks})参与同一事务,每只钩只拿到语句面(`query`),事务归执行器。
+ * 破坏性事务的次序(K4,一步不省):
+ *   `holdLock`(首句)→ 候选加锁读(`FOR UPDATE`,含每只候选的会话行)→ 每只候选根 `session.beforeCommit`(仅会话树)→
+ *   `liveReferences`(余下候选)→ `beforeDelete`(终集)→ 本执行器删自己的行、落墓碑 → `audit`(提交前末句)→ COMMIT。
+ * 一只被某个钩放下的会话不进任何后续钩的入参。部署那一半(server 的 hold / 审计 / 认领判 / 十一张部署表)在
+ * `plugins/retention-deployment.ts`,组合在 `plugins/store-backend.ts`(`createSqlRetentionExecutor`)。
  *
  * ── 域(domain)口径 ────────────────────────────────────────────────────────────────────────────────
  * 域 = 租户键。三张保留表各有自己的载体列:`session_meta.owner`(**可空**)、`checkpoint.scope`(非空)、
@@ -24,68 +23,29 @@
  *   · **空串 `''` = 无主(anonymous/dev)桶**,谓词写成 `(owner IS NULL OR owner = '')` —— 两者合并成一个
  *     桶是**保守**的(合并只发生在无主侧,永远不会伸进一个真租户);拆成两个桶才会漏(NULL 那半永不被
  *     枚举 = codex F4 同族的病)。真部署里 `''` 不是可铸的 principal(auth 门拒空 system 名)。
+ *   · 谓词的唯一写法在 `plugins/retention-sql.ts`(执行器与部署钩同读,一条律一个读法)。
  *
  * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
  *   - `?` 占位符 vs `$n`;多值集合 MySQL 用 `IN (?,?,…)`、PG 用 `= ANY($n::text[])`(先例:
  *     workflow-run-store-sql 的 reap)
- *   - 幂等建行:哨兵形(形 A,[ref])`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
- *     —— 随后有同行 `FOR UPDATE` 的建行**必须**用 ON DUPLICATE(重复键取 X,同锁模式);墓碑那种
- *     「只读 affected 不加锁读」的写点(形 B)才保留 `INSERT IGNORE`
- *   - 级联 DELETE 的 JOIN 形:`DELETE te FROM a te JOIN b …` vs `DELETE FROM a te USING b …`
+ *   - 幂等建行:墓碑那种「只读 affected 不加锁读」的写点(形 B)用 `INSERT IGNORE` vs `ON CONFLICT (…) DO NOTHING`
  *   - null-safe 比较:`<=>` vs `IS NOT DISTINCT FROM`(及其**占位符数量**差:`?` 不可复用)
  *   - JSON 提取(workflow_run 的 originatingSessionId):`JSON_UNQUOTE(JSON_EXTRACT(run,'$.x'))` vs
  *     `run::json->>'x'`
  *   - 表级 `COLLATE utf8mb4_bin` vs 逐列 `COLLATE "C"`(`isolation-key-collation` 门执法)
  *   - 事务动词:只有 `begin()` 一个;读语义的判据在 {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`
- *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 `SCHEMA_STATEMENTS`;PG DDL 由本文件的
- *     `ensurePgRetentionSchema` 导出、由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(与 leader-run 同姿势)。
+ *   - schema 属主:本执行器只建**墓碑表**(MySQL DDL 展开进 `tidb-pool.ts` 的 `SCHEMA_STATEMENTS`;PG DDL 由 `pg-pool.ts`
+ *     的中央 `ensurePgSchema` 组合);审计 / hold / 租约三表的属主是部署(`plugins/retention-lane-store-sql.ts`)。
  *
  * ── 命名([ref] 纪律,与设计稿的复数写法的**有意**偏离)────────────────────────────────────────────
  * 设计稿 §5/§2 写的是 `retention_holds` / `retention_tombstones`;本仓的表名闭集词表是**单数**制且由
  * `test/schema-naming-invariants.test.ts` 机器执法(「一张表是一类行的集合,表名说的是『一行是什么』」)。
  * ⇒ 落库名一律单数:`retention_audit` / `retention_hold` / `retention_lease` / `retention_tombstone`。
  */
-import type { ManagedRetentionCapability, RetentionDeclaration, RetentionReceipt } from "@sema-agent/core";
-import type { Pool as MySqlPool } from "mysql2/promise";
-import type { Pool as PgPool } from "pg";
-import { type SqlDriver, type SqlTxConn } from "./sql-driver.js";
-import { type IndexSpec } from "./ensure-index.js";
-import type { EndedSpace } from "../workspace-space.js";
-/**
- * 三只**被托管**的 SQL 店(session / checkpoint / tool-result)在扫车道开着时的 `retention` 声明常量。
- *
- * 🔴 **谁说这个词**(引擎 7.58.0 起:店说 `"managed"` 而部署不跑执行器 ⇒ 锁不锁都拒启):「这只店的行有没有人按期删」不是店类自己知道的事,
- * 是装配它的部署知道的事。唯一事实 = 扫车道开不开({@link retentionSweepRuns});后端铸店时按它给词({@link sqlStoreRetention}),
- * 交给引擎启动检查的执行器读同一个事实(开 ⇒ 执行器,关 ⇒ `null`)。店构造不给词 ⇒ `"none"`(引擎对缺席的同一读法)。
- *
- * 🔴 为什么是一个共享常量而不是各写各的字面量:这一格是 core `assertRetentionCapability` 的**唯一**读点,
- * 三只店的答案必须同进同退 —— 哪天本能力从某只店的行上撤了(比如 tool_result 改由别处清),漏改一处
- * 就是一句谎,而谎的方向是「locked policy 放行了一只其实不删的店」。
- *
- * 🔴 声明的**读法**(与 core 契约的字面对齐,别读大也别读小):`"managed"` 说的是「**这只店的行**由本
- * 部署的托管留存按期删除」,不是「本对象自己实现了三个方法」。三方法的实现体是本文件的
- * `SqlRetentionStore` —— 它是 E21 purge 协调器的事务化孪生,横跨十余张表(理由见文件顶注的布局裁定)。
- * core 的门读的是「这只店的数据会不会被按期删掉」(拒启文案逐字:「a locked retention policy over stores
- * that cannot delete would be *policy locked, data immortal*」),SQL 三店的诚实答案就是 `"managed"`。
- * file/in-memory 形没有任何东西会按期删它们的行 ⇒ 显式 `"none"`(缺席也读 none,但显式是文档义务)。
- */
-export declare const MANAGED_RETENTION: RetentionDeclaration;
-/** file/in-memory 形、以及扫车道关着的 SQL 店的诚实声明(见 {@link MANAGED_RETENTION} 的读法说明)。 */
-export declare const UNMANAGED_RETENTION: RetentionDeclaration;
-/** 本部署跑不跑托管留存的扫车道(`RETENTION_SWEEP_INTERVAL_SEC > 0`)—— 三只 SQL 店的声明与交给引擎启动检查的执行器只读这一处。 */
-export declare function retentionSweepRuns(sweep: {
-    readonly intervalSec: number;
-}): boolean;
-/** 后端铸三只被托管的 SQL 店时交给店的词:扫车道开 ⇒ `"managed"`,关 ⇒ `"none"`。 */
-export declare function sqlStoreRetention(sweep: {
-    readonly intervalSec: number;
-}): RetentionDeclaration;
-/** 追加式审计表(设计稿 §6)。 */
-export declare const RETENTION_AUDIT_TABLE = "retention_audit";
-/** per-domain 法务保留标记(设计稿 §5)——**行在 = 该域整体冻结**。 */
-export declare const RETENTION_HOLD_TABLE = "retention_hold";
-/** sweep 互斥的单行租约表(设计稿 §3)。表建在车1(schema 一次齐),抢/续租的逻辑归车2。 */
-export declare const RETENTION_LEASE_TABLE = "retention_lease";
+import type { ManagedRetentionCapability, RetentionReceipt } from "@sema-agent/core";
+import type { SessionWriteHooks } from "./session-write-hooks.js";
+import type { SqlDriver, SqlTxConn } from "../plugins/sql-driver.js";
+import type { IndexSpec } from "../plugins/ensure-index.js";
 /** 删除墓碑(设计稿 §2)——副本/备份收敛 **+ 域枚举并集的第四条腿**(codex F4)。 */
 export declare const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
 /**
@@ -93,49 +53,44 @@ export declare const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
  * v1 两个成员 —— 会话树(`deleteExpiredSessions`)与孤儿卸载结果(`deleteOrphanToolResults`)。
  */
 export type RetentionTombstoneKind = "session" | "tool_result";
+/** MySQL 协议方言的墓碑表建表语句(执行器是它的唯一 DDL 属主;由 `tidb-pool.ts` 展开进中央 `SCHEMA_STATEMENTS`,紧跟部署的三张留存表)。 */
+export declare const TIDB_RETENTION_TOMBSTONE_STATEMENTS: readonly string[];
+/** PG 方言的墓碑表(MySQL 孪生的逐条翻译;语义逐字见 MySQL 孪生的行内注)。由 `pg-pool.ts` 的中央 ensure 组合。 */
+export declare const PG_RETENTION_TOMBSTONE_SCHEMA: readonly string[];
+/** [ref]:墓碑表的索引**声明**(两方言共用一份;应用点同上)。 */
+export declare const RETENTION_TOMBSTONE_INDEXES: readonly IndexSpec[];
+/** 钩能发的语句:执行器事务所持连接的 `query`(提交 / 回滚归执行器,钩拿不到)。 */
+export type SqlStatementFace = Pick<SqlTxConn, "query">;
+/** 钩被告知的破坏性调用 —— 执行器会删东西的那几只成员。 */
+export type SqlRetentionOp = Exclude<keyof ManagedRetentionCapability, "listRetentionDomains">;
 /**
- * 审计行的 `action` 闭集(设计稿 §6 逐字)。**破坏性三词**由本店在删除同事务内写;其余四词
- * (`audit_only` / `skipped_legal_hold` / `failed` / `hold_placed` / `hold_released`)属主是 lane/路由(车2)
- * —— 它们没有「删了没记」的窗口。词表整只放在这里是为了两半场共用一份真源。
+ * 部署的表在执行器事务里出场的位置。闭集:每组每钩都在这里点名。
+ * 破坏性事务次序:`holdLock` → 候选加锁读 → `session.beforeCommit`(每只候选根,仅 `deleteExpiredSessions`)→ `liveReferences`
+ * → `beforeDelete`(终集 = 候选 − 被拒 − 被引)→ 执行器删自己的行、落墓碑 → `audit` → 提交。被某只钩放下的会话不进后续钩的入参。
  */
-export type RetentionAuditAction = "expired_checkpoints" | "deleted_sessions" | "deleted_tool_results" | "audit_only" | "skipped_legal_hold" | "failed" | "hold_placed" | "hold_released";
-/** MySQL 协议方言的建表语句(真源;由 `tidb-pool.ts` 展开进中央 `SCHEMA_STATEMENTS`)。 */
-export declare const TIDB_RETENTION_STATEMENTS: readonly string[];
-/** PG 方言的建表语句(MySQL 孪生的逐条翻译:AUTO_INCREMENT→BIGSERIAL,逐列 `COLLATE "C"`,内联 KEY→独立
- *  CREATE INDEX)。语义逐字见 MySQL 孪生的行内注,此处不复述(两份注释迟早分叉)。 */
-export declare const PG_RETENTION_SCHEMA: readonly string[];
-/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgRetentionSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
-export declare const RETENTION_INDEXES: readonly IndexSpec[];
-/** PG 侧的幂等 schema apply(由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合;裸 `PgQueryFn` 形,与
- *  approval-ask / leader-run 同姿势 —— DDL 仍跑在中央那条 client 上,advisory lock 的 session 语义不受影响)。 */
-export declare function ensurePgRetentionSchema(query: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
-/**
- * 一次破坏性留存调用的**审计上下文**——判定时点的三格,由调用方(车2 的 lane)传入。
- *
- * 🔴 为什么必须由调用方传、而不是店自己去读配置:`mode`/`policyDays` 是**判定时点**的事实(策略是部署
- * env、模式是灰度旋钮,两者都会在两次 sweep 之间被改),`fencingToken` 更是本轮租约的身份。店去现读
- * 配置 = 审计行记的是「写这行的那一刻的配置」,而不是「按哪档删的」,那正好把审计的意义抹掉。
- */
-export interface RetentionAuditContext {
-    /** 判定时点的灰度档。词表闭集(与 §4 同一张表);`audit-only` 档下 lane 不该调破坏性方法,但如果调了,
-     *  审计行会如实记下这个矛盾(而不是被店悄悄改写成 enforce)。 */
-    mode: "audit-only" | "enforce";
-    /** 判定时点的策略值(天)。 */
-    policyDays: number;
-    /** 本轮 sweep lease 的 fencing token(§3)。`null` = 调用方没有租约面(单机/测试);破坏性行仍会落
-     *  审计,只是这一位为空 —— 「没有轮次身份」本身也是审计要记的事实。 */
-    fencingToken: number | null;
-}
-/** 三只契约方法的入参 —— core 的 `{domain, cutoffMs}` **超集**(多一个可选的审计上下文,见下)。 */
-export interface RetentionCallInput {
-    domain: string;
-    cutoffMs: number;
-    /**
-     * 🔴 类型上**可选**、运行时**必需**(fail-closed)。可选是为了结构上仍然满足 core 的
-     * `ManagedRetentionCapability`(拿着契约类型的调用方看得见的形必须是 core 那个形);运行时缺席则当场
-     * 抛 —— 一次没有审计上下文的破坏性调用 = 无证删除,而 §6 F5 的全部意义就是不许有无证删除。
-     */
-    audit?: RetentionAuditContext;
+export interface SqlTransactionHooks {
+    readonly retention?: {
+        /** 每个破坏性事务的首句:部署锁读本域的 hold 记录并持锁到提交。`"held"` ⇒ 本次调用在该域一行不删、候选计 skipped。 */
+        holdLock?(txn: SqlStatementFace, call: {
+            readonly domain: string;
+            readonly op: SqlRetentionOp;
+        }): Promise<"proceed" | "held">;
+        /** 执行器锁住候选会话之后调:答其中仍被部署行引用的 id —— 本轮跳过。 */
+        liveReferences?(txn: SqlStatementFace, candidates: readonly string[]): Promise<ReadonlySet<string>>;
+        /** 执行器删自己的行之前、对终集调:部署删同一批会话的部署行。每行带会话的化身。 */
+        beforeDelete?(txn: SqlStatementFace, rows: readonly {
+            readonly sessionId: string;
+            readonly incarnation: string | undefined;
+        }[]): Promise<void>;
+        /** 提交前的末句:部署在同一事务里写自己的审计行(轮次 / 策略 / 栅栏令牌是部署的事)。`receipt` = 本次调用的三个计数。 */
+        audit?(txn: SqlStatementFace, call: {
+            readonly domain: string;
+            readonly op: SqlRetentionOp;
+        }, receipt: RetentionReceipt): Promise<void>;
+    };
+    /** 会话组 = 会话座自己的那只钩(契约 `session-write-hooks.ts`;组合座交进来的是会话店用的同一只工厂铸的):每只候选根(会话行已由候选读锁住、什么都没写)
+     *  调一次 `beforeCommit({ op: "retention-delete" })`,`{ refuse }` ⇒ 这棵树本轮不删、计 skipped、继续别的。 */
+    readonly session?: Pick<SessionWriteHooks, "beforeCommit">;
 }
 /** `previewRetention` 的三候选计数(**非契约**窄读口:core 无 count 面,这是 server 自己店上的超集)。 */
 export interface RetentionPreview {
@@ -143,23 +98,11 @@ export interface RetentionPreview {
     sessions: number;
     toolResults: number;
 }
-/** 装配面必须如实告知的**可选表在场性**(见 {@link SqlRetentionStore} 的构造器注)。 */
+/** 执行器的构造选项(core-stores-sql `SqlStorageBackendOptions` 里与留存相关的那一格 + 诊断日志座)。 */
 export interface SqlRetentionStoreOptions {
-    /**
-     * `task_attachment` 表是否在场。**必填,没有默认值**:boot 只在配了对象存储时才 ensure 这张表
-     * (`boot/stores.ts` 的附件段:无 MinIO ⇒ 整段不接线、表不建),于是一条盲发的 DELETE 在无对象存储的
-     * 部署上会以 unknown-table 报错、把整轮 sweep 打红。让装配层如实回答,比让店去吞一个错误好 —— 吞错误
-     * 就是静默 fail-open(附件行从此永不被留存清理,而没有任何人知道)。
-     */
-    taskAttachmentTable: boolean;
-    /**
-     * [ref] `task_list_meta` / `task_list_item` 两表是否在场。**必填,没有默认值**(与
-     * `taskAttachmentTable` 同一条理由:盲发 DELETE 会在没建表的库上把整轮 sweep 打红)。
-     * 生产上 `boot/task-list-lane.ts` 在**任何 SQL 后端**都无条件 ensure 这两张表 ⇒ 装配层照实传 true;
-     * 纯内存/local 车道压根没有 SQL 留存腿。
-     */
-    taskListTables: boolean;
-    /** 诊断日志座(可选)。 */
+    /** 部署在执行器事务里的钩表(K4)。缺席 = 部署没有自己的表参与(没有 hold、没有审计行、没有部署行要随会话删)。 */
+    transactionHooks?: SqlTransactionHooks;
+    /** 诊断日志座(可选;事务回滚失败的那一行)。 */
     logger?: {
         info?(msg: string, meta?: unknown): void;
         warn?(msg: string, meta?: unknown): void;
@@ -172,35 +115,23 @@ export declare const RETENTION_SESSION_BATCH = 500;
 /** checkpoint / tool_result 腿的同款上界(单行代价远小于会话树,故取大一档)。 */
 export declare const RETENTION_ROW_BATCH = 2000;
 /**
- * 托管留存能力的双方言实现 —— core `ManagedRetentionCapability` 的 server 侧真身。
- * 方言差异台账见文件顶注;每个破坏性方法的事务形(hold 锁读 → 变更+墓碑 → 审计行,同 commit 同 rollback)
- * 见各方法的头注。
+ * 托管留存能力的双方言实现 —— core `ManagedRetentionCapability` 的执行器。方言差异台账见文件顶注;
+ * 每个破坏性方法的事务形(`holdLock` 首句 → 变更 + 墓碑 → `audit` 末句,同 commit 同 rollback)见各方法的头注。
  */
 export declare class SqlRetentionStore implements ManagedRetentionCapability {
     protected readonly db: SqlDriver;
     protected readonly opts: SqlRetentionStoreOptions;
-    /** 本店自己也是一只 `retention: "managed"` 的店(它就是那三个方法的实现体)。 */
-    readonly retention: RetentionDeclaration;
-    constructor(db: SqlDriver, opts: SqlRetentionStoreOptions);
+    /** 本执行器自己也是一只 `retention: "managed"` 的店(它就是那三个方法的实现体)。 */
+    readonly retention: import("@sema-agent/core").RetentionDeclaration;
+    constructor(db: SqlDriver, opts?: SqlRetentionStoreOptions);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE (A12 判据)。 */
     protected q(mysql: string, pg: string): string;
-    /**
-     * 域谓词。**四种写法逐条写出来**(方言 × 有主/无主):
-     *  · 有主:`col = ?` / `col = $n`;
-     *  · 无主(域键 `""`):`(col IS NULL OR col = ?)` / `(col IS NULL OR col = $n)` —— 把 SQL NULL 与空串
-     *    合并进同一个桶。合并只发生在**无主侧**,永远伸不进一个真租户;拆开才会漏(NULL 那半永不被枚举)。
-     * 🔴 两支的**占位符数量刻意相同**(无主支也绑一个 `""`):arity 一变,PG 的 `$n` 编号就会在同一条 SQL 的
-     * 后续参数上错位——那是一类只在某个域值上才复现的 bug,不许存在。
-     */
+    /** 域谓词 —— 唯一写法在 `plugins/retention-sql.ts`({@link retentionDomainWhere};部署钩同读)。 */
     protected domainWhere(col: string, domain: string, pgIndex: number): {
         sql: string;
         params: unknown[];
     };
-    /**
-     * 多值集合谓词 —— **真方言分叉**(不是 SQL 文本差):MySQL 展开 N 个 `?`,PG 用**一枚**数组参数
-     * `= ANY($n::text[])`。占位符数量因此不同(N vs 1),这是先例(workflow-run-store-sql 的 reap)也是
-     * 必然:把 500 个 id 展开成 500 个 `$n` 会让语句文本随批量变形,PG 的预编译缓存跟着退化。
-     */
+    /** 多值集合谓词 —— 唯一写法在 `plugins/retention-sql.ts`({@link retentionIdSet};部署钩同读)。 */
     protected idSet(col: string, ids: readonly string[], pgIndex: number): {
         sql: string;
         params: unknown[];
@@ -213,43 +144,19 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * `protected` = 真库套件的语句录制注入点(判据「hold 锁读是事务首条 SQL」靠它自证)。
      */
     protected tx<T>(fn: (conn: SqlTxConn) => Promise<T>): Promise<T>;
+    /** 交给钩的语句面:本事务连接的 `query`,别无他物(提交 / 回滚 / 释放归 {@link SqlRetentionStore.tx})。 */
+    private statementFace;
+    /** 首句:部署锁读本域的 hold 记录。无钩 ⇒ 部署没有 hold 面,`proceed`。 */
+    private heldBy;
     /**
-     * 破坏性调用的**入门检**:审计上下文缺席 ⇒ 当场抛(fail-closed)。
-     * core 的契约形只有 `{domain, cutoffMs}`,所以一个拿着契约类型的调用方**在类型上**能省掉它 —— 那正是
-     * 这道运行时门存在的理由:省掉它的那次调用如果照删不误,库里就多了一批无证删除的行。
+     * 每只候选根问一次部署(根的会话行已由候选读锁住)。无钩 ⇒ `proceed`;`{ refuse }` ⇒ 本轮不删这棵树,计进 `skipped`(账法见
+     * {@link SqlRetentionStore.deleteExpiredSessions} 头注「receipt 口径」)。
      */
-    protected requireAudit(input: RetentionCallInput, action: RetentionAuditAction): RetentionAuditContext;
-    /**
-     * 事务**首步**:拿本域的互斥行锁,并读出「这个域是不是冻结中」(§5 F2 承重)。
-     *
-     * 两步,缺一不可:
-     *  ① 幂等建一条 `held = 0` 的**哨兵行**(形 A,[ref]:MySQL `ON DUPLICATE KEY UPDATE domain = domain` /
-     *     PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存的 hold(两方言的这两个动词都只在缺行时
-     *     写),只保证**接下来那把行锁有东西可锁**;重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式
-     *     (`INSERT IGNORE` 在这里取 S 再升 X = InnoDB 上两个并发 sweep 互等的死锁形,[ref]);
-     *  ② `SELECT held … FOR UPDATE` —— 现在这行必定存在,于是锁真的拿到了。
-     *
-     * 🔴 为什么必须先造行(codex 交叉复审 R1-[high],验真后改):`FOR UPDATE` 锁不住缺席行(TiDB 无 gap
-     * lock;PG READ COMMITTED 同样)。presence 形(「行在 = 冻结」)下,operator 的 PUT 与本事务可以**同时**
-     * 都读到「没有 hold」,PUT 提交返回成功之后本事务照删不误 —— 设计稿 §5 声称由行锁给出的串行化在那一形
-     * 上根本不存在。哨兵行把 hold 的写点与删除的读点压到**同一把行锁**上,那句承诺才成立。
-     * ⚠️ 车2 交接:PUT/DELETE hold 必须走**同一 PK 的 upsert 改 `held` 列**(不是 INSERT/DELETE 行),
-     * 否则这把锁又会退回缺席形。
-     */
-    protected holdInForce(conn: SqlTxConn, domain: string): Promise<boolean>;
-    /**
-     * 审计行的**唯一**写点(§6 F5:破坏性行由店在删除同事务内写)。
-     * `protected` 是**有意的注入口**:真双库套件用一只覆盖本方法为抛错的子类来证 V10(「注入 audit 写失败
-     * ⇒ 整事务回滚、数据仍在」)。把注入点做成 mock 层的猴补丁反而证不了这件事 —— 它证的是 mock。
-     */
-    protected writeAuditRow(conn: SqlTxConn, row: {
-        domain: string;
-        action: RetentionAuditAction;
-        audit: RetentionAuditContext;
-        deleted: number;
-        skipped: number;
-        tombstones: number;
-    }): Promise<void>;
+    private admittedBy;
+    /** 部署仍在引用的候选(无钩 ⇒ 空集)。 */
+    private referencedBy;
+    /** 提交前末句:部署的审计行。无钩 ⇒ 部署不记审计。 */
+    private auditedBy;
     /**
      * 墓碑写入(幂等)。返回**真正新落地**的墓碑数 —— 重跑时既有墓碑不重复计数,于是 receipt 的
      * `tombstones` 与 `deleted` 在幂等重跑上同步归零。
@@ -287,10 +194,10 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
     /**
      * CAS 栅栏 `pending → expired`,每行恰一胜者(胜负由 `status = 'pending'` 谓词在引擎里裁,跨副本安全)。
      *
-     * 事务形(§5 F2 + §6 F5,一步不省):
-     *   ① `retention_hold` 本域行的**锁读** —— 行在 ⇒ 本事务零变更、全计 skipped 返回;
+     * 事务形(§5 F2 + §6 F5 + K4,一步不省):
+     *   ① `holdLock` 钩(首句;部署的 hold 哨兵行锁读)—— `"held"` ⇒ 本事务零变更、全计 skipped 返回;
      *   ② 候选读 + CAS UPDATE;
-     *   ③ 审计行(同事务)→ COMMIT。**没有**提交前的第二次 hold 复核:域的行锁在 ① 就拿住了并持有到
+     *   ③ `audit` 钩(提交前末句;部署的审计行,同事务)→ COMMIT。**没有**提交前的第二次 hold 复核:域的行锁在 ① 就拿住了并持有到
      *      COMMIT,一个并发的 PUT hold 在此期间提交不了(它抢同一把锁)——一段恒真的"复核"比没有更坏。
      *
      * 视界判据**两条臂都写出来**:`deadline` 在场按 deadline,缺席按 `created_at_ms`。少了后一条臂,一条
@@ -310,7 +217,10 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * receipt 口径:`deleted` = **本次 CAS 赢下的行数**(过期销毁的是那道 pending 门,行本身按设计留在库里
      * 供审计/对账);`tombstones` = 0(没有行被移除,写墓碑会让「墓碑 ⇒ 这行没了」这条读法失真)。
      */
-    expireCheckpoints(input: RetentionCallInput): Promise<RetentionReceipt>;
+    expireCheckpoints(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
     /**
      * 视界谓词的两条臂(`deadline` 在场按 deadline、缺席按 `created_at_ms`)—— 两方言逐字相同,占位符各自编号。
      * 抽成一处是因为它同时被「可过期候选」与「被 pin 的计数」两条查询用,手抄两份必分家。
@@ -400,26 +310,28 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * lineage-aware 的会话树删除。**引用在删除事务内重查**(core 契约逐字:「references are re-checked inside
      * the deletion transaction, never assumed from a prior scan」),有活引用的树**整棵**跳过计 `skipped`。
      *
-     * 事务形(§5 F2 + §6 F5):
-     *   ① `retention_hold` 哨兵行的**锁读** —— `held=1` ⇒ 零删、全 skip 返回;锁持有到 COMMIT;
+     * 事务形(§5 F2 + §6 F5 + K4):
+     *   ① `holdLock` 钩(首句;部署的 hold 哨兵行锁读)—— `"held"` ⇒ 零删、全 skip 返回;锁持有到 COMMIT;
      *   ② **一条**加锁读同时完成「候选 + 活引用重查」(谓词下推 + `FOR UPDATE`,见
-     *      {@link SqlRetentionStore.sessionCandidates});
-     *   ②′ 读写序律的写者半:锁住候选行之后,逐只用**本事务的连接、新语句**锁定读一次认领(`lockRootAndReadClaim`);有认领的树整棵跳过;
-     *   ③ 按 E21 顺序逐表删 → 墓碑 → 审计行(同事务)→ COMMIT。
+     *      {@link SqlRetentionStore.sessionCandidates});每只候选的会话行在此锁住;
+     *   ②′ 读写序律的写者半 = `session.beforeCommit` 钩(每只候选根一次,`op: "retention-delete"`;会话座的那一只钩):用**本事务的连接、新语句**锁定读一次认领;
+     *      有认领 ⇒ `{ refuse }`,整棵跳过;然后 `liveReferences` 钩(余下候选;部署不给 ⇒ 空集);
+     *   ③ `beforeDelete` 钩(终集,行带化身:部署删它的十一张表、自算结束了的空间)→ 本执行器按序删引擎座表({@link SqlRetentionStore.purgeSessionTrees})
+     *      → 墓碑 → `audit` 钩(提交前末句,同事务)→ COMMIT。
      *
      * 🔴 活引用重查为什么是**候选查询本身**而不是第二条查询(codex 交叉复审 R1 的两条 high 合并采纳):
      *  · 两条查询之间有窗口,而下推之后「被查到的」按构造就是「四条腿一条都不命中的」;
      *  · `FOR UPDATE` 让这些会话行在本事务期间不可被 `touch()` 拉回视界、也不可被 session-sync 改写属主 ——
      *    旧形(不加锁 + 尾部无条件删 `session_event`)可以在属主被并发改写后,把**别的租户**的历史删掉;
      *  · 旧形还在删完 `task_active` **之后**才去复核它,那道复核因此恒真(自己刚把证据删了)—— 一段恒真的
-     *    "防护"比没有更坏。删除之前的判据是候选查询 + ②′ 那一读,删除后不再假装复核。
+     *    "防护"比没有更坏。删除之前的判据是候选查询 + ②′ 那一读(会话座的 `beforeCommit` 钩),删除后不再假装复核。
      * 与认领的互斥(共同锁序,读写序律两半):
      *  · 认领半:`createRun` 在认领事务里**先锁根会话行**(`session_meta … FOR UPDATE`)再插 `task_active`(`run-store-sql.ts` 的 `createRun` 顶注)
      *    ⇒ 候选查询锁住会话行之后才来的认领等在那一行上,本事务提交后它锁定读到零行 ⇒ `sessionAbsent`,不建行;
-     *  · 写者半(②′):候选查询开始时**已经持着**会话行锁、尚未提交的认领 —— 候选查询等它提交后才拿到行锁,而那条 `NOT EXISTS task_active`
+     *  · 写者半(②′,会话座的 `beforeCommit` 钩):候选查询开始时**已经持着**会话行锁、尚未提交的认领 —— 候选查询等它提交后才拿到行锁,而那条 `NOT EXISTS task_active`
      *    读的是语句开始时的快照(PG 读已提交下非目标表按语句快照读),看不见刚提交的认领;②′ 是行锁之后的**新语句**锁定读(PG 新快照、TiDB 当前读),
      *    认领已提交就读得到 ⇒ 这棵树跳过。被锁住的根行上不会再有新认领(认领先锁根行),所以 ②′ 之后到提交之间没有窗。
-     *    `skipped` 仍由 {@link SqlRetentionStore.countProtectedSessions} 独立测得(非锁定读:PG 新语句看得见这一只,TiDB 读事务快照可能少计它一只 —— 回执的计数口径,不是删除判据)。
+     *    被拒的树计进 `skipped`(K4:拒 ⇒ 计 skipped,见下「receipt 口径」)。
      *
      * 活引用的四条腿(与设计稿 §2 的清单对表,并如实标注一条**结构上不存在**的边):
      *   · `task_active` —— 活跑 claim(在线协调器的第一道门,同一张表同一条判据);
@@ -431,35 +343,34 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *     会话悬空(它的字节是它自己的),所以这条边**结构上不需要保护**。设计稿把「fork 子」列进 lineage
      *     清单是按 core 契约的通用措辞抄的;本仓的 fork 语义使它落空,记在这里免得后人当缺口再"补"一次。
      *
-     * receipt 口径:`deleted` = **删掉的会话树棵数**(= `session_meta` 的命中行数),不是级联删掉的总行数
+     * receipt 口径:`skipped` = 本域过视界、本轮没删的树:{@link SqlRetentionStore.countProtectedSessions} 独立测得的受保护数 + 钩放下的候选
+     * (`beforeCommit` 拒的、`liveReferences` 引的 —— 候选读排除了受保护的树,两部分各自测得、各自 ≥ 0)。账法与
+     * {@link SqlRetentionStore.countPinnedExpiryCandidates} 同一条:中途翻转的树(例:PG 上候选读等锁期间提交的认领 —— 被拒,计数语句又看得见它)最多两边各记一次,
+     * 刻意选的失真方向是轻微重复计数。
+     * `deleted` = **删掉的会话树棵数**(= `session_meta` 的命中行数),不是级联删掉的总行数
      * ——后者跨十余张表、随部署形态漂(附件表可能不在场),做不成稳定判据;而「幂等重跑 ⇒ 0」这条契约在
      * 两种口径下同真。`tombstones` = 本次**新落地**的墓碑数(重跑时既有墓碑不重复计)。
      */
-    deleteExpiredSessions(input: RetentionCallInput): Promise<RetentionReceipt & {
-        readonly endedSpaces?: readonly EndedSpace[];
-    }>;
+    deleteExpiredSessions(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
     /**
-     * E21 顺序契约的**事务化搬入**:同一组 DELETE、同一个顺序,一次性发在一条事务连接上。
-     * 顺序的两条承重理由(其余是可读性):
-     *   · `checkpoint` / `checkpoint_ctx` 的属主门是 `session_meta.owner` 的 EXISTS 子查询 ⇒ 它们**必须**排在
-     *     `session_meta` 删除**之前**(meta 一没,门就恒假、一行都删不掉);
-     *   · `task_event` / `task_active` 经 `task_run` 连删 ⇒ 必须排在 `task_run` 删除**之前**。
-     * 在线协调器那边「子表先删、meta 最后」的次序还额外承担**跨事务崩溃**语义(半途失败时 meta 仍在 ⇒ 幂等
-     * 重试能收敛);本方法整段在一个事务里,那条理由在这里不成立,但次序照抄不改 —— 两条腿的等价断言
-     * (E21)比的就是"同一条契约的两个执行体",让次序分家等于自愿放弃那条判据。
+     * 会话树里**引擎座表**这一半的删除:同一组 DELETE、同一个相对次序,发在执行器事务的连接上。部署的十一张表在这之前已由
+     * `beforeDelete` 钩删完(K4 次序:部署行先于执行器行;部署那一半见 `plugins/retention-deployment.ts`)。
+     * 次序的承重理由:
+     *   · `checkpoint` 的属主门是 `session_meta.owner` 的 EXISTS 子查询 ⇒ 它**必须**排在 `session_meta` 删除**之前**
+     *     (meta 一没,门就恒假、一行都删不掉);部署钩里的 `checkpoint_ctx` 同一道门,同一条理由(钩先于本方法,天然满足);
+     *   · file-history 的 scope 哨兵先锁、再删它的行;`session_policy` 先于 `session_policy_rev_mark`(两条锁序理由见各腿注)。
+     * 引擎 [ref] 的会话树步表(`RETENTION_SESSION_TREE_STEPS`)里本方法执行的是 6(检查点)/ 7(工具结果)/ 8(会话策略)/ 9(文件历史)/
+     * 11(会话本体)五步,相对次序与表同;1–5 与 10 共六步(workflow journal 与 run、后台子代与其信箱、名册、会话信箱)本执行器不删
+     * —— 留存路径不过会话删除级联是登记过的既有欠(对表钉在 `test/retention-hook-order.test.ts`)。
      *
-     * 属主门的一处**有意改写**(而不是照抄 `<=>`):在线协调器传的是"这个会话的 owner"(可能是 SQL NULL),
+     * 属主门的一处**有意改写**(而不是照抄在线协调器的 `<=>`):在线协调器传的是"这个会话的 owner"(可能是 SQL NULL),
      * 留存腿传的是**域键**(字符串,`""` 表示无主桶)⇒ 用 {@link SqlRetentionStore.domainWhere} 表达
      * `(owner IS NULL OR owner = '')`。对有主域两者逐字等价(`col = ?` ⟺ `col <=> ?`,参数非 NULL);
      * 对无主域,`<=>` 拿字符串 `""` 去比 NULL 会**一行都不匹配** —— 那正是「无主会话永远清不掉」的病。
-     * 这条改写只对 **`session_meta.owner` 这一族门**(meta / checkpoint / checkpoint_ctx)成立。
-     *
-     * 🔴 运行账本(task_event / task_active / task_run)**没有**属主门,按 `session_id` 单键删(F-A,2026-08-17
-     * 合并码扫描;与在线协调器同刀改):`task_run.owner` 是**每次提交的 principal**,与会话主会分叉(无主存量
-     * 会话被带 principal 的壳续聊 ⇒ 新行 owner="default")。行级属主门于是只删得掉半棵树,而 `session_meta`
-     * 在同一事务里已经删掉 ⇒ {@link SqlRetentionStore.sessionCandidates} 从此**永远枚举不到**这些行:它们不是
-     * "下一轮再清",是**没有任何清理路径**的孤儿。域隔离不靠这道门承担 —— `ids` 已经是**本域** session_meta
-     * 里选出来并 `FOR UPDATE` 锁住的候选集,行级门去掉之后越域仍然结构上不可能。
+     * 这条改写只对 **`session_meta.owner` 这一族门**(meta / checkpoint,以及部署钩里的 checkpoint_ctx)成立。
      */
     protected purgeSessionTrees(conn: SqlTxConn, domain: string, ids: readonly string[]): Promise<number>;
     /**
@@ -478,9 +389,12 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *    都是猜;实体清理归既有的 TTL 腿(core `ToolResultStore.reap`,`boot/reapers.ts` 驱动)。这与 core 的
      *    「an UNOWNED entry is never deleted」是同一条纪律的两处执行点。
      *
-     * 事务形与另外两只方法逐字同款(hold 哨兵行锁读 → 删除+墓碑 → 审计行,同 commit 同 rollback)。
+     * 事务形与另外两只方法逐字同款(`holdLock` 钩首句 → 删除+墓碑 → `audit` 钩末句,同 commit 同 rollback)。
      */
-    deleteOrphanToolResults(input: RetentionCallInput): Promise<RetentionReceipt>;
+    deleteOrphanToolResults(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<RetentionReceipt>;
     /** 「活转录可达」的行数(属主会话仍在 `session_meta`、域是本域、行已过视界)= receipt 的 `skipped`。 */
     protected countLiveReachableToolResults(exec: {
         query: SqlDriver["query"];
@@ -489,12 +403,4 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
         cutoffMs: number;
     }): Promise<number>;
 }
-/** MySQL-protocol (TiDB) binding。 */
-export declare class TiDBRetentionStore extends SqlRetentionStore {
-    constructor(pool: MySqlPool, opts: SqlRetentionStoreOptions);
-}
-/** PostgreSQL binding。 */
-export declare class PgRetentionStore extends SqlRetentionStore {
-    constructor(pool: PgPool, opts: SqlRetentionStoreOptions);
-}
 //# sourceMappingURL=retention-store-sql.d.ts.map