@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/retention-declaration.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 托管留存的**声明词**(部署说的话):三只被托管的 SQL 店交给引擎的 `retention` 词,与「本部署跑不跑扫车道」这一个事实。
+ *
+ * 为什么不住在执行器文件里:执行器(`stores-sql/retention-store-sql.ts`)是阶段三逐字搬进引擎包的那一半;「这只店的行有没有人按期删」是**部署**知道的事
+ * (扫车道开不开),声明词由装配它的部署给 —— 引擎包里同一个事实读 `retention` 选项(必填,部署表态),不读店类常量。阶段三这两只常量随店类常量一起退役。
+ */
+import type { RetentionDeclaration } from "@sema-agent/core";
+/**
+ * 三只**被托管**的 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`(`stores-sql/retention-store-sql.ts`)—— 它是 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;
+//# sourceMappingURL=retention-declaration.d.ts.map

package/dist/plugins/retention-declaration.js

@@ -0,0 +1,9 @@
+export const MANAGED_RETENTION = "managed";
+export const UNMANAGED_RETENTION = "none";
+export function retentionSweepRuns(sweep) {
+    return sweep.intervalSec > 0;
+}
+export function sqlStoreRetention(sweep) {
+    return retentionSweepRuns(sweep) ? MANAGED_RETENTION : UNMANAGED_RETENTION;
+}
+//# sourceMappingURL=retention-declaration.js.map

package/dist/plugins/retention-deployment.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 托管留存的**部署那一半** —— 本仓的表经执行器(`stores-sql/retention-store-sql.ts`)的事务内钩表(K4)参与同一个破坏性事务。
+ * 执行器是事务属主(开 / 提交 / 回滚),只认 core 的 `{domain, cutoffMs}`;部署的事实(hold、审计行的判定时点三格、认领、十三张部署表、
+ * 被删附件行的字节哈希)全在这里,经钩出场:
+ *   · `holdLock`(首句)  —— hold 哨兵行锁读(`retention-lane-store-sql.ts` 的 {@link lockHoldSentinel});
+ *   · `beforeDelete`(终集)—— 删十三张部署表里这批会话的行(下面 {@link deleteDeploymentSessionRows}),并收集被删附件行的字节哈希(提交之后交收尾);
+ *   · `audit`(提交前末句)—— 破坏性审计行({@link appendDestructiveAuditRow}),判定时点三格是这一次调用的。
+ * 认领判(每只候选根的 `session.beforeCommit`)不在这里:它是会话座的钩(`plugins/session-store-sql.ts` 的 `createSqlSessionWriteHooks`,
+ * `retention-delete` 臂),组合座把同一只交给执行器 —— 一处实现。
+ * 钩只拿语句面(`query`),从不碰事务本身;库外副作用(附件字节、完成信箱围栏、会话信箱盒、空间)不在钩里做 —— 执行器提交成功返回之后,
+ * 组合座把删掉的会话树交给收尾(`session-erase.ts`,与在线删除同一只)。
+ *
+ * 钩表为什么**每次破坏性调用**铸一份(组合座 `plugins/store-backend.ts` 的 `createSqlRetentionExecutor`):审计行的 `{mode, policyDays,
+ * fencingToken}` 与 `checkpoint_ctx` 属主门要的域是**这一次调用**的事实,而 core 的钩签名不带它们(`audit` 收 `{domain, op}` 与回执,
+ * `beforeDelete` 只收行)。
+ *
+ * ── 方言差异(只列本文件独有的;其余见执行器顶注)──────────────────────────────────────────────────
+ *   - 级联 DELETE 的 JOIN 形:`DELETE te FROM a te JOIN b …` vs `DELETE FROM a te USING b …`
+ */
+import type { ManagedRetentionCapability, RetentionReceipt } from "@sema-agent/core";
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+import { type RetentionAuditContext } from "./retention-lane-store-sql.js";
+import type { SessionTreesErased } from "../session-erase.js";
+/**
+ * lane 消费的**执行器**面 —— core `ManagedRetentionCapability` 的三方法 + 非契约窄读口 `previewRetention`
+ * (audit-only 档的读数源;core 契约无 count 面)+ 声明位。真身 = 组合座 `createSqlRetentionExecutor`。
+ *
+ * 🔴 三方法的入参是 core 契约形的**超集**(多一个必填的 `audit`):判定时点三格是部署的事实,组合座把它绑进这一次调用的 audit 钩
+ * —— 写进类型,让「忘了传」是编译错。
+ */
+export interface RetentionExecutor {
+    readonly retention?: "managed" | "none";
+    listRetentionDomains(): Promise<readonly string[]>;
+    previewRetention(input: {
+        domain: string;
+        cutoffMs: number;
+    }): Promise<{
+        checkpoints: number;
+        sessions: number;
+        toolResults: number;
+    }>;
+    expireCheckpoints(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+    deleteExpiredSessions(input: RetentionDestructiveInput): Promise<RetentionSessionsReceipt>;
+    deleteOrphanToolResults(input: RetentionDestructiveInput): Promise<RetentionReceipt>;
+}
+/** 破坏性调用的入参(判定时点的三格随行 —— 理由逐字见 {@link RetentionAuditContext} 的头注)。 */
+export interface RetentionDestructiveInput {
+    domain: string;
+    cutoffMs: number;
+    audit: RetentionAuditContext;
+}
+/**
+ * 会话树 sweep 的回执 = core 契约的 `RetentionReceipt` + 本仓一位:`erased` = 本次删掉的会话树交收尾的那一份(会话 + 删前属主 + 住客、附件字节哈希、
+ * 无出处卸载结果数),present-iff 删掉了至少一棵树。lane 把它交给收尾(`session-erase.ts` 的 `createSessionEraseSettler`,与会话删除协调器同一只)。
+ */
+export type RetentionSessionsReceipt = RetentionReceipt & {
+    readonly erased?: SessionTreesErased;
+};
+/** 装配面必须如实告知的**可选部署表在场性**(+ 执行器的诊断日志座)。 */
+export interface RetentionExecutorOptions {
+    /**
+     * `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;
+    /**
+     * 收件箱四表(`mailbox` / `mailbox_message` / `mailbox_consumed` / `mailbox_tombstone`)是否在场。**必填,没有默认值**(同上一条理由)。
+     * 生产上 `boot/stores.ts` 在**任何 SQL 后端**都无条件 ensure 这四张表并接上 SQL 信箱店 ⇒ 装配层照实传 true;为真时执行体在同一个事务里、
+     * 会话行删除之前的最后一腿丢掉被删会话的会话盒(店的 `drop` 同一组语句,`dropMailboxBoxOn`)。
+     */
+    mailboxTables: boolean;
+    /**
+     * workflow 完成信箱在不在用(本部署接了完成信箱 = 有 enqueue 方)。**必填,没有默认值**。为真时执行体在事务里给被删会话立清除围栏
+     * (信箱 `purge` 的同一句 `writeInboxPurgeFenceOn`),提交之后再清一次事务里落下的迟到行({@link sweepLateCompletionRows});为假时没有 enqueue 方、
+     * 也就没有围栏要立(围栏行只由信箱自己的写动词顺手扫,没有信箱就没人扫 ⇒ 不写)。
+     */
+    completionInbox: boolean;
+    /** 诊断日志座(可选;交给执行器)。 */
+    logger?: {
+        info?(msg: string, meta?: unknown): void;
+        warn?(msg: string, meta?: unknown): void;
+    };
+}
+/** 执行器会删东西的那几只成员(钩被告知的 `op`;与执行器钩表的同名型同读 core 的键集)。 */
+type RetentionOp = Exclude<keyof ManagedRetentionCapability, "listRetentionDomains">;
+/**
+ * 删净之后清一次**迟到的完成信箱行**:执行体事务里立的清除围栏提交之前别的连接看不见,事务进行中入队的完成会落行。按「这只会话 ∧ **删前属主** ∧ 入队时刻不晚于 `atMs`」删
+ * —— 与清除围栏同一把键(会话 × 属主):别的属主的行(同 id 重登记的别人)一行不碰;同一属主同 id 的下一位住客在围栏的窗内入队即被拒(`workflow_inbox_fence`),
+ * 它的行落不下 ⇒ 这一句只可能删到事务进行中漏进来的那几行。发在池上(提交之后);属主一组一句(`owner` 列可空,无主 = `IS NULL`)。
+ */
+export declare function sweepLateCompletionRows(db: SqlExec, dialect: SqlDialect, sessions: readonly {
+    readonly sessionId: string;
+    readonly owner: string | null;
+}[], atMs: number): Promise<void>;
+/**
+ * 部署行那一半的钩(`beforeDelete`:删这批会话在部署十三张表里的行)+ 它收集到的附件字节哈希(提交之后交收尾释放)。两种破坏性调用同一只:
+ * 留存清扫({@link createRetentionDeploymentHooks})与删一只会话(组合座 `createSqlSessionEraser`)。`domain` = 这批会话的域键(`checkpoint_ctx` 属主门读它)。
+ */
+export declare function createSessionRowsHook(dialect: SqlDialect, opts: RetentionExecutorOptions, domain: string): {
+    beforeDelete: (txn: SqlExec, rows: readonly {
+        readonly sessionId: string;
+        readonly incarnation: string | undefined;
+    }[]) => Promise<void>;
+    attachmentShas: () => readonly string[];
+};
+/**
+ * 一次留存破坏性调用的钩表 + 它收集到的附件字节哈希。`call` = 这一次调用(域与判定时点三格)。
+ * 钩的形对齐执行器的 `SqlTransactionHooks`(组合座把 `hooks` 交给执行器时由类型系统对表,形一分叉就编译红)。
+ */
+export declare function createRetentionDeploymentHooks(dialect: SqlDialect, opts: RetentionExecutorOptions, call: RetentionDestructiveInput): {
+    hooks: {
+        retention: {
+            holdLock: (txn: SqlExec, at: {
+                readonly domain: string;
+                readonly op: RetentionOp;
+            }) => Promise<"proceed" | "held">;
+            beforeDelete: (txn: SqlExec, rows: readonly {
+                readonly sessionId: string;
+                readonly incarnation: string | undefined;
+            }[]) => Promise<void>;
+            audit: (txn: SqlExec, at: {
+                readonly domain: string;
+                readonly op: RetentionOp;
+            }, receipt: RetentionReceipt) => Promise<void>;
+        };
+    };
+    attachmentShas: () => readonly string[];
+};
+/**
+ * 会话树里**部署表**这一半的删除(`beforeDelete` 钩的身体):十三张部署表,发在执行器事务的连接上,先于执行器删自己的表(K4 次序)。
+ * 两个决定者同调(留存清扫 / 删一只会话的 `eraseSession`)—— 删净会话的行面只有执行器那一段事务体(`session-erase.ts` 头注);表与腿序对
+ * `SESSION_TREE_LEGS`(local 执行体按它迭代各店动词)。
+ * 次序的承重理由:
+ *   · `task_event` / `task_active` 经 `task_run` 连删 ⇒ 必须排在 `task_run` 删除**之前**;
+ *   · `checkpoint_ctx` 的属主门是 `session_meta.owner` 的 EXISTS 子查询 ⇒ 必须在 meta 删除之前(执行器的 meta 删除在本钩之后,天然满足);
+ *   · 任务清单:meta 行锁 → item → meta(与 `mutate` 同向的锁序,见该腿注)。
+ *
+ * 🔴 运行账本(task_event / task_active / task_run)**没有**属主门,按 `session_id` 单键删(F-A,2026-08-17
+ * 合并码扫描):`task_run.owner` 是**每次提交的 principal**,与会话主会分叉(无主存量
+ * 会话被带 principal 的壳续聊 ⇒ 新行 owner="default")。行级属主门于是只删得掉半棵树,而 `session_meta`
+ * 在同一事务里随后就删掉 ⇒ 执行器的候选读从此**永远枚举不到**这些行:它们不是
+ * "下一轮再清",是**没有任何清理路径**的孤儿。域隔离不靠这道门承担 —— `ids` 已经是**本域** session_meta
+ * 里选出来并 `FOR UPDATE` 锁住的终集,行级门去掉之后越域仍然结构上不可能。
+ *
+ * `checkpoint_ctx` 的属主门用**域键**(`domain`,`""` = 无主桶)而不是会话的 owner 值 —— 理由逐字见执行器 `purgeSessionTrees` 头注「属主门读域键」段。
+ */
+export declare function deleteDeploymentSessionRows(txn: SqlExec, dialect: SqlDialect, domain: string, ids: readonly string[], opts: RetentionExecutorOptions): Promise<readonly string[]>;
+export {};
+//# sourceMappingURL=retention-deployment.d.ts.map

package/dist/plugins/retention-deployment.js

@@ -0,0 +1,119 @@
+import { TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE, taskListKeyFor } from "./task-list-store-sql.js";
+import { USER_INPUT_ACCEPTANCE_TABLE } from "./user-input-ledger-sql.js";
+import { deleteSessionApprovalRows } from "./approval-ask-store-sql.js";
+import { retentionDomainWhere, retentionIdSet } from "./retention-sql.js";
+import { appendDestructiveAuditRow, lockHoldSentinel } from "./retention-lane-store-sql.js";
+import { writeInboxPurgeFenceOn } from "./workflow-run-store-sql.js";
+function auditActionOf(op) {
+    switch (op) {
+        case "expireCheckpoints":
+            return "expired_checkpoints";
+        case "deleteExpiredSessions":
+            return "deleted_sessions";
+        case "deleteOrphanToolResults":
+            return "deleted_tool_results";
+    }
+}
+export async function sweepLateCompletionRows(db, dialect, sessions, atMs) {
+    const byOwner = new Map();
+    for (const { sessionId, owner } of sessions)
+        byOwner.set(owner, [...(byOwner.get(owner) ?? []), sessionId]);
+    for (const [owner, ids] of [...byOwner].sort(([a], [b]) => String(a).localeCompare(String(b)))) {
+        const s = retentionIdSet(dialect, "session_id", [...ids].sort(), 1);
+        const next = (k) => (dialect === "mysql" ? "?" : `$${s.params.length + k}`);
+        const ownerSql = owner === null ? "owner IS NULL" : `owner = ${next(1)}`;
+        const at = next(owner === null ? 1 : 2);
+        await db.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql} AND ${ownerSql} AND enqueued_at_ms <= ${at}`, [...s.params, ...(owner === null ? [] : [owner]), atMs]);
+    }
+}
+export function createSessionRowsHook(dialect, opts, domain) {
+    const shas = [];
+    return {
+        beforeDelete: async (txn, rows) => {
+            shas.push(...(await deleteDeploymentSessionRows(txn, dialect, domain, rows.map((r) => r.sessionId), opts)));
+        },
+        attachmentShas: () => shas,
+    };
+}
+export function createRetentionDeploymentHooks(dialect, opts, call) {
+    if (!call.audit) {
+        throw new Error(`retention: refusing a destructive call in domain ${JSON.stringify(call.domain)} with no audit context — every destructive retention ` +
+            `transaction must persist its {mode, policyDays, fencingToken} alongside the deletion. Pass \`audit\` from the sweep lane's current round.`);
+    }
+    const rowsHook = createSessionRowsHook(dialect, opts, call.domain);
+    const hooks = {
+        retention: {
+            holdLock: async (txn, at) => (await lockHoldSentinel(txn, dialect, at.domain)) ? "held" : "proceed",
+            beforeDelete: rowsHook.beforeDelete,
+            audit: async (txn, at, receipt) => appendDestructiveAuditRow(txn, dialect, {
+                domain: at.domain,
+                action: auditActionOf(at.op),
+                audit: call.audit,
+                deleted: receipt.deleted,
+                skipped: receipt.skipped,
+                tombstones: receipt.tombstones,
+            }),
+        },
+    };
+    return { hooks, attachmentShas: rowsHook.attachmentShas };
+}
+export async function deleteDeploymentSessionRows(txn, dialect, domain, ids, opts) {
+    const q = (mysql, pg) => (dialect === "mysql" ? mysql : pg);
+    const set = (col, pgIndex) => retentionIdSet(dialect, col, ids, pgIndex);
+    {
+        const s = set("tr.session_id", 1);
+        await txn.query(q(`DELETE te FROM task_event te JOIN task_run tr ON te.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_event te USING task_run tr WHERE te.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
+    }
+    {
+        const s = set("tr.session_id", 1);
+        await txn.query(q(`DELETE ta FROM task_active ta JOIN task_run tr ON ta.task_id = tr.task_id WHERE ${s.sql}`, `DELETE FROM task_active ta USING task_run tr WHERE ta.task_id = tr.task_id AND ${s.sql}`), [...s.params]);
+    }
+    {
+        const s = set("session_id", 1);
+        await txn.query(`DELETE FROM task_run WHERE ${s.sql}`, [...s.params]);
+    }
+    await deleteSessionApprovalRows(txn, dialect, ids);
+    {
+        const s = set("checkpoint_ctx.session_id", 1);
+        const w = retentionDomainWhere(dialect, "sm.owner", domain, 2);
+        await txn.query(`DELETE FROM checkpoint_ctx WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint_ctx.session_id AND ${w.sql})`, [...s.params, ...w.params]);
+    }
+    let attachmentShas = [];
+    if (opts.taskAttachmentTable) {
+        const s = set("session_id", 1);
+        const { rows } = await txn.query(`SELECT sha256 FROM task_attachment WHERE ${s.sql} FOR UPDATE`, s.params);
+        attachmentShas = rows.map((r) => String(r.sha256));
+    }
+    for (const [table, col] of [
+        ["resume_anchor", "session_id"],
+        ["approval_exemption", "session_id"],
+        ...(opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
+        [USER_INPUT_ACCEPTANCE_TABLE, "session_id"],
+    ]) {
+        const s = set(col, 1);
+        await txn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
+    }
+    if (opts.taskListTables) {
+        const listKeys = ids.map((id) => taskListKeyFor(id)).sort();
+        {
+            const s = retentionIdSet(dialect, "list_key", listKeys, 1);
+            await txn.query(`SELECT list_key FROM ${TASK_LIST_META_TABLE} WHERE ${s.sql} ORDER BY list_key FOR UPDATE`, s.params);
+        }
+        for (const table of [TASK_LIST_ITEM_TABLE, TASK_LIST_META_TABLE]) {
+            const s = retentionIdSet(dialect, "list_key", listKeys, 1);
+            await txn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
+        }
+    }
+    {
+        if (opts.completionInbox) {
+            const owner = domain === "" ? null : domain;
+            const now = Date.now();
+            for (const id of [...ids].sort())
+                await writeInboxPurgeFenceOn(txn, dialect, id, owner, now);
+        }
+        const s = set("session_id", 1);
+        await txn.query(`DELETE FROM workflow_completion_inbox WHERE ${s.sql}`, s.params);
+    }
+    return attachmentShas;
+}
+//# sourceMappingURL=retention-deployment.js.map

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -23,14 +23,84 @@
  *     自增判据在**应用层**算,因为它同时要产出返回给调用方的 token);
  *   - 事务动词:只有 `begin()` 一个;读语义的判据在 {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`
  *     (本店唯一的读是 `acquire` 的租约行 `FOR UPDATE` —— 锁读在两引擎都是当前读)。
- *   - schema 属主:**四张表全部由车1 的 `retention-store-sql.ts` 建**(`TIDB_RETENTION_STATEMENTS` /
- *     `PG_RETENTION_SCHEMA`)。本文件一条 DDL 都不发 —— 「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
+ *   - schema 属主:**审计 / hold / 租约三张表由本文件建**(`TIDB_RETENTION_LANE_STATEMENTS` / `PG_RETENTION_LANE_SCHEMA`,
+ *     中央 ensure 组合);墓碑表是执行器的(`stores-sql/retention-store-sql.ts`)。「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
  *     的实测结论:第二个属主的 `IF NOT EXISTS` 会静默吞掉列/索引差异)。
+ *   - 执行器破坏性事务里的两句也写在这里(`lockHoldSentinel` 首句 / `appendDestructiveAuditRow` 末句):hold / 审计是**调度方语义**,
+ *     经执行器的事务内钩(K4)参与,不住在执行器里。
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import { type SqlDriver, type SqlExec } from "./sql-driver.js";
-import { type RetentionAuditAction } from "./retention-store-sql.js";
+import { type SqlDialect, type SqlDriver, type SqlExec } from "./sql-driver.js";
+import type { IndexSpec } from "./ensure-index.js";
+import type { RetentionMode } from "../config-types.js";
+/** 追加式审计表(设计稿 §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";
+/**
+ * 审计行的 `action` 闭集(设计稿 §6 逐字)。**破坏性三词**在执行器的删除事务里由 audit 钩写({@link appendDestructiveAuditRow});其余五词
+ * (`audit_only` / `skipped_legal_hold` / `failed` / `hold_placed` / `hold_released`)属主是 lane/路由(车2)
+ * —— 它们没有「删了没记」的窗口。词表与审计表同住本文件:一份真源。
+ */
+export type RetentionAuditAction = "expired_checkpoints" | "deleted_sessions" | "deleted_tool_results" | "audit_only" | "skipped_legal_hold" | "failed" | "hold_placed" | "hold_released";
+/** MySQL 协议方言的建表语句(本模块是这三张表的唯一 DDL 属主;由 `tidb-pool.ts` 展开进中央 `SCHEMA_STATEMENTS`,紧挨执行器的墓碑表那一句、次序不变)。 */
+export declare const TIDB_RETENTION_LANE_STATEMENTS: readonly string[];
+/** PG 方言的建表语句(MySQL 孪生的逐条翻译:AUTO_INCREMENT→BIGSERIAL,逐列 `COLLATE "C"`,内联 KEY→独立
+ *  CREATE INDEX)。语义逐字见 MySQL 孪生的行内注,此处不复述(两份注释迟早分叉)。由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(紧挨墓碑表那一句)。 */
+export declare const PG_RETENTION_LANE_SCHEMA: readonly string[];
+/** [ref]:三张表的索引**声明**(两方言共用一份)。PG 侧由 `pg-pool.ts` 的中央 ensure 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+export declare const RETENTION_LANE_INDEXES: readonly IndexSpec[];
+/**
+ * 一次破坏性留存调用的**审计上下文**——判定时点的三格,由调用方(lane)随每次破坏性调用交给组合座(`plugins/store-backend.ts`
+ * `createSqlRetentionExecutor`),组合座把它绑进**这一次**调用的 audit 钩(执行器入参只有 core 的 `{domain, cutoffMs}`,不认识它)。
+ *
+ * 🔴 为什么必须由调用方传、而不是店自己去读配置:`mode`/`policyDays` 是**判定时点**的事实(策略是部署
+ * env、模式是灰度旋钮,两者都会在两次 sweep 之间被改),`fencingToken` 更是本轮租约的身份。店去现读
+ * 配置 = 审计行记的是「写这行的那一刻的配置」,而不是「按哪档删的」,那正好把审计的意义抹掉。
+ */
+export interface RetentionAuditContext {
+    /** 判定时点的灰度档。词表闭集(与 §4 同一张表);`audit-only` 档下 lane 不该调破坏性方法,但如果调了,
+     *  审计行会如实记下这个矛盾(而不是被悄悄改写成 enforce)。 */
+    mode: RetentionMode;
+    /** 判定时点的策略值(天)。 */
+    policyDays: number;
+    /** 本轮 sweep lease 的 fencing token(§3)。`null` = 调用方没有租约面(单机/测试);破坏性行仍会落
+     *  审计,只是这一位为空 —— 「没有轮次身份」本身也是审计要记的事实。 */
+    fencingToken: number | null;
+}
+/**
+ * 破坏性事务的**首句**(K4 `holdLock`):拿本域的互斥行锁,并读出「这个域是不是冻结中」(§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 的写点与删除的读点压到**同一把行锁**上,那句承诺才成立。
+ * ⚠️ PUT/DELETE hold 必须走**同一 PK 的 upsert 改 `held` 列**(本模块 `setHoldOn`,不是 INSERT/DELETE 行),
+ * 否则这把锁又会退回缺席形。
+ */
+export declare function lockHoldSentinel(txn: SqlExec, dialect: SqlDialect, domain: string): Promise<boolean>;
+/**
+ * 破坏性审计行的**唯一**写点 —— 执行器事务里提交前的**末句**(K4 `audit`;§6 F5:与删除同一个事务,先删后补记 = 崩在中间会留下无证删除)。
+ * 三个数字 = 这一次调用的回执(执行器交给 audit 钩的那一份),判定时点三格 = 这一次调用的 {@link RetentionAuditContext}。
+ */
+export declare function appendDestructiveAuditRow(txn: SqlExec, dialect: SqlDialect, row: {
+    domain: string;
+    action: Extract<RetentionAuditAction, "expired_checkpoints" | "deleted_sessions" | "deleted_tool_results">;
+    audit: RetentionAuditContext;
+    deleted: number;
+    skipped: number;
+    tombstones: number;
+}): Promise<void>;
 /** 审计读面的单页上界(与 roster 名册窗同姿势:读面要有界)。 */
 export declare const RETENTION_AUDIT_MAX_LIMIT = 200;
 /** 审计读面的缺省页大小。 */

package/dist/plugins/retention-lane-store-sql.js

@@ -1,5 +1,107 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { RETENTION_AUDIT_TABLE, RETENTION_HOLD_TABLE, RETENTION_LEASE_TABLE } from "./retention-store-sql.js";
+export const RETENTION_AUDIT_TABLE = "retention_audit";
+export const RETENTION_HOLD_TABLE = "retention_hold";
+export const RETENTION_LEASE_TABLE = "retention_lease";
+export const TIDB_RETENTION_LANE_STATEMENTS = [
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_AUDIT_TABLE} (
+     id            BIGINT       NOT NULL AUTO_INCREMENT,
+     domain        VARCHAR(190) NOT NULL,
+     -- action:闭集词表见 RetentionAuditAction。前三词 = 破坏性行(本店写),其余 = lane/路由写。
+     action        VARCHAR(32)  NOT NULL,
+     -- mode:判定时点的灰度档(audit-only | enforce)——「按哪档跑的」必须与计数同行,否则事后无法解释
+     -- 一行 deleted=0 是"没有候选"还是"当时是 audit-only"。
+     mode          VARCHAR(16)  NOT NULL,
+     -- policy_days:判定时点的策略值(按哪版策略删的)。策略是部署 env,会被改;计数离开它就没有意义。
+     policy_days   INT          NOT NULL,
+     -- fencing_token:本轮 sweep lease 的 fencing token(§3;**破坏性行必填**,非破坏行可空)。丢租后
+     -- 在飞的旧轮仍可能提交一条审计行,靠这一位判别新旧轮。
+     fencing_token BIGINT       NULL,
+     -- 三数字 = RetentionReceipt(audit_only 行 = previewRetention 的三候选数)。
+     deleted       INT          NOT NULL DEFAULT 0,
+     skipped       INT          NOT NULL DEFAULT 0,
+     tombstones    INT          NOT NULL DEFAULT 0,
+     executed_at_ms BIGINT      NOT NULL,
+     error         TEXT         NULL,
+     PRIMARY KEY (id),
+     KEY idx_retention_audit_domain (domain, id),
+     KEY idx_retention_audit_executed (executed_at_ms)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
+     domain       VARCHAR(190) NOT NULL,
+     -- held:**1 = 冻结中,0 = 只是一把锁**。
+     -- 🔴 为什么冻结不能用「行在/行不在」表达(codex 对抗复审 R1-[high],验真后改的**承重**形):
+     -- 设计稿 §5 声称「PUT hold 的 commit 一旦完成,其后任何删除事务都必然看见它,串行化由行锁给出」——
+     -- 而 SELECT … FOR UPDATE **锁不住一条不存在的行**(TiDB 无 gap lock;PG 的 READ COMMITTED 同样
+     -- 不锁缺席行)。presence 形下两边都读到「没有 hold」是完全可能的,于是 operator 拿到成功回执之后
+     -- 数据仍被删 —— 那正是 F2 要消灭的那件事,只是换了个位置复发。
+     -- ⇒ 行**恒存在**(破坏性事务首步幂等建一条 held=0 的哨兵),冻结与否写在这一列上。
+     -- 于是 hold 的放置(同一 PK 的 upsert)与三只破坏性事务抢的是**同一把行锁**,串行化由引擎给出:
+     -- PUT 提交完成 ⇒ 其后每一个破坏性事务的首读必见 held=1。放置/解除都必须走这一列(车2 交接件)。
+     held         TINYINT(1)   NOT NULL DEFAULT 0,
+     placed_by    VARCHAR(190) NULL,
+     placed_at_ms BIGINT       NULL,
+     note         TEXT         NULL,
+     PRIMARY KEY (domain)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_LEASE_TABLE} (
+     -- singleton:恒 'x' 的单行键(全局唯一一只 sweep 租约)。用定值列而不是 id=1,是为了让"这张表只能有
+     -- 一行"写在**主键**上而不是写在注释里。
+     singleton     CHAR(1)      NOT NULL DEFAULT 'x',
+     holder        VARCHAR(190) NOT NULL,
+     -- fencing_token:每次**抢租**(而非续租)自增;随本轮全部审计行走,旧轮的写因此可判别。
+     fencing_token BIGINT       NOT NULL DEFAULT 0,
+     expires_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (singleton)
+   ) COLLATE utf8mb4_bin`,
+];
+export const PG_RETENTION_LANE_SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_AUDIT_TABLE} (
+     id            BIGSERIAL,
+     domain        VARCHAR(190) COLLATE "C" NOT NULL,
+     action        VARCHAR(32) COLLATE "C"  NOT NULL,
+     mode          VARCHAR(16) COLLATE "C"  NOT NULL,
+     policy_days   INT          NOT NULL,
+     fencing_token BIGINT       NULL,
+     deleted       INT          NOT NULL DEFAULT 0,
+     skipped       INT          NOT NULL DEFAULT 0,
+     tombstones    INT          NOT NULL DEFAULT 0,
+     executed_at_ms BIGINT      NOT NULL,
+     error         TEXT COLLATE "C"         NULL,
+     PRIMARY KEY (id)
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_HOLD_TABLE} (
+     domain       VARCHAR(190) COLLATE "C" NOT NULL,
+     -- held:1 = 冻结中,0 = 只是那把域级互斥行锁的哨兵。完整判据(为什么 presence 形不成立)见 MySQL 孪生。
+     held         SMALLINT     NOT NULL DEFAULT 0,
+     placed_by    VARCHAR(190) COLLATE "C" NULL,
+     placed_at_ms BIGINT       NULL,
+     note         TEXT COLLATE "C"         NULL,
+     PRIMARY KEY (domain)
+   )`,
+    `CREATE TABLE IF NOT EXISTS ${RETENTION_LEASE_TABLE} (
+     singleton     CHAR(1) COLLATE "C"      NOT NULL DEFAULT 'x',
+     holder        VARCHAR(190) COLLATE "C" NOT NULL,
+     fencing_token BIGINT       NOT NULL DEFAULT 0,
+     expires_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (singleton)
+   )`,
+];
+export const RETENTION_LANE_INDEXES = [
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_domain", columns: ["domain", "id"] },
+    { table: `${RETENTION_AUDIT_TABLE}`, name: "idx_retention_audit_executed", columns: ["executed_at_ms"] },
+];
+export async function lockHoldSentinel(txn, dialect, domain) {
+    const key = domain;
+    const q = (mysql, pg) => (dialect === "mysql" ? mysql : pg);
+    await txn.query(q(`INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES (?,0,NULL,NULL,NULL) ON DUPLICATE KEY UPDATE domain = domain`, `INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES ($1,0,NULL,NULL,NULL) ON CONFLICT (domain) DO NOTHING`), [key]);
+    const { rows } = await txn.query(q(`SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = ? FOR UPDATE`, `SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = $1 FOR UPDATE`), [key]);
+    return Number(rows[0]?.held ?? 0) === 1;
+}
+export async function appendDestructiveAuditRow(txn, dialect, row) {
+    await txn.query(dialect === "mysql"
+        ? `INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms) VALUES (?,?,?,?,?,?,?,?,?)`
+        : `INSERT INTO ${RETENTION_AUDIT_TABLE} (domain, action, mode, policy_days, fencing_token, deleted, skipped, tombstones, executed_at_ms) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)`, [row.domain, row.action, row.audit.mode, row.audit.policyDays, row.audit.fencingToken, row.deleted, row.skipped, row.tombstones, Date.now()]);
+}
 export const RETENTION_AUDIT_MAX_LIMIT = 200;
 export const RETENTION_AUDIT_DEFAULT_LIMIT = 50;
 export class SqlRetentionLaneStore {

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

@@ -0,0 +1,29 @@
+/**
+ * 托管留存的两只 SQL 谓词 —— 执行器(`stores-sql/retention-store-sql.ts`,引擎座表那一半)与部署的事务内钩(`plugins/retention-deployment.ts`,
+ * 部署表那一半)对**同一条域律**发谓词,只从这里取:一条律一个读法,两半不各写一份(分家的方向是多删或漏删)。
+ *
+ * 域 = 租户键:`COALESCE(session_meta.owner, '')` / `checkpoint.scope` 原样;**空串 `''` = 无主(anonymous/dev)桶**,谓词写成
+ * `(owner IS NULL OR owner = '')` —— 合并只发生在无主侧,永远伸不进一个真租户;拆成两个桶才会漏(NULL 那半永不被枚举)。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+/**
+ * 域谓词。**四种写法逐条写出来**(方言 × 有主/无主):
+ *  · 有主:`col = ?` / `col = $n`;
+ *  · 无主(域键 `""`):`(col IS NULL OR col = ?)` / `(col IS NULL OR col = $n)`。
+ * 🔴 两支的**占位符数量刻意相同**(无主支也绑一个 `""`):arity 一变,PG 的 `$n` 编号就会在同一条 SQL 的
+ * 后续参数上错位——那是一类只在某个域值上才复现的 bug,不许存在。
+ */
+export declare function retentionDomainWhere(dialect: SqlDialect, 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 的预编译缓存跟着退化。
+ */
+export declare function retentionIdSet(dialect: SqlDialect, col: string, ids: readonly string[], pgIndex: number): {
+    sql: string;
+    params: unknown[];
+};
+//# sourceMappingURL=retention-sql.d.ts.map

package/dist/plugins/retention-sql.js

@@ -0,0 +1,8 @@
+export function retentionDomainWhere(dialect, col, domain, pgIndex) {
+    const ph = dialect === "mysql" ? "?" : `$${pgIndex}`;
+    return domain === "" ? { sql: `(${col} IS NULL OR ${col} = ${ph})`, params: [""] } : { sql: `${col} = ${ph}`, params: [domain] };
+}
+export function retentionIdSet(dialect, col, ids, pgIndex) {
+    return dialect === "mysql" ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] } : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
+}
+//# sourceMappingURL=retention-sql.js.map

package/dist/plugins/run-preview-m45.d.ts

@@ -0,0 +1,11 @@
+/** SQL 腿的粗筛:闭集标签各一个 `LIKE` 前缀(`<tag%`;标签名里没有 `%` / `_` / 转义字符)。粗筛中、精判不中的行(`<system-reminderish …`)不动。 */
+export declare const RUN_PREVIEW_COARSE_PREFIXES_M45: readonly string[];
+/** M45 选不选这一列值:以闭集开标签起头。 */
+export declare function startsWithInjectedOpenTagM45(value: string): boolean;
+/**
+ * M45 对这一列值的新值:不选 ⇒ `undefined`(不动);选中 ⇒ 剥到不动点,仍以开标签起头 ⇒ `""`。
+ * 终止:第一遍之后的值不长于 120;此后每一遍要么逐字节不变(不动点)要么严格变短(剥块 / trim / 截都只删,脱敏对自己的产出不再命中),
+ * 所以遍数不超过「首遍结果的长度 + 1」—— 循环上界就写这个数,走出循环的那一臂不可达。
+ */
+export declare function normalizedRunPreviewM45(value: string): string | undefined;
+//# sourceMappingURL=run-preview-m45.d.ts.map

package/dist/plugins/run-preview-m45.js

@@ -0,0 +1,19 @@
+import { INJECTED_BLOCK_TAGS, buildRunObjectivePreview } from "../user-authored-text.js";
+const INJECTED_OPEN_TAG_HEAD_M45 = new RegExp(`^<(?:${INJECTED_BLOCK_TAGS.join("|")})(?=[\\s>/]|$)`);
+export const RUN_PREVIEW_COARSE_PREFIXES_M45 = INJECTED_BLOCK_TAGS.map((tag) => `<${tag}%`);
+export function startsWithInjectedOpenTagM45(value) {
+    return INJECTED_OPEN_TAG_HEAD_M45.test(value);
+}
+export function normalizedRunPreviewM45(value) {
+    if (!startsWithInjectedOpenTagM45(value))
+        return undefined;
+    let cur = buildRunObjectivePreview(value);
+    for (let pass = 0, bound = cur.length + 1; pass <= bound; pass += 1) {
+        const next = buildRunObjectivePreview(cur);
+        if (next === cur)
+            return startsWithInjectedOpenTagM45(cur) ? "" : cur;
+        cur = next;
+    }
+    return "";
+}
+//# sourceMappingURL=run-preview-m45.js.map