@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,72 +1,11 @@
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-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 { ensureIndexes } from "./ensure-index.js";
+import { peerSessionBoxHandle } from "@sema-agent/core";
 import { incarnationFromCell } from "../session-incarnation.js";
-import { lockRootAndReadClaim, rowsOnSqlExec } from "./execution-placement-sql.js";
-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;
-}
-export const RETENTION_AUDIT_TABLE = "retention_audit";
-export const RETENTION_HOLD_TABLE = "retention_hold";
-export const RETENTION_LEASE_TABLE = "retention_lease";
+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_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 TIDB_RETENTION_TOMBSTONE_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS ${RETENTION_TOMBSTONE_TABLE} (
      domain        VARCHAR(190) NOT NULL,
      -- kind:闭集(session | tool_result),见 RetentionTombstoneKind。
@@ -88,37 +27,7 @@ export const TIDB_RETENTION_STATEMENTS = [
      KEY idx_retention_tombstone_key (kind, row_key)
    ) COLLATE utf8mb4_bin`,
 ];
-export const PG_RETENTION_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 PG_RETENTION_TOMBSTONE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS ${RETENTION_TOMBSTONE_TABLE} (
      domain        VARCHAR(190) COLLATE "C" NOT NULL,
      kind          VARCHAR(32) COLLATE "C"  NOT NULL,
@@ -128,16 +37,9 @@ export const PG_RETENTION_SCHEMA = [
      PRIMARY KEY (domain, kind, row_key)
    )`,
 ];
-export const RETENTION_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 const RETENTION_TOMBSTONE_INDEXES = [
     { table: `${RETENTION_TOMBSTONE_TABLE}`, name: "idx_retention_tombstone_key", columns: ["kind", "row_key"] },
 ];
-export async function ensurePgRetentionSchema(query) {
-    for (const stmt of PG_RETENTION_SCHEMA)
-        await query(stmt);
-    await ensureIndexes(query, "pg", RETENTION_INDEXES);
-}
 class RetentionAborted extends Error {
     why;
     constructor(why) {
@@ -145,13 +47,20 @@ 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 {
     db;
     opts;
     retention = MANAGED_RETENTION;
-    constructor(db, opts) {
+    constructor(db, opts = {}) {
         this.db = db;
         this.opts = opts;
     }
@@ -159,14 +68,10 @@ export class SqlRetentionStore {
         return this.db.dialect === "mysql" ? mysql : pg;
     }
     domainWhere(col, domain, pgIndex) {
-        return domain === ""
-            ? { sql: this.q(`(${col} IS NULL OR ${col} = ?)`, `(${col} IS NULL OR ${col} = $${pgIndex})`), params: [""] }
-            : { sql: this.q(`${col} = ?`, `${col} = $${pgIndex}`), params: [domain] };
+        return retentionDomainWhere(this.db.dialect, col, domain, pgIndex);
     }
     idSet(col, ids, pgIndex) {
-        return this.db.dialect === "mysql"
-            ? { sql: `${col} IN (${ids.map(() => "?").join(",")})`, params: [...ids] }
-            : { sql: `${col} = ANY($${pgIndex}::text[])`, params: [ids] };
+        return retentionIdSet(this.db.dialect, col, ids, pgIndex);
     }
     async tx(fn) {
         const conn = await this.db.connect();
@@ -189,22 +94,43 @@ export class SqlRetentionStore {
             conn.release();
         }
     }
-    requireAudit(input, action) {
-        if (!input.audit) {
-            throw new Error(`retention: refusing a destructive call (${action}) with no audit context — every destructive retention ` +
-                `transaction must persist its {mode, policyDays, fencingToken} alongside the deletion (DESIGN-270 §6 F5). ` +
-                `Pass \`audit\` from the sweep lane's current round.`);
+    statementFace(conn) {
+        return { query: (sql, params) => conn.query(sql, params) };
+    }
+    async heldBy(face, call) {
+        const holdLock = this.opts.transactionHooks?.retention?.holdLock;
+        if (holdLock === undefined)
+            return false;
+        const answer = await holdLock(face, call);
+        switch (answer) {
+            case "proceed":
+                return false;
+            case "held":
+                return true;
+            default: {
+                const unknown = answer;
+                throw new Error(`retention: holdLock answered ${JSON.stringify(unknown)} for ${call.op} in domain ${JSON.stringify(call.domain)} — the closed answer set is "proceed" | "held"; rolling back.`);
+            }
         }
-        return input.audit;
     }
-    async holdInForce(conn, domain) {
-        const key = domain;
-        await conn.query(this.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 conn.query(this.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;
+    async refusalOf(face, write) {
+        const rootSessionId = write.rootSessionId;
+        const beforeCommit = this.opts.transactionHooks?.session?.beforeCommit;
+        if (beforeCommit === undefined)
+            return undefined;
+        const answer = await beforeCommit(face, write);
+        if (answer === "proceed")
+            return undefined;
+        if (typeof answer === "object" && answer !== null && answer.refuse instanceof Error)
+            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) {
+        const liveReferences = this.opts.transactionHooks?.retention?.liveReferences;
+        return liveReferences === undefined || candidates.length === 0 ? new Set() : liveReferences(face, candidates);
     }
-    async writeAuditRow(conn, row) {
-        await conn.query(this.q(`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()]);
+    async auditedBy(face, call, receipt) {
+        await this.opts.transactionHooks?.retention?.audit?.(face, call, receipt);
     }
     async writeTombstones(conn, domain, kind, keys) {
         if (keys.length === 0)
@@ -236,11 +162,12 @@ export class SqlRetentionStore {
         return { checkpoints, sessions, toolResults };
     }
     async expireCheckpoints(input) {
-        const audit = this.requireAudit(input, "expired_checkpoints");
+        const call = { domain: input.domain, op: "expireCheckpoints" };
         let skippedOnAbort = 0;
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.expiryCandidates(conn, input)).length + (await this.countPinnedExpiryCandidates(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
@@ -252,12 +179,13 @@ 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;
                 }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "expired_checkpoints", audit, deleted: expired, skipped: pinned, tombstones: 0 });
-                return { domain: input.domain, deleted: expired, skipped: pinned, tombstones: 0 };
+                const receipt = { domain: input.domain, deleted: expired, skipped: pinned, tombstones: 0 };
+                await this.auditedBy(face, call, receipt);
+                return receipt;
             });
         }
         catch (err) {
@@ -271,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() {
@@ -329,33 +259,30 @@ export class SqlRetentionStore {
         return rows.map((r) => String(r.ref));
     }
     async deleteExpiredSessions(input) {
-        const audit = this.requireAudit(input, "deleted_sessions");
+        const call = { domain: input.domain, op: "deleteExpiredSessions" };
         let skippedOnAbort = 0;
+        const unattributable = await this.unattributableToolResults();
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.sessionCandidates(conn, input)).length + (await this.countProtectedSessions(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
                 const candidates = await this.sessionCandidates(conn, input, true);
-                const rowsOn = rowsOnSqlExec(conn);
-                const doomed = [];
+                const admitted = [];
                 for (const c of candidates)
-                    if ((await lockRootAndReadClaim(rowsOn, this.db.dialect, c.id)).activeTaskId === null)
-                        doomed.push(c);
-                const skipped = await this.countProtectedSessions(conn, input);
+                    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) {
-                    deleted = await this.purgeSessionTrees(conn, input.domain, ids);
-                    tombstones = await this.writeTombstones(conn, input.domain, "session", ids);
-                }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_sessions", audit, deleted, skipped, tombstones });
-                const endedSpaces = doomed.flatMap((d) => (d.incarnation === undefined ? [] : [{ sessionId: d.id, spaceKey: d.incarnation }]));
-                return { domain: input.domain, deleted, skipped, tombstones, ...(endedSpaces.length > 0 ? { endedSpaces } : {}) };
-            });
+                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, erased: erased?.rows };
+            }).then(({ receipt, erased }) => (erased !== undefined ? { ...receipt, erasedRows: { ...erased, unattributableToolResults: unattributable } } : receipt));
         }
         catch (err) {
             if (err instanceof RetentionAborted)
@@ -363,30 +290,52 @@ export class SqlRetentionStore {
             throw err;
         }
     }
-    async purgeSessionTrees(conn, domain, ids) {
-        const set = (col, pgIndex) => this.idSet(col, ids, pgIndex);
-        {
-            const s = set("tr.session_id", 1);
-            await conn.query(this.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 conn.query(this.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 conn.query(`DELETE FROM task_run WHERE ${s.sql}`, [...s.params]);
+    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);
             const w = this.domainWhere("sm.owner", domain, 2);
             await conn.query(`DELETE FROM checkpoint WHERE ${s.sql} AND EXISTS (SELECT 1 FROM session_meta sm WHERE sm.session_id = checkpoint.session_id AND ${w.sql})`, [...s.params, ...w.params]);
         }
-        {
-            const s = set("checkpoint_ctx.session_id", 1);
-            const w = this.domainWhere("sm.owner", domain, 2);
-            await conn.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]);
-        }
         {
             const s = set("owner_session_id", 1);
             await conn.query(`DELETE FROM tool_result WHERE ${s.sql}`, s.params);
@@ -395,13 +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 [
-            ["resume_anchor", "session_id"],
-            ["approval_exemption", "session_id"],
-            ["session_policy", "session_id"],
-            ["session_policy_rev_mark", "session_id"],
-            ...(this.opts.taskAttachmentTable ? [["task_attachment", "session_id"]] : []),
-            [USER_INPUT_ACCEPTANCE_TABLE, "session_id"],
             ["file_history_tracked", "scope"],
             ["file_history_version", "scope"],
             ["file_history_boundary", "scope"],
@@ -412,20 +371,10 @@ export class SqlRetentionStore {
             const s = set(col, 1);
             await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
         }
-        if (this.opts.taskListTables) {
-            const listKeys = ids.map((id) => taskListKeyFor(id)).sort();
-            {
-                const s = this.idSet("list_key", listKeys, 1);
-                await conn.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 = this.idSet("list_key", listKeys, 1);
-                await conn.query(`DELETE FROM ${table} WHERE ${s.sql}`, s.params);
-            }
-        }
-        {
-            const s = set("session_id", 1);
-            await conn.query(`DELETE FROM workflow_completion_inbox 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);
@@ -440,11 +389,12 @@ export class SqlRetentionStore {
         return metaRes.affected;
     }
     async deleteOrphanToolResults(input) {
-        const audit = this.requireAudit(input, "deleted_tool_results");
+        const call = { domain: input.domain, op: "deleteOrphanToolResults" };
         let skippedOnAbort = 0;
         try {
             return await this.tx(async (conn) => {
-                if (await this.holdInForce(conn, input.domain)) {
+                const face = this.statementFace(conn);
+                if (await this.heldBy(face, call)) {
                     skippedOnAbort = (await this.orphanToolResultCandidates(conn, input)).length + (await this.countLiveReachableToolResults(conn, input));
                     throw new RetentionAborted("hold_in_force");
                 }
@@ -458,8 +408,9 @@ export class SqlRetentionStore {
                     deleted = res.affected;
                     tombstones = await this.writeTombstones(conn, input.domain, "tool_result", refs);
                 }
-                await this.writeAuditRow(conn, { domain: input.domain, action: "deleted_tool_results", audit, deleted, skipped: reachable, tombstones });
-                return { domain: input.domain, deleted, skipped: reachable, tombstones };
+                const receipt = { domain: input.domain, deleted, skipped: reachable, tombstones };
+                await this.auditedBy(face, call, receipt);
+                return receipt;
             });
         }
         catch (err) {
@@ -474,14 +425,4 @@ export class SqlRetentionStore {
         return Number(rows[0]?.n ?? 0);
     }
 }
-export class TiDBRetentionStore extends SqlRetentionStore {
-    constructor(pool, opts) {
-        super(mysqlDriver(pool), opts);
-    }
-}
-export class PgRetentionStore extends SqlRetentionStore {
-    constructor(pool, opts) {
-        super(pgDriver(pool), opts);
-    }
-}
 //# sourceMappingURL=retention-store-sql.js.map

package/dist/{plugins → stores-sql}/session-event-payload.d.ts

@@ -28,7 +28,7 @@
  * `isJsonColumnBodyProblem`,不另写一份。
  */
 import { type SessionTreeEntry } from "@sema-agent/core";
-import { type JsonColumnReader } from "./sql-json-column.js";
+import { type JsonColumnReader } from "../plugins/sql-json-column.js";
 /**
  * 形读者:core 自己声明的 `SessionTreeEntryBase` 里那两把**不可省**的串键。
  *

package/dist/{plugins → stores-sql}/session-event-payload.js

@@ -1,5 +1,5 @@
 import { SessionError } from "@sema-agent/core";
-import { decodeJsonColumn, isJsonColumnBodyProblem } from "./sql-json-column.js";
+import { decodeJsonColumn, isJsonColumnBodyProblem } from "../plugins/sql-json-column.js";
 export const readSessionEventPayload = (body) => {
     if (typeof body !== "object" || body === null || Array.isArray(body))
         return { problem: "expected a JSON object (a SessionTreeEntry)" };

package/dist/stores-sql/session-policy-store-sql.d.ts

@@ -2,7 +2,7 @@ import { type SessionPolicyStore, type SessionPermissionRules, type StoredSessio
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type JsonColumnShape } from "../plugins/sql-json-column.js";
-import { type SqlDriver } from "../plugins/sql-driver.js";
+import { type SqlDialect, type SqlDriver, type SqlTxConn } from "../plugins/sql-driver.js";
 /** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
  *
  *  🔴 导出而不是让收编腿再抄一份(clay 宪法「schema 单一属主禁复制」):[ref] form b 的身份重绑要
@@ -44,16 +44,38 @@ export type StoredSessionRulesBody = SessionPermissionRules & Pick<StoredSession
  * + 恰好解一次 `decodeJsonColumn` + 折码 `foldJsonColumn`);本店只留「形判据是哪一只」与「坏体折成哪个码」。
  */
 export declare function readSessionRulesBody(body: unknown): JsonColumnShape<StoredSessionRulesBody>;
-/** 本店唯一的日志口:抹除封键那一臂([ref])的点名。缺席 ⇒ 退回 `console.warn`(不静默)。
- *  结构型,与服务日志口的 `warn` 逐位同形:本目录对服务的观测模块零依赖(目录的可搬性),服务的日志口照样直接交进来。 */
+/** 封键的 warn 事件名(提交后每次抹除至多一条,点名会话与被封的键)。 */
+export declare const SEALED_EVENT = "session_policy_erase_sealed_keys";
+/** 一把被封的键:单向哈希的键 + 那一行读不出的两个计数的原文(取证用;不带 principal 明文、不带规则体)。 */
+export type SealedEraseKey = {
+    readonly policyKey: string;
+    readonly rev: string;
+    readonly gen: string;
+};
+/** 本店的日志口:抹除封键那一臂([ref])的点名。**必填**:组合座(`store-backend.ts`)交服务的日志口,没有自己的就交日志出口接缝的
+ *  缺省 logger —— 本目录不碰 stdio(目录的可搬性;进程 stdout / stderr 只有接缝一个出口,`test/log-exit-single-source-gate.test.ts`)。
+ *  结构型,与服务日志口的 `warn` 逐位同形,服务的日志口照样直接交进来。注入的这只抛 ⇒ 同一行落接缝的缺省 logger(见 `discloseSealed`)。 */
 export type SessionPolicyStoreLogger = {
     warn(msg: string, fields?: Record<string, unknown>): void;
 };
+/**
+ * 一次客户端写的计数(部署的格:会话规则是客户端可见的会话态,提交出口撤回一只刚铸的会话之前读这只计数)。组合座交入;店只在锁住根行、根行在、
+ * 所有拒判之后、规则落行之前,同一事务、同一连接调它一次 —— 计数住部署的旁表,店目录不认识那张表。
+ */
+export type SessionClientWriteCounter = (conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string) => Promise<void>;
+/**
+ * 按会话抹除规则行的**唯一语句源**(店的 `deleteBySession` 在自己的事务里调;会话删除执行体 `retention-store-sql.ts` 在会话树事务里对一批会话调 ——
+ * 同一组语句,`session_policy_rev_mark` 的高水位律只写这一处,core 契约 `session_policy.rev_survives_delete`)。调用方持事务。
+ * 步序:锁这批会话的规则行(`policy_key` 升序,与 `putRules` 同向)→ 每把键写记号(rev 高水位 + 下一代 `gen`;读不出计数的行写封键)→ 删规则行。
+ * 返回封键(调用方负责响亮披露)。没有规则行 ⇒ 零写。
+ */
+export declare function eraseSessionPolicyRowsOn(conn: Pick<SqlTxConn, "query">, dialect: SqlDialect, sessionIds: readonly string[]): Promise<readonly SealedEraseKey[]>;
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;
-    private readonly logger?;
-    constructor(db: SqlDriver, logger?: SessionPolicyStoreLogger | undefined);
+    private readonly countClientWrite;
+    private readonly logger;
+    constructor(db: SqlDriver, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** 判据属主 = `sql-errors.ts`([ref] P1-①;本站点旧形已是并集形,收编后语义不变)。 */
@@ -106,7 +128,7 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *      order. This is the SAME lock order putRules uses (policy row → mark row), which is the whole point: the
      *      obvious shape (`INSERT … SELECT` the marks, then DELETE) locks the MARK first and takes only a SHARED lock
      *      on the policy rows it reads, i.e. a reversed order PLUS an S→X upgrade — the textbook deadlock this repo
-     *      已经吃过两次(retention-store-sql.ts ④a/④b 的 [ref] 案:一边持 boundary 等哨兵,一边持哨兵等 boundary)。
+     *      已经吃过两次(留存会话树删除的 file-history 哨兵腿与任务清单腿的 [ref] 案:一边持 boundary 等哨兵,一边持哨兵等 boundary)。
      *   ② the marks (their revs come from ①'s already-locked rows) — `GREATEST` merge, so a mark only ever RISES and
      *      repeated erases never walk the line back.
      *   ③ the DELETE — scoped to ①'s POLICY_KEY SET, never re-scanned by `session_id`. 🔴 This is the whole of
@@ -143,9 +165,9 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *  (驱动错误;那只记号本来就读不回,`putRules` 同样拒)—— 抹除不读记号,这一形不在本判词射程内。 */
     deleteBySession(sessionId: string): Promise<void>;
     /**
-     * [ref] 封键的响亮面:一次抹除至多一条 warn。日志座**抛** ⇒ 退回 `console.warn` 带原句 —— 走到这里删除已经提交,
-     * 一次日志故障不许把它报成失败(E21 会因此 500、overwrite-dst 会因此中止;codex 7.105.0 修复验证轮 [medium] 同形)。
-     * 缺日志座(直接 `new` 本店的工具 / 测试)⇒ `console.warn`,不静默。
+     * [ref] 封键的响亮面:一次抹除至多一条 warn。走到这里删除已经提交,一次日志故障不许把它报成失败(E21 会因此 500、
+     * overwrite-dst 会因此中止;codex 7.105.0 修复验证轮 [medium] 同形)⇒ 日志座抛不往外抛;**也不吞披露**:同一行落日志出口接缝的
+     * 缺省 logger(与数据根权限收紧的披露座同一条律:披露不许因日志座坏而消失)—— 运维面对一把读写都拒的封键,要靠这一行知道为什么。
      */
     private discloseSealed;
     /**
@@ -161,10 +183,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: MySqlPool, logger?: SessionPolicyStoreLogger);
+    constructor(pool: MySqlPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: PgPool, logger?: SessionPolicyStoreLogger);
+    constructor(pool: PgPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
 }
 //# sourceMappingURL=session-policy-store-sql.d.ts.map