@sema-agent/server 7.147.0 → 7.149.0

package/dist/stores-sql/pg-session-storage.js

@@ -2,20 +2,21 @@ import { emitLeafAdvance } from "../session-leaf-bus.js";
 import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement, } from "@sema-agent/core";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
 import { WindowedSessionStorage } from "./windowed-session-storage.js";
-import { scanEpochAnchor } from "../plugins/session-epoch-anchor.js";
+import { epochAnchorPageSql, epochFloorOf, scanEpochAnchor, sqlEpochAnchorRowOf } from "../plugins/session-epoch-anchor.js";
 import { jsonColumnText } from "../plugins/sql-json-column.js";
 import { pgSafeJsonStringify } from "../plugins/pg-safe-json.js";
 import { toIso } from "../plugins/sql-row-helpers.js";
-import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
+import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertCells, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "../plugins/sql-errors.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
-import { SESSION_META_INCARNATION_COLUMN, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { SESSION_META_INCARNATION_COLUMN, SESSION_META_LINEAGE_COLUMNS, forkLineageOfRow, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
+import { withdrawSessionOn } from "./tidb-session-store.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.js";
-import { selectForkRows } from "@sema-agent/core";
-import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "../plugins/session-fork.js";
+import { forkRowCells, selectForkRows } from "@sema-agent/core";
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf, sameSourceGeneration } from "../plugins/session-fork.js";
 const statementsOn = (conn) => ({
     async query(sql, params) {
         const res = await conn.query(sql, params ?? []);
@@ -56,6 +57,8 @@ export const PG_SESSION_SCHEMA = [
      placed_at                   TIMESTAMPTZ(3),
      -- S-790 / S-506:会话化身(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN)。
      ${SESSION_META_INCARNATION_COLUMN.pg},
+     -- fork 谱系(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_LINEAGE_COLUMNS):NULL = 不是 fork 建的行 / 两列落地之前建的 fork(不回填)。
+     ${SESSION_META_LINEAGE_COLUMNS.pg},
      PRIMARY KEY (session_id)
    )`,
     `CREATE TABLE IF NOT EXISTS session_event (
@@ -91,13 +94,13 @@ export class PgSessionStorage extends WindowedSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.floorSeq, async (beforeSeq) => {
-            const res = await this.pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq < $2 AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`, [this.sessionId, beforeSeq]);
-            return res.rows;
+        return scanEpochAnchor(epochFloorOf(this.floorSeq, await this.windowFloorEntry()), async (beforeSeq) => {
+            const res = await this.pool.query(epochAnchorPageSql("pg"), [this.sessionId, beforeSeq]);
+            return res.rows.map(sqlEpochAnchorRowOf);
         }, (row) => decodeSessionEventPayload(row.payload, this.sessionId, row.seq));
     }
     static async wake(pool, sessionId) {
-        const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
+        const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS}, forked_from, forked_from_incarnation FROM session_meta WHERE session_id = $1`, [sessionId]);
         const meta = metaRes.rows[0];
         if (!meta)
             return null;
@@ -105,7 +108,13 @@ export class PgSessionStorage extends WindowedSessionStorage {
         const eventRes = await pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq >= $2 ORDER BY seq ASC`, [sessionId, floorSeq]);
         const entries = eventRes.rows.map((r) => decodeSessionEventPayload(r.payload, sessionId, r.seq));
         const placement = placementFromRow(meta);
-        const metadata = { id: sessionId, createdAt: toIso(meta.created_at), incarnation: incarnationFromCell(sessionId, meta.incarnation), ...(placement !== undefined ? { placement } : {}) };
+        const metadata = {
+            id: sessionId,
+            createdAt: toIso(meta.created_at),
+            incarnation: incarnationFromCell(sessionId, meta.incarnation),
+            ...(placement !== undefined ? { placement } : {}),
+            ...forkLineageOfRow(sessionId, meta.forked_from, meta.forked_from_incarnation),
+        };
         return new PgSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
     static async computeFloor(pool, sessionId) {
@@ -213,21 +222,42 @@ export class PgSessionStore {
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
+        await this.registerWithReceipt(sessionId, owner);
+    }
+    async registerWithReceipt(sessionId, owner) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
-                return;
+                return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
-        await this.insertMeta(sessionId, owner, undefined);
+        const incarnation = mintSessionIncarnation();
+        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        return { minted: { sessionId, owner, incarnation } };
+    }
+    async deleteSessionIf(sessionId, cond) {
+        const conn = await this.pool.connect();
+        try {
+            await conn.query("BEGIN");
+            const outcome = await withdrawSessionOn(statementsOn(conn), "pg", this.hooks, sessionId, cond);
+            await conn.query(outcome.withdrawn ? "COMMIT" : "ROLLBACK");
+            return outcome;
+        }
+        catch (err) {
+            await conn.query("ROLLBACK").catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
     }
     async createOnAcquire(sessionId, placement) {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
-    async insertMeta(sessionId, owner, placement) {
+    async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
         const now = new Date();
-        await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
-            "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +
-            "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
+        const placed = placementInsertCells(placement, now);
+        await this.pool.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
+            "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
         const res = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
@@ -312,7 +342,8 @@ export class PgSessionStore {
         throw new ForkTargetUnsettledError(target.id);
     }
     async forkToOnce(sourceId, owner, target) {
-        const metaRes = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = $1", [sourceId]);
+        const sourceRow = "SELECT leaf_id, owner, incarnation FROM session_meta WHERE session_id = $1";
+        const metaRes = await this.pool.query(sourceRow, [sourceId]);
         if (!metaRes.rows[0])
             return null;
         const leafId = metaRes.rows[0].leaf_id ?? null;
@@ -321,16 +352,20 @@ export class PgSessionStore {
         if (storage === null)
             return null;
         const point = await forkPointOf(storage);
+        const cells = forkRowCells(await storage.getMetadata());
         const eventRes = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("pg", "payload")}, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [sourceId]);
+        const afterRes = await this.pool.query(sourceRow, [sourceId]);
+        if (!sameSourceGeneration(cells.forkedFromIncarnation, metaRes.rows[0].incarnation, afterRes.rows[0]?.incarnation))
+            return null;
         const { rows, leafId: forkLeafId } = selectForkRows(eventRes.rows, leafId, point, FORK_LOG_ROW_SHAPE);
         const now = new Date();
         const conn = await this.pool.connect();
         let collided = false;
         try {
             await conn.query("BEGIN");
+            const placed = placementInsertCells(target.placement, now);
             try {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
-                    "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)", [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), ...placementInsertValues(target.placement, now)]);
+                await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}, forked_from, forked_from_incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)`, [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), ...placed.values, cells.forkedFrom, cells.forkedFromIncarnation ?? null]);
             }
             catch (err) {
                 if (!isDupKey(err))
@@ -500,33 +535,6 @@ export class PgSessionStore {
         }
         return removed;
     }
-    async deleteSession(sessionId, owner) {
-        const conn = await this.pool.connect();
-        try {
-            await conn.query("BEGIN");
-            const locked = await conn.query("SELECT session_id FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
-            if (locked.rows.length > 0)
-                settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "delete", rootSessionId: sessionId }));
-            const metaRes = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [sessionId, owner]);
-            if ((metaRes.rowCount ?? 0) > 0)
-                await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
-            await conn.query("COMMIT");
-            return (metaRes.rowCount ?? 0) > 0;
-        }
-        catch (err) {
-            try {
-                await conn.query("ROLLBACK");
-            }
-            catch {
-            }
-            if (err instanceof HookRefusal)
-                throw err.refuse;
-            throw err;
-        }
-        finally {
-            conn.release();
-        }
-    }
     get size() {
         return this.pending.size;
     }

package/dist/stores-sql/retention-store-sql.d.ts

@@ -13,8 +13,10 @@
  * 破坏性事务的次序(K4,一步不省):
  *   `holdLock`(首句)→ 候选加锁读(`FOR UPDATE`,含每只候选的会话行)→ 每只候选根 `session.beforeCommit`(仅会话树)→
  *   `liveReferences`(余下候选)→ `beforeDelete`(终集)→ 本执行器删自己的行、落墓碑 → `audit`(提交前末句)→ COMMIT。
- * 一只被某个钩放下的会话不进任何后续钩的入参。部署那一半(server 的 hold / 审计 / 认领判 / 十一张部署表)在
+ * 一只被某个钩放下的会话不进任何后续钩的入参。部署那一半(server 的 hold / 审计 / 认领判 / 十三张部署表)在
  * `plugins/retention-deployment.ts`,组合在 `plugins/store-backend.ts`(`createSqlRetentionExecutor`)。
+ * **会话树事务体是删净会话的唯一一段**({@link SqlRetentionStore.eraseTreesInTxn}):留存的 `deleteExpiredSessions` 与在线删除的 `eraseSession`
+ * (锁行 → 会话座事务内钩的 `erase` 判在删令牌 → 同一段事务体;组合座 `createSqlSessionEraser`)同调 —— 一只会话无论哪个决定者删,行面一个执行体(`session-erase.ts` 头注)。
  *
  * ── 域(domain)口径 ────────────────────────────────────────────────────────────────────────────────
  * 域 = 租户键。三张保留表各有自己的载体列:`session_meta.owner`(**可空**)、`checkpoint.scope`(非空)、
@@ -42,7 +44,7 @@
  * `test/schema-naming-invariants.test.ts` 机器执法(「一张表是一类行的集合,表名说的是『一行是什么』」)。
  * ⇒ 落库名一律单数:`retention_audit` / `retention_hold` / `retention_lease` / `retention_tombstone`。
  */
-import type { ManagedRetentionCapability, RetentionReceipt } from "@sema-agent/core";
+import { type ManagedRetentionCapability, type 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";
@@ -98,6 +100,37 @@ export interface RetentionPreview {
     sessions: number;
     toolResults: number;
 }
+/** 会话树事务体删掉的行面(两只入口同形):每只会话(id + 删前属主 + 住客化身)+ 全库无出处卸载结果数。组合座据它交收尾(`session-erase.ts`)。 */
+export interface ErasedTreeRows {
+    readonly sessions: readonly {
+        readonly sessionId: string;
+        readonly owner: string | null;
+        readonly incarnation: string | undefined;
+    }[];
+    readonly unattributableToolResults: number;
+}
+/** 会话树清扫的回执 = core 契约的三计数 + 本仓一位:`erasedRows` present-iff 本次删掉了至少一棵树。 */
+export type SessionTreesReceipt = RetentionReceipt & {
+    readonly erasedRows?: ErasedTreeRows;
+};
+/**
+ * 会话规则行的 rev 高水位记号随不随会话走 —— 会话树事务体里两个决定者**唯一**的行面之差(其余每一句同):
+ *  · `keep`(在线删除 `eraseSession`):被删会话的 workflow run 可以活过这次删除(在线删除不判在跑的 workflow),同 id 重登记之后规则的谱系
+ *    (rev 高水位 + 下一代 `gen`)必须活过行,读者才分得出「新行」与「续行」—— 店的抹除语义;
+ *  · `drop`(托管留存 `deleteExpiredSessions`):候选按定义没有活引用,那条 rev 线已无读者;记号带明文 `session_id` ⇒ 随会话树删。
+ * 在线删除也判在跑的 workflow 之日,两支合成 `drop`。
+ */
+export type RuleMarks = "keep" | "drop";
+/** 删一只在删会话(`eraseSession`)的答案(闭集):行不在 / 属主不是那一位 ⇒ `absent`;会话座的事务内钩拒(`erase`:这一行不是这只令牌的在删态)⇒ `refused`(带它的错);删完 ⇒ `erased`。三支都**先于任何 DELETE** 定。 */
+export type SessionEraseOutcome = {
+    readonly outcome: "absent";
+} | {
+    readonly outcome: "refused";
+    readonly refusal: Error;
+} | {
+    readonly outcome: "erased";
+    readonly rows: ErasedTreeRows;
+};
 /** 执行器的构造选项(core-stores-sql `SqlStorageBackendOptions` 里与留存相关的那一格 + 诊断日志座)。 */
 export interface SqlRetentionStoreOptions {
     /** 部署在执行器事务里的钩表(K4)。缺席 = 部署没有自己的表参与(没有 hold、没有审计行、没有部署行要随会话删)。 */
@@ -107,6 +140,11 @@ export interface SqlRetentionStoreOptions {
         info?(msg: string, meta?: unknown): void;
         warn?(msg: string, meta?: unknown): void;
     };
+    /**
+     * 会话盒的分区读法 —— 在场 ⇔ 收件箱四表在场(组合座按装配层的必填答案 `RetentionExecutorOptions.mailboxTables` 交入服务的唯一派生);
+     * 在场 ⇒ 会话树的最后一腿丢被删会话的会话盒(`scope = sessionBoxScope(删前属主)`)。
+     */
+    sessionBoxScope?: (owner: string | null) => string;
 }
 /** 单次调用的候选上界(**安全界,不是分批语义**)。设计稿 §3 的 v1 口径是「先由 cutoff 天然限量」,
  *  这里额外扣一个上界,理由是运维面而不是功能面:一个从未清过账的大租户会让「一个事务删十余张表的
@@ -149,10 +187,10 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
     /** 首句:部署锁读本域的 hold 记录。无钩 ⇒ 部署没有 hold 面,`proceed`。 */
     private heldBy;
     /**
-     * 每只候选根问一次部署(根的会话行已由候选读锁住)。无钩 ⇒ `proceed`;`{ refuse }` ⇒ 本轮不删这棵树,计进 `skipped`(账法见
-     * {@link SqlRetentionStore.deleteExpiredSessions} 头注「receipt 口径」)。
+     * 每只根问一次会话座的事务内钩(根的会话行已由本事务锁住):`erase`(删一只在删会话,`eraseSession`,带令牌)/ `retention-delete`(留存候选根)。
+     * 无钩 ⇒ 放行;`{ refuse }` ⇒ 交回那只错(`eraseSession` 答 `refused`;留存这棵树本轮不删、计进 `skipped`,账法见 {@link SqlRetentionStore.deleteExpiredSessions} 头注「receipt 口径」)。
      */
-    private admittedBy;
+    private refusalOf;
     /** 部署仍在引用的候选(无钩 ⇒ 空集)。 */
     private referencedBy;
     /** 提交前末句:部署的审计行。无钩 ⇒ 部署不记审计。 */
@@ -226,8 +264,13 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 抽成一处是因为它同时被「可过期候选」与「被 pin 的计数」两条查询用,手抄两份必分家。
      */
     private horizonArms;
-    /** 「这条 checkpoint 的会话被一次活跑占着」= [ref] 的 live-pinned 判据(SQL 谓词形,两方言同文本)。 */
-    private static readonly PINNED_EXISTS;
+    /**
+     * 「这张卡**所属的 run** 被一次活跑占着」= [ref] 的 live-pinned 判据(SQL 谓词形,两方言同文本;候选读、pinned 计数、
+     * CAS 更新三处同一只,`row` 只换行引用名)。连的是归属列 `host_session_id` —— run 的认领 `task_active` 挂在 run 的会话上,
+     * cascade 的级上卡自己的会话(`session_id`)上没有认领;按卡自己的会话判,一条仍挂着的 cascade run 的那张卡会被当成无主
+     * 过期,随后 run 收割把这条 run 判失败。归属为 NULL(滚动升级窗内旧副本写的行,下次起服 M49 回填)⇒ 不算被占。
+     */
+    private static pinnedExists;
     /**
      * **可过期**的候选 token(保护谓词写在 SQL 里、扣在 `LIMIT` **之前**)。
      *
@@ -316,7 +359,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      *      {@link SqlRetentionStore.sessionCandidates});每只候选的会话行在此锁住;
      *   ②′ 读写序律的写者半 = `session.beforeCommit` 钩(每只候选根一次,`op: "retention-delete"`;会话座的那一只钩):用**本事务的连接、新语句**锁定读一次认领;
      *      有认领 ⇒ `{ refuse }`,整棵跳过;然后 `liveReferences` 钩(余下候选;部署不给 ⇒ 空集);
-     *   ③ `beforeDelete` 钩(终集,行带化身:部署删它的十一张表、自算结束了的空间)→ 本执行器按序删引擎座表({@link SqlRetentionStore.purgeSessionTrees})
+     *   ③ `beforeDelete` 钩(终集,行带化身:部署删它的十三张表、自算结束了的空间)→ 本执行器按序删引擎座表({@link SqlRetentionStore.purgeSessionTrees})
      *      → 墓碑 → `audit` 钩(提交前末句,同事务)→ COMMIT。
      *
      * 🔴 活引用重查为什么是**候选查询本身**而不是第二条查询(codex 交叉复审 R1 的两条 high 合并采纳):
@@ -354,25 +397,50 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
     deleteExpiredSessions(input: {
         domain: string;
         cutoffMs: number;
-    }): Promise<RetentionReceipt>;
+    }): Promise<SessionTreesReceipt>;
+    /**
+     * **删一只在删会话**(在线删除的执行体;合同外,本仓自己的面 —— 与 `previewRetention` 同类)。与 {@link deleteExpiredSessions} 跑**同一段**会话树事务体
+     * ({@link eraseTreesInTxn}),只是「删谁」由调用方点名(删除协调器的围栏写下的令牌)而不是视界选:
+     *   E1 锁行 `session_meta … FOR UPDATE`(读属主 + 化身)—— 行不在 / 属主不是围栏判过的那一位(`owner`:域键,部署行与墓碑按它写)⇒ `absent`。
+     *      同 id 的重登记(`INSERT … ON DUPLICATE`)、围栏、认领都先锁这一行 ⇒ 都等在这把锁上;
+     *   E2 会话座的事务内钩 `erase`:这一行此刻处于 `token` 那一次删除的在删态(判官读旁表的在删令牌,同一连接)—— 不是 ⇒ `refused`(另一次删除接管了它,
+     *      或它已删完而同 id 是新住客 —— 新行不带这只令牌)。令牌只在围栏判过属主、判过认领之后写下,在删期间认领落不下 ⇒ 这里不再判属主与认领;
+     *   E3–E6 部署行(`beforeDelete` 钩)→ 引擎座行({@link purgeSessionTrees},行最后 + 命中数断言)→ 墓碑(域 = 属主,`""` = 无主桶)→ 提交;之后读一次无出处卸载结果数。
+     * 事务里只有 SQL 语句(完成信箱围栏在部署钩、会话盒在最后一腿,都在里面);对象存储字节、空间、进程态在调用方的提交之后(`session-erase.ts` 的收尾)。没有 hold / 审计:那是留存决定者的事。
+     */
+    eraseSession(input: {
+        readonly sessionId: string;
+        readonly owner: string | null;
+        readonly token: string;
+    }): Promise<SessionEraseOutcome>;
+    /**
+     * 全库无出处卸载结果数(告知数:这类行任何会话删除都删不到 ⇒ 删除不完整)。**在破坏性事务之前**读,两只入口同调:聚合读加不了锁、也不决定任何写 ⇒ 不进事务;
+     * 删一棵会话树不改它(按出处列删的行出处非空);读失败 ⇒ 抛在任何一字节被删之前(重试从同一状态开始),不会让一次已提交的删除丢掉收尾。
+     */
+    private unattributableToolResults;
+    /**
+     * **会话树事务体 —— 删净会话的唯一一段**(`eraseSession` 与 `deleteExpiredSessions` 同调;调用方已锁住这批会话行、判过认领):
+     * 部署行(`beforeDelete` 钩:部署的十三张表)→ 引擎座行({@link purgeSessionTrees})→ 墓碑。全库无出处卸载结果数在事务之前读({@link unattributableToolResults})。
+     * `domain` = 这批会话的域键(`COALESCE(owner, '')`);行面回执里每只会话的删前属主由它读回(`""` ⇒ 无主)。
+     * `ruleMarks` = 规则行的 rev 高水位记号随不随会话走 —— 两个决定者唯一的行面之差({@link RuleMarks})。
+     */
+    private eraseTreesInTxn;
     /**
-     * 会话树里**引擎座表**这一半的删除:同一组 DELETE、同一个相对次序,发在执行器事务的连接上。部署的十一张表在这之前已由
+     * 会话树里**引擎座表**这一半的删除:同一组 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`(两条锁序理由见各腿注)。
+     *   · file-history 的 scope 哨兵先锁、再抹规则行(记号随不随会话走 = {@link RuleMarks})、再删 file-history 的行。
      * 引擎 [ref] 的会话树步表(`RETENTION_SESSION_TREE_STEPS`)里本方法执行的是 6(检查点)/ 7(工具结果)/ 8(会话策略)/ 9(文件历史)/
-     * 11(会话本体)五步,相对次序与表同;1–5 与 10 共六步(workflow journal 与 run、后台子代与其信箱、名册、会话信箱)本执行器不删
-     * —— 留存路径不过会话删除级联是登记过的既有欠(对表钉在 `test/retention-hook-order.test.ts`)。
+     * 10(会话信箱,收件箱四表在场时;信箱店 `drop` 的同一组语句)/ 11(会话本体)六步,相对次序与表同;1–5 共五步
+     * (workflow journal 与 run、后台子代与其信箱、名册)本执行器不删 —— 登记过的既有欠(对表钉在 `test/retention-hook-order.test.ts`)。
      *
-     * 属主门的一处**有意改写**(而不是照抄在线协调器的 `<=>`):在线协调器传的是"这个会话的 owner"(可能是 SQL NULL),
-     * 留存腿传的是**域键**(字符串,`""` 表示无主桶)⇒ 用 {@link SqlRetentionStore.domainWhere} 表达
-     * `(owner IS NULL OR owner = '')`。对有主域两者逐字等价(`col = ?` ⟺ `col <=> ?`,参数非 NULL);
-     * 对无主域,`<=>` 拿字符串 `""` 去比 NULL 会**一行都不匹配** —— 那正是「无主会话永远清不掉」的病。
-     * 这条改写只对 **`session_meta.owner` 这一族门**(meta / checkpoint,以及部署钩里的 checkpoint_ctx)成立。
+     * 属主门读**域键**(两只入口同:留存传本轮的域,`eraseSession` 传 `owner ?? ""`),经 {@link SqlRetentionStore.domainWhere} 表达 —— `""` = 无主桶
+     * `(owner IS NULL OR owner = '')`;有主域 `owner = ?`。`<=>` 拿字符串 `""` 去比 NULL 会一行都不匹配(「无主会话永远清不掉」的病),所以这一族门
+     * (meta / checkpoint,以及部署钩里的 checkpoint_ctx)只用这一种写法。
      */
-    protected purgeSessionTrees(conn: SqlTxConn, domain: string, ids: readonly string[]): Promise<number>;
+    protected purgeSessionTrees(conn: SqlTxConn, domain: string, ids: readonly string[], ruleMarks: RuleMarks): Promise<number>;
     /**
      * 属主 session 已亡的 offloaded 结果(core 契约:「whose owning sessions are gone (or past the horizon),
      * skipping refs still reachable from live transcripts」)。

package/dist/stores-sql/retention-store-sql.js

@@ -1,6 +1,9 @@
+import { peerSessionBoxHandle } from "@sema-agent/core";
 import { incarnationFromCell } from "../session-incarnation.js";
 import { MANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { retentionDomainWhere, retentionIdSet } from "../plugins/retention-sql.js";
+import { dropMailboxBoxOn } from "./mailbox-store-sql.js";
+import { SEALED_EVENT, eraseSessionPolicyRowsOn } from "./session-policy-store-sql.js";
 export const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
 export const TIDB_RETENTION_TOMBSTONE_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${RETENTION_TOMBSTONE_TABLE} (
@@ -44,6 +47,13 @@ class RetentionAborted extends Error {
         this.why = why;
     }
 }
+class EraseRefused extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`session erase refused: ${refusal.message}`);
+        this.refusal = refusal;
+    }
+}
 export const RETENTION_SESSION_BATCH = 500;
 export const RETENTION_ROW_BATCH = 2000;
 export class SqlRetentionStore {
@@ -103,15 +113,16 @@ export class SqlRetentionStore {
             }
         }
     }
-    async admittedBy(face, rootSessionId) {
+    async refusalOf(face, write) {
+        const rootSessionId = write.rootSessionId;
         const beforeCommit = this.opts.transactionHooks?.session?.beforeCommit;
         if (beforeCommit === undefined)
-            return true;
-        const answer = await beforeCommit(face, { op: "retention-delete", rootSessionId });
+            return undefined;
+        const answer = await beforeCommit(face, write);
         if (answer === "proceed")
-            return true;
+            return undefined;
         if (typeof answer === "object" && answer !== null && answer.refuse instanceof Error)
-            return false;
+            return answer.refuse;
         throw new Error(`retention: session.beforeCommit answered ${JSON.stringify(answer)} for root ${JSON.stringify(rootSessionId)} — the closed answer set is "proceed" | { refuse }; rolling back.`);
     }
     async referencedBy(face, candidates) {
@@ -168,8 +179,8 @@ export class SqlRetentionStore {
                     const w = this.domainWhere("scope", input.domain, 2);
                     const set = this.idSet("token", doomed, 3);
                     const res = await conn.query(this.q(`UPDATE checkpoint SET status = 'expired', decided_at_ms = ? WHERE ${w.sql} AND status = 'pending' AND ${set.sql} ` +
-                        `AND NOT EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = checkpoint.session_id)`, `UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 WHERE ${w.sql} AND status = 'pending' AND ${set.sql} ` +
-                        `AND NOT EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = checkpoint.session_id)`), [Date.now(), ...w.params, ...set.params]);
+                        `AND NOT ${SqlRetentionStore.pinnedExists("checkpoint")}`, `UPDATE checkpoint SET status = 'expired', decided_at_ms = $1 WHERE ${w.sql} AND status = 'pending' AND ${set.sql} ` +
+                        `AND NOT ${SqlRetentionStore.pinnedExists("checkpoint")}`), [Date.now(), ...w.params, ...set.params]);
                     expired = res.affected;
                 }
                 const receipt = { domain: input.domain, deleted: expired, skipped: pinned, tombstones: 0 };
@@ -188,19 +199,21 @@ export class SqlRetentionStore {
             ? `((c.deadline IS NOT NULL AND c.deadline <= ?) OR (c.deadline IS NULL AND c.created_at_ms <= ?))`
             : `((c.deadline IS NOT NULL AND c.deadline <= $${pgFirst}) OR (c.deadline IS NULL AND c.created_at_ms <= $${pgFirst + 1}))`;
     }
-    static PINNED_EXISTS = `EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = c.session_id)`;
+    static pinnedExists(row) {
+        return `EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = ${row}.host_session_id)`;
+    }
     async expiryCandidates(exec, input) {
         const w = this.domainWhere("c.scope", input.domain, 1);
         const { rows } = await exec.query(this.q(`SELECT c.token FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
-            `AND NOT ${SqlRetentionStore.PINNED_EXISTS} ORDER BY c.created_at_ms ASC LIMIT ?`, `SELECT c.token FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
-            `AND NOT ${SqlRetentionStore.PINNED_EXISTS} ORDER BY c.created_at_ms ASC LIMIT $4`), [...w.params, input.cutoffMs, input.cutoffMs, RETENTION_ROW_BATCH]);
+            `AND NOT ${SqlRetentionStore.pinnedExists("c")} ORDER BY c.created_at_ms ASC LIMIT ?`, `SELECT c.token FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
+            `AND NOT ${SqlRetentionStore.pinnedExists("c")} ORDER BY c.created_at_ms ASC LIMIT $4`), [...w.params, input.cutoffMs, input.cutoffMs, RETENTION_ROW_BATCH]);
         return rows.map((r) => String(r.token));
     }
     async countPinnedExpiryCandidates(exec, input) {
         const w = this.domainWhere("c.scope", input.domain, 1);
         const { rows } = await exec.query(this.q(`SELECT COUNT(*) AS n FROM (SELECT 1 AS one FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
-            `AND ${SqlRetentionStore.PINNED_EXISTS} LIMIT ?) x`, `SELECT COUNT(*) AS n FROM (SELECT 1 AS one FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
-            `AND ${SqlRetentionStore.PINNED_EXISTS} LIMIT $4) x`), [...w.params, input.cutoffMs, input.cutoffMs, RETENTION_ROW_BATCH]);
+            `AND ${SqlRetentionStore.pinnedExists("c")} LIMIT ?) x`, `SELECT COUNT(*) AS n FROM (SELECT 1 AS one FROM checkpoint c WHERE ${w.sql} AND c.status = 'pending' AND ${this.horizonArms(2)} ` +
+            `AND ${SqlRetentionStore.pinnedExists("c")} LIMIT $4) x`), [...w.params, input.cutoffMs, input.cutoffMs, RETENTION_ROW_BATCH]);
         return Number(rows[0]?.n ?? 0);
     }
     liveReferenceExists() {
@@ -248,6 +261,7 @@ export class SqlRetentionStore {
     async deleteExpiredSessions(input) {
         const call = { domain: input.domain, op: "deleteExpiredSessions" };
         let skippedOnAbort = 0;
+        const unattributable = await this.unattributableToolResults();
         try {
             return await this.tx(async (conn) => {
                 const face = this.statementFace(conn);
@@ -258,24 +272,17 @@ export class SqlRetentionStore {
                 const candidates = await this.sessionCandidates(conn, input, true);
                 const admitted = [];
                 for (const c of candidates)
-                    if (await this.admittedBy(face, c.id))
+                    if ((await this.refusalOf(face, { op: "retention-delete", rootSessionId: c.id })) === undefined)
                         admitted.push(c);
                 const referenced = await this.referencedBy(face, admitted.map((c) => c.id));
                 const doomed = admitted.filter((c) => !referenced.has(c.id));
                 const skipped = (await this.countProtectedSessions(conn, input)) + (candidates.length - doomed.length);
                 skippedOnAbort = doomed.length + skipped;
-                let deleted = 0;
-                let tombstones = 0;
-                const ids = doomed.map((d) => d.id);
-                if (ids.length > 0) {
-                    await this.opts.transactionHooks?.retention?.beforeDelete?.(face, doomed.map((d) => ({ sessionId: d.id, incarnation: d.incarnation })));
-                    deleted = await this.purgeSessionTrees(conn, input.domain, ids);
-                    tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
-                }
-                const receipt = { domain: input.domain, deleted, skipped, tombstones };
+                const erased = doomed.length > 0 ? await this.eraseTreesInTxn(conn, face, input.domain, doomed, "drop") : undefined;
+                const receipt = { domain: input.domain, deleted: erased?.deleted ?? 0, skipped, tombstones: erased?.tombstones ?? 0 };
                 await this.auditedBy(face, call, receipt);
-                return receipt;
-            });
+                return { receipt, erased: erased?.rows };
+            }).then(({ receipt, erased }) => (erased !== undefined ? { ...receipt, erasedRows: { ...erased, unattributableToolResults: unattributable } } : receipt));
         }
         catch (err) {
             if (err instanceof RetentionAborted)
@@ -283,7 +290,46 @@ export class SqlRetentionStore {
             throw err;
         }
     }
-    async purgeSessionTrees(conn, domain, ids) {
+    async eraseSession(input) {
+        if (this.opts.transactionHooks?.session?.beforeCommit === undefined) {
+            throw new Error(`retention: eraseSession(${JSON.stringify(input.sessionId)}) needs the session write hook (the erase token judge) — refusing to delete a session that no judge can confirm is in this deletion's deleting state`);
+        }
+        const unattributable = await this.unattributableToolResults();
+        const out = await this.tx(async (conn) => {
+            const face = this.statementFace(conn);
+            const { rows } = await conn.query(this.q("SELECT owner, incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", "SELECT owner, incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE"), [input.sessionId]);
+            const row = rows[0];
+            if (row === undefined)
+                return { outcome: "absent" };
+            const owner = row.owner === null || row.owner === undefined ? null : String(row.owner);
+            if (owner !== input.owner)
+                return { outcome: "absent" };
+            const incarnation = incarnationFromCell(input.sessionId, row.incarnation, "absent");
+            const refusal = await this.refusalOf(face, { op: "erase", rootSessionId: input.sessionId, token: input.token });
+            if (refusal !== undefined)
+                throw new EraseRefused(refusal);
+            const erased = await this.eraseTreesInTxn(conn, face, owner ?? "", [{ id: input.sessionId, incarnation }], "keep");
+            return { outcome: "erased", rows: erased.rows };
+        }).catch((err) => {
+            if (err instanceof EraseRefused)
+                return { outcome: "refused", refusal: err.refusal };
+            throw err;
+        });
+        return out.outcome === "erased" ? { outcome: "erased", rows: { ...out.rows, unattributableToolResults: unattributable } } : out;
+    }
+    async unattributableToolResults() {
+        const { rows: unowned } = await this.db.query("SELECT COUNT(*) AS n FROM tool_result WHERE owner_session_id IS NULL");
+        return Number(unowned[0]?.n ?? 0);
+    }
+    async eraseTreesInTxn(conn, face, domain, doomed, ruleMarks) {
+        const ids = doomed.map((d) => d.id);
+        await this.opts.transactionHooks?.retention?.beforeDelete?.(face, doomed.map((d) => ({ sessionId: d.id, incarnation: d.incarnation })));
+        const deleted = await this.purgeSessionTrees(conn, domain, ids, ruleMarks);
+        const tombstones = await this.writeTombstones(conn, domain, "session", ids);
+        const owner = domain === "" ? null : domain;
+        return { deleted, tombstones, rows: { sessions: doomed.map((d) => ({ sessionId: d.id, owner, incarnation: d.incarnation })) } };
+    }
+    async purgeSessionTrees(conn, domain, ids, ruleMarks) {
         const set = (col, pgIndex) => this.idSet(col, ids, pgIndex);
         {
             const s = set("checkpoint.session_id", 1);
@@ -298,9 +344,23 @@ export class SqlRetentionStore {
             const s = set("scope", 1);
             await conn.query(`SELECT scope FROM file_history_scope WHERE ${s.sql} ORDER BY scope FOR UPDATE`, s.params);
         }
+        if (ruleMarks === "drop") {
+            for (const table of ["session_policy", "session_policy_rev_mark"]) {
+                const s = set("session_id", 1);
+                await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
+            }
+        }
+        else {
+            const sealed = await eraseSessionPolicyRowsOn(conn, this.db.dialect, ids);
+            if (sealed.length > 0) {
+                this.opts.logger?.warn?.(SEALED_EVENT, {
+                    sessionIds: ids,
+                    keys: sealed,
+                    note: "these rows' counters were unreadable, so the erase could not end their lineage: each key now carries a sealed rev mark and answers every read and write with SessionPolicyError corrupt until an operator unseals its session_policy_rev_mark row in place (USAGE §9.11)",
+                });
+            }
+        }
         for (const [table, col] of [
-            ["session_policy", "session_id"],
-            ["session_policy_rev_mark", "session_id"],
             ["file_history_tracked", "scope"],
             ["file_history_version", "scope"],
             ["file_history_boundary", "scope"],
@@ -311,6 +371,11 @@ export class SqlRetentionStore {
             const s = set(col, 1);
             await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
         }
+        if (this.opts.sessionBoxScope !== undefined) {
+            const scope = this.opts.sessionBoxScope(domain === "" ? null : domain);
+            for (const id of ids)
+                await dropMailboxBoxOn(conn, this.db.dialect, scope, peerSessionBoxHandle(id));
+        }
         const s = set("session_id", 1);
         const w = this.domainWhere("owner", domain, 2);
         const metaRes = await conn.query(`DELETE FROM session_meta WHERE ${s.sql} AND ${w.sql}`, [...s.params, ...w.params]);