@sema-agent/server 7.147.0 → 7.148.0

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

@@ -1,6 +1,6 @@
 import { parkedApprovalCard } from "../approval-content-kind.js";
 import { createHash } from "node:crypto";
-import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
+import { CHECKPOINT_FACET_SQL, CHECKPOINT_SWEEP_ORDER_SQL, CheckpointIndexRefusedError, checkpointSweepAfterSql, hostSessionOf, judgeCheckpointIndexCells } from "../plugins/checkpoint-index-columns.js";
 import { CheckpointError, validatePendingSteer, appendPendingSteer, winnerFromOutcome, summarizeCheckpoint, checkpointRevOf, judgeCheckpointRow, CONTRACT_KIT_ENGINE_VERSION, ExecutionOutcomeConflictError, executionRecordDisposition, executionVerdict, } from "@sema-agent/core";
 import { parkRowFacts, skillCardFacts } from "../approval-card.js";
 import { assertJsonColumnWritable, createObjectColumnReader, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextSha256, readJsonArrayColumn, readJsonColumnTextSha256, readNonNullJsonValueColumn, StoreCorruptError, } from "../plugins/sql-json-column.js";
@@ -11,7 +11,7 @@ import { isDupKeyError, isMissingColumnError, rowTooLargeOrSelf, StoreRowTooLarg
 import { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
-import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, queueRowGateKind, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
+import { approvalDecisionOfWinner, boundedRuleOffers, boundedToolInput, candidateIdentityOf, DECIDED_REPLAY_SCAN_CAP, DENY_SWEEP_PAGE_ROWS, isUnreadableSummaryForm, parkedLegTaskId, queueRowGateKind, queueTriageOrder, readRiskDescriptorBody, TERMINAL_BACKSTOP_MS, TERMINAL_GRACE_MS, UnreadableCheckpointRowError, } from "../plugins/checkpoint-store-face.js";
 const CTX_REWRITE_PAGE = 500;
 export function tokenFingerprint(token) {
     return "sha256:" + createHash("sha256").update(token).digest("hex").slice(0, 12);
@@ -61,7 +61,14 @@ export const CHECKPOINT_ADDED_COLUMNS = [
         column: "execution_at_ms",
         breaksAt: "it is written in the same CAS as `execution_outcome` (the record and its stamp are one write group)",
     },
+    {
+        column: "host_session_id",
+        breaksAt: "the park-mint write (put) stamps it, the one-time backfill M49 (which runs right after this check) fills it on the rows already parked, " +
+            "and every read that finds a run's card — cancel, steer, both park reapers, resume-context retention, the queue row's run — names it, " +
+            "so every durable suspend fails at first park and every cancel of a parked run errors",
+    },
 ];
+const PENDING_ROW_AXIS_COLUMN = { card: "session_id", run: "host_session_id" };
 export async function assertCheckpointColumnSchema(query, dialect) {
     for (const { column, breaksAt } of CHECKPOINT_ADDED_COLUMNS) {
         try {
@@ -82,18 +89,12 @@ export async function assertCheckpointColumnSchema(query, dialect) {
 const readCheckpointBlobBody = createObjectColumnReader();
 const readResumeOutcomeBody = createObjectColumnReader();
 const readGateOutcomeBody = createObjectColumnReader();
-const readRiskDescriptorBody = createObjectColumnReader();
 function decodeCheckpointColumn(cell, where) {
     return decodeJsonColumn(cell, readCheckpointBlobBody, `checkpoint.checkpoint ${where}`);
 }
 function verdictOfUnreadableBody(cell) {
     return judgeCheckpointRow(cell);
 }
-const UNREADABLE_SUMMARY_MEMBERS = new Set(["token", "rowVerdict", "sessionId", "scope", "gateKind", "createdAt", "deadline"]);
-function isUnreadableSummaryForm(summary) {
-    const names = UNREADABLE_SUMMARY_MEMBERS;
-    return summary.rowVerdict.kind !== "ok" && Object.keys(summary).every((member) => names.has(member));
-}
 function readCheckpointBodyOrRefuse(cell, where) {
     try {
         return refusing("a checkpoint nobody can resume", () => decodeCheckpointColumn(cell, where));
@@ -161,8 +162,8 @@ function readParkRowActionCell(cell) {
         return undefined;
     }
 }
-const PARK_ROW_PENDING_ACTION = { key: "pendingAction", as: "pending_action" };
-const PARK_ROW_CHECKPOINT_ID = { key: "checkpointId", as: "checkpoint_id" };
+const PARK_ROW_PENDING_ACTION = { path: ["pendingAction"], as: "pending_action" };
+const PARK_ROW_CHECKPOINT_ID = { path: ["checkpointId"], as: "checkpoint_id" };
 const readCheckpointIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "checkpointId is not a JSON string" });
 function readCheckpointIdCell(cell) {
     try {
@@ -174,6 +175,18 @@ function readCheckpointIdCell(cell) {
         return null;
     }
 }
+const PARK_ROW_RECORDED_TASK_ID = { path: ["state", "rowTaskId"], as: "row_task_id" };
+const readRecordedTaskIdMemberBody = (body) => (typeof body === "string" ? { value: body } : { problem: "state.rowTaskId is not a JSON string" });
+function readRecordedTaskIdCell(cell) {
+    try {
+        return decodeNullableJsonColumn(cell, readRecordedTaskIdMemberBody, "checkpoint.checkpoint $.state.rowTaskId (operator queue row)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return undefined;
+    }
+}
 const readPendingActionMemberBody = createObjectColumnReader();
 function candidateIdentityOfColumn(cell, where) {
     let cp;
@@ -238,13 +251,11 @@ export class SqlCheckpointStore {
     durability = "durable";
     fidelity = "json";
     execution = { outcome: true };
-    claims;
     storedRowMemo = new StoredRowProjectionMemo();
     constructor(db, logger, opts = {}) {
         this.db = db;
         this.logger = logger;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
-        this.claims = opts.claims;
     }
     q(mysql, pg) {
         return this.db.dialect === "mysql" ? mysql : pg;
@@ -260,7 +271,7 @@ export class SqlCheckpointStore {
     }
     pendingRowQuery(select, sessionId, scope, binding) {
         const params = [sessionId];
-        const where = [`session_id=${this.ph(1)}`, "status='pending'"];
+        const where = [`${PENDING_ROW_AXIS_COLUMN[binding?.axis ?? "card"]}=${this.ph(1)}`, "status='pending'"];
         if (scope !== undefined) {
             params.push(scope);
             where.push(`scope=${this.ph(params.length)}`);
@@ -286,15 +297,16 @@ export class SqlCheckpointStore {
         if (judged.kind !== "cells")
             throw new CheckpointIndexRefusedError(cp.sessionId, judged);
         const cells = judged.cells;
+        const hostSessionId = hostSessionOf(cp);
         const pa = cp.pendingAction;
         const toolInput = boundedToolInput(pa?.args);
         const ruleOffers = boundedRuleOffers(pa?.ruleOffers);
         const executionOutcome = cp.executionOutcome === undefined ? null : this.json(cp.executionOutcome, "execution outcome");
         const executionAtMs = cp.executionOutcome === undefined ? null : (cp.executionAtMs ?? null);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms) " +
-                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22)"), [
+            await this.db.query(this.q("INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
+                "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", "INSERT INTO checkpoint (token, scope, session_id, version, status, tool_name, tool_call_id, tool_input, checkpoint, deadline, created_at_ms, terminal_at_ms, gate_kind, approval_card, bound_input_hash, risk_descriptor, rule_suggestions, has_bidi_controls, rev, reopen_reason, execution_outcome, execution_at_ms, host_session_id) " +
+                "VALUES ($1,$2,$3,$4,$5,$6,$7,$8::jsonb,$9::jsonb,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb,$22,$23)"), [
                 token,
                 cells.scope,
                 cells.session_id,
@@ -317,6 +329,7 @@ export class SqlCheckpointStore {
                 cp.reopenReason ?? null,
                 executionOutcome,
                 executionAtMs,
+                hostSessionId,
             ]);
         }
         catch (e) {
@@ -439,17 +452,20 @@ export class SqlCheckpointStore {
             `WHERE status = 'pending' AND ((deadline IS NOT NULL AND deadline <= $2 AND COALESCE(${CHECKPOINT_FACET_SQL.pg}, '') <> 'A') OR (terminal_at_ms IS NOT NULL AND terminal_at_ms <= $3))`), [Date.now(), cutoff, cutoff]);
         return res.affected;
     }
-    async listExpiredApprovalGates(cutoff, limit = 100) {
-        const { rows } = await this.db.query(this.q(`SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `SELECT session_id, scope FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= $1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit]);
-        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope) }));
+    async listExpiredApprovalGates(cutoff, limit = DENY_SWEEP_PAGE_ROWS, after) {
+        const head = "SELECT session_id, scope, deadline, token FROM checkpoint WHERE status = 'pending' AND deadline IS NOT NULL AND deadline <= ";
+        const { rows } = after === undefined
+            ? await this.db.query(this.q(`${head}? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `${head}$1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $2`), [cutoff, limit])
+            : await this.db.query(this.q(`${head}? AND ${CHECKPOINT_FACET_SQL.mysql} = 'A' AND ${checkpointSweepAfterSql(() => "?")} ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT ?`, `${head}$1 AND ${CHECKPOINT_FACET_SQL.pg} = 'A' AND ${checkpointSweepAfterSql((i) => `$${i + 2}`)} ORDER BY ${CHECKPOINT_SWEEP_ORDER_SQL} LIMIT $5`), [cutoff, after.deadline, after.deadline, after.token, limit]);
+        return rows.map((r) => ({ sessionId: String(r.session_id), scope: String(r.scope), position: { deadline: Number(r.deadline), token: String(r.token) } }));
     }
     async listPending(scope) {
         const d = this.db.dialect;
         const base = `SELECT c.session_id, c.token, c.scope, c.tool_name, c.tool_call_id, ${jsonColumnText(d, "tool_input")}, c.bound_input_hash, ` +
             `${jsonColumnText(d, "risk_descriptor")}, ${jsonColumnText(d, "rule_suggestions")}, c.has_bidi_controls, c.created_at_ms, c.deadline, c.gate_kind, c.approval_card, ta.task_id, ` +
-            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ` +
+            `${jsonColumnText(d, "checkpoint", PARK_ROW_PENDING_ACTION)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_CHECKPOINT_ID)}, ${jsonColumnText(d, "checkpoint", PARK_ROW_RECORDED_TASK_ID)}, ` +
             `${jsonColumnTextSha256(d, "checkpoint", CHECKPOINT_SHA256_AS)} ` +
-            "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.session_id WHERE c.status='pending'";
+            "FROM checkpoint c LEFT JOIN task_active ta ON ta.session_id = c.host_session_id WHERE c.status='pending'";
         const { rows } = scope
             ? await this.db.query(`${base}${this.q(" AND c.scope=?", " AND c.scope=$1")} ORDER BY c.created_at_ms ASC`, [scope])
             : await this.db.query(`${base} ORDER BY c.created_at_ms ASC`);
@@ -472,7 +488,7 @@ export class SqlCheckpointStore {
                 ...(toolCallId !== null ? { boundCallId: toolCallId } : {}),
                 ...(boundInputHash !== null ? { boundInputHash } : {}),
                 gateKind,
-                taskId: r.task_id ?? null,
+                taskId: parkedLegTaskId(readRecordedTaskIdCell(r[PARK_ROW_RECORDED_TASK_ID.as]), r.task_id ?? null),
                 input: refusing("a tool input the operator would be approving unseen", () => decodeToolInputColumn(r.tool_input)) ?? null,
                 createdAt: Number(r.created_at_ms),
                 deadline: r.deadline == null ? null : Number(r.deadline),
@@ -489,7 +505,7 @@ export class SqlCheckpointStore {
             const p = projections.get(e.token);
             return p === undefined ? e.row : { ...e.row, ...p.skillCardFacts, rowVerdict: p.rowVerdict };
         });
-        return out.sort((a, b) => (b.riskDescriptor?.severity ?? 0) - (a.riskDescriptor?.severity ?? 0) || a.createdAt - b.createdAt);
+        return out.sort(queueTriageOrder);
     }
     async storedRowProjections(rows) {
         const out = new Map();
@@ -676,42 +692,57 @@ export class SqlCheckpointStore {
             return undefined;
         return rows[0].scope ?? null;
     }
-    async putCtx(sessionId, ctx) {
+    async hostSessionOfCard(token) {
+        const { rows } = await this.db.query(this.q("SELECT host_session_id FROM checkpoint WHERE token = ?", "SELECT host_session_id FROM checkpoint WHERE token = $1"), [token]);
+        if (!rows[0])
+            return undefined;
+        const host = rows[0].host_session_id;
+        return typeof host === "string" && host !== "" ? host : null;
+    }
+    async putCtx(sessionId, ctx, claim) {
+        if (claim !== undefined)
+            return this.writeCtxWhileClaimed(sessionId, ctx, claim, "claim-fenced write", async (tx, text) => (await this.upsertCtx(tx, sessionId, text), "written"));
         const text = this.json(ctx, "checkpoint ctx");
         assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (write leg)`);
         try {
-            await this.db.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
-                "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
-                "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
+            await this.upsertCtx(this.db, sessionId, text);
         }
         catch (e) {
             throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)}`);
         }
+        return "written";
+    }
+    async upsertCtx(exec, sessionId, text) {
+        await exec.query(this.q("INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES (?,?,?) " +
+            "ON DUPLICATE KEY UPDATE ctx = VALUES(ctx), updated_at_ms = VALUES(updated_at_ms)", "INSERT INTO checkpoint_ctx (session_id, ctx, updated_at_ms) VALUES ($1,$2::jsonb,$3) " +
+            "ON CONFLICT (session_id) DO UPDATE SET ctx = EXCLUDED.ctx, updated_at_ms = EXCLUDED.updated_at_ms"), [sessionId, text, Date.now()]);
     }
     async getCtx(sessionId) {
         const { rows } = await this.db.query(this.q(`SELECT ${jsonColumnText("mysql", "ctx")} FROM checkpoint_ctx WHERE session_id=?`, `SELECT ${jsonColumnText("pg", "ctx")} FROM checkpoint_ctx WHERE session_id=$1`), [sessionId]);
         return rows[0] ? refusing("a resume context nobody can read", () => decodeCtxColumn(rows[0].ctx, `for session ${JSON.stringify(sessionId)}`)) : null;
     }
-    async rewriteCtxWhileClaimed(sessionId, taskId, ctx, legHolds) {
-        const claims = this.claims;
-        if (claims === undefined)
-            throw new Error("SqlCheckpointStore.rewriteCtxWhileClaimed: no claim fence is bound to this store (wiring defect: the backend binds its own run store)");
+    async rewriteCtxWhileClaimed(sessionId, ctx, claim) {
+        return this.writeCtxWhileClaimed(sessionId, ctx, claim, "claim-fenced rewrite", async (tx, text) => {
+            const row = await tx.query(this.q("SELECT session_id FROM checkpoint_ctx WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM checkpoint_ctx WHERE session_id = $1 FOR UPDATE"), [sessionId]);
+            if (row.rows.length === 0)
+                return "context_absent";
+            await tx.query(this.q("UPDATE checkpoint_ctx SET ctx = ?, updated_at_ms = ? WHERE session_id = ?", "UPDATE checkpoint_ctx SET ctx = $1::jsonb, updated_at_ms = $2 WHERE session_id = $3"), [text, Date.now(), sessionId]);
+            return "written";
+        });
+    }
+    async writeCtxWhileClaimed(sessionId, ctx, claim, leg, write) {
+        const fence = claim.fence;
+        if (!("db" in fence) || fence.db.dialect !== this.db.dialect) {
+            throw new Error(`SqlCheckpointStore ${leg}: the claim fence must be the ${this.db.dialect} run store on this store's database (wiring defect: the run store and the checkpoint store come from one backend)`);
+        }
         const text = this.json(ctx, "checkpoint ctx");
-        assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (claim-fenced rewrite)`);
+        assertJsonColumnWritable(text, createObjectColumnReader(), `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         let fenced;
         try {
-            fenced = await claims.whileHoldingClaim(sessionId, taskId, async (tx, run) => {
-                if (!legHolds(run))
-                    return "claim_released";
-                const row = await tx.query(this.q("SELECT session_id FROM checkpoint_ctx WHERE session_id = ? FOR UPDATE", "SELECT session_id FROM checkpoint_ctx WHERE session_id = $1 FOR UPDATE"), [sessionId]);
-                if (row.rows.length === 0)
-                    return "context_absent";
-                await tx.query(this.q("UPDATE checkpoint_ctx SET ctx = ?, updated_at_ms = ? WHERE session_id = ?", "UPDATE checkpoint_ctx SET ctx = $1::jsonb, updated_at_ms = $2 WHERE session_id = $3"), [text, Date.now(), sessionId]);
-                return "written";
-            });
+            fenced = await fence.whileHoldingClaim(sessionId, claim.taskId, async (tx, run) => (claim.legHolds(run) ? write(tx, text) : "claim_released"));
         }
         catch (e) {
-            throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (claim-fenced rewrite)`);
+            throw rowTooLargeOrSelf(this.db.dialect, e, `checkpoint_ctx.ctx for session ${JSON.stringify(sessionId)} (${leg})`);
         }
         return fenced.held ? fenced.value : "claim_released";
     }
@@ -760,9 +791,9 @@ export class SqlCheckpointStore {
     }
     async reapCtx(cutoff) {
         const res = await this.db.query(this.q("DELETE FROM checkpoint_ctx WHERE updated_at_ms < ? " +
-            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT host_session_id FROM checkpoint WHERE status='pending' AND host_session_id IS NOT NULL) " +
             "AND session_id NOT IN (SELECT session_id FROM task_active)", "DELETE FROM checkpoint_ctx WHERE updated_at_ms < $1 " +
-            "AND session_id NOT IN (SELECT session_id FROM checkpoint WHERE status='pending') " +
+            "AND session_id NOT IN (SELECT host_session_id FROM checkpoint WHERE status='pending' AND host_session_id IS NOT NULL) " +
             "AND session_id NOT IN (SELECT session_id FROM task_active)"), [cutoff]);
         return res.affected;
     }

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

@@ -16,10 +16,6 @@ export declare const MAILBOX_TOMBSTONE_TABLE = "mailbox_tombstone";
  *  是**盒**事实(与 `next_seq` 同生命周期):`drop` 随盒删、`reap` 留着(它清掉的东西从没被收过)。新表而不是 `mailbox` 加列,理由同墓碑表(存量库零运维动作)。
  *  `digests` = 引擎 `mailboxReplayDigests` 的四面摘要 JSON(只读那一只函数,不另算)。 */
 export declare const MAILBOX_CONSUMED_TABLE = "mailbox_consumed";
-/**
- * 身份键(`scope` / `handle` / lease `owner`)的 UTF-8 字节上界 = 键列宽(TiDB `VARBINARY(190)`;PG 列按字符,本判官在两方言上都按字节拒)。
- */
-export declare const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
 /**
  * 🔴 **「这只串能当收件箱的身份键吗」的唯一判官**(三只键列:`scope` / `handle` / lease `owner`;两方言同一只、同一句拒因)。一只串当得了键 ⇔
  *  ⓪ `scope` 非空(引擎 InMemory 同一句「without a scope」:没有箱址;handle / owner 空照引擎参照形放行);
@@ -46,6 +42,13 @@ export declare const MAILBOX_KEYED_TABLES: readonly ["mailbox", "mailbox_message
 export type MailboxKeyedTable = (typeof MAILBOX_KEYED_TABLES)[number];
 /** 按键删收件箱表族的一张表(两方言;参数 = [scope_key, handle])。 */
 export declare function mailboxKeyDeleteSql(dialect: SqlDialect, table: MailboxKeyedTable): string;
+/**
+ * **整盒删**(盒行先删 → 消息 → 消费记录 → 墓碑,{@link MAILBOX_KEYED_TABLES} 序;锁序与理由见店的 `drop`)发在调用方事务的连接上。
+ * 语句源唯一:店的 `drop` 与删净会话的执行体(`plugins/retention-deployment.ts` 的部署行,在执行体那一个事务里)同调。判官拒的键没有箱 ⇒ 零语句。
+ */
+export declare function dropMailboxBoxOn(exec: {
+    query(sql: string, params: unknown[]): Promise<unknown>;
+}, dialect: SqlDialect, scope: string, handle: string): Promise<void>;
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记
  *  `mailbox_message_column_corrupt`(scope/handle/seq/column/code),运维按 seq 修行。

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

@@ -1,7 +1,7 @@
 import { isUtf8 } from "node:buffer";
 import { MAILBOX_CONSUMED_ID_WINDOW, MAILBOX_INVALID_PEER_META_CODE, MAILBOX_RECORD_ID_MAX_CHARS, MAILBOX_REPLAY_FACETS, MAILBOX_TOMBSTONED_RECIPIENT_CODE, MailboxStoreError, assertMailboxDecisionMove, judgeMailboxAppendById, mailboxReplayDigests, readMailboxAppend, readMailboxPeerMeta, readStoredMailboxDecision } from "@sema-agent/core";
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "../plugins/pg-safe-json.js";
-import { isWellFormedUnicode } from "../principal-jwt.js";
+import { PRINCIPAL_MAX_BYTES, isWellFormedUnicode } from "../principal-shape.js";
 import { ensureIndexes } from "../plugins/ensure-index.js";
 import { escapeLike } from "../plugins/sql-escape.js";
 import { SqlJsonColumnError, decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText, readStringArrayColumn } from "../plugins/sql-json-column.js";
@@ -22,15 +22,14 @@ function rowToTombstone(r) {
     const label = r.label === null || r.label === undefined ? undefined : bufToStr(r.label);
     return { handle: bufToStr(r.handle), retiredAt: Number(r.retired_at_ms), ...(label !== undefined ? { label } : {}) };
 }
-export const MAILBOX_KEY_MAX_UTF8_BYTES = 190;
 export function mailboxKeyProblem(what, v) {
     if (what === "scope" && (v === undefined || v === ""))
         return "MailboxStore: refusing a message without a scope (an empty scope addresses no box)";
     const unaddressable = byteExactIdentityProblem(what, v);
     if (unaddressable !== undefined)
         return unaddressable;
-    if (Buffer.byteLength(v, "utf8") > MAILBOX_KEY_MAX_UTF8_BYTES) {
-        return `MailboxStore: ${what} exceeds the ${MAILBOX_KEY_MAX_UTF8_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
+    if (Buffer.byteLength(v, "utf8") > PRINCIPAL_MAX_BYTES) {
+        return `MailboxStore: ${what} exceeds the ${PRINCIPAL_MAX_BYTES}-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`;
     }
     return undefined;
 }
@@ -122,6 +121,12 @@ export const MAILBOX_KEYED_TABLES = [MAILBOX_TABLE, MAILBOX_MSG_TABLE, MAILBOX_C
 export function mailboxKeyDeleteSql(dialect, table) {
     return dialect === "mysql" ? `DELETE FROM ${table} WHERE scope_key = ? AND handle = ?` : `DELETE FROM ${table} WHERE scope_key = $1 AND handle = $2`;
 }
+export async function dropMailboxBoxOn(exec, dialect, scope, handle) {
+    if (keyless(scope, handle))
+        return;
+    for (const table of MAILBOX_KEYED_TABLES)
+        await exec.query(mailboxKeyDeleteSql(dialect, table), [scope, handle]);
+}
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
 }
@@ -223,18 +228,18 @@ function decisionMoveVerdict(rows, expect) {
 }
 export async function ensureTiDBMailboxSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
-    scope VARCHAR(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    scope VARCHAR(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     next_seq BIGINT NOT NULL,
-    lease_owner VARBINARY(190) NULL,
+    lease_owner VARBINARY(${PRINCIPAL_MAX_BYTES}) NULL,
     lease_expires_at_ms BIGINT NULL,
     lease_max_seq BIGINT NULL,
     PRIMARY KEY (scope_key, handle)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_MSG_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     seq BIGINT NOT NULL,
     from_id VARBINARY(255) NULL,
     content LONGTEXT NOT NULL,
@@ -259,16 +264,16 @@ export async function ensureTiDBMailboxSchema(pool) {
     KEY idx_mbm_sent (scope_key, handle, sent_at_ms)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_CONSUMED_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     seq BIGINT NOT NULL,
     record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) NOT NULL,
     digests TEXT NOT NULL,
     PRIMARY KEY (scope_key, handle, seq)
   ) COLLATE utf8mb4_bin`);
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
-    scope_key VARBINARY(190) NOT NULL,
-    handle VARBINARY(190) NOT NULL,
+    scope_key VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
+    handle VARBINARY(${PRINCIPAL_MAX_BYTES}) NOT NULL,
     retired_at_ms BIGINT NOT NULL,
     -- 退役前的显示名(会话的删前 title)。纯显示面:目录据它铸 PeerSessionRecord.name;NULL = 当时无名可用。
     label TEXT NULL,
@@ -281,18 +286,18 @@ export const MAILBOX_INDEXES = [
 ];
 export async function ensurePgMailboxSchema(q) {
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
-    scope VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    scope VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     next_seq BIGINT NOT NULL,
-    lease_owner VARCHAR(190) COLLATE "C",
+    lease_owner VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C",
     lease_expires_at_ms BIGINT,
     lease_max_seq BIGINT,
     PRIMARY KEY (scope_key, handle)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_MSG_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     seq BIGINT NOT NULL,
     from_id VARCHAR(255) COLLATE "C",
     content TEXT COLLATE "C" NOT NULL,
@@ -304,16 +309,16 @@ export async function ensurePgMailboxSchema(q) {
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_CONSUMED_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     seq BIGINT NOT NULL,
     record_id VARCHAR(${MAILBOX_RECORD_ID_MAX_CHARS}) COLLATE "C" NOT NULL,
     digests TEXT COLLATE "C" NOT NULL, -- TiDB twin 同注:已收窗(core 7.61.0),四面摘要 JSON
     PRIMARY KEY (scope_key, handle, seq)
   )`);
     await q(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TOMBSTONE_TABLE} (
-    scope_key VARCHAR(190) COLLATE "C" NOT NULL,
-    handle VARCHAR(190) COLLATE "C" NOT NULL,
+    scope_key VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
+    handle VARCHAR(${PRINCIPAL_MAX_BYTES}) COLLATE "C" NOT NULL,
     retired_at_ms BIGINT NOT NULL,
     label TEXT COLLATE "C", -- TiDB twin 同注:纯显示面,NULL = 无名可用
     PRIMARY KEY (scope_key, handle)
@@ -441,10 +446,7 @@ export class TiDBMailboxStore {
     async drop(scope, handle) {
         if (keyless(scope, handle))
             return;
-        await this.tx(async (c) => {
-            for (const table of MAILBOX_KEYED_TABLES)
-                await c.query(mailboxKeyDeleteSql("mysql", table), [scope, handle]);
-        });
+        await this.tx((c) => dropMailboxBoxOn(c, "mysql", scope, handle));
     }
     async reap(scope, now, opts) {
         if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)
@@ -617,10 +619,7 @@ export class PgMailboxStore {
     async drop(scope, handle) {
         if (keyless(scope, handle))
             return;
-        await this.tx(async (c) => {
-            for (const table of MAILBOX_KEYED_TABLES)
-                await c.query(mailboxKeyDeleteSql("pg", table), [scope, handle]);
-        });
+        await this.tx((c) => dropMailboxBoxOn(c, "pg", scope, handle));
     }
     async reap(scope, now, opts) {
         if (opts?.maxAgeMs === undefined || mailboxKeyProblem("scope", scope) !== undefined)

package/dist/stores-sql/pg-session-storage.d.ts

@@ -4,8 +4,10 @@ import { WindowedSessionStorage } from "./windowed-session-storage.js";
 import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
+import { type RegisterReceipt, type WithdrawOutcome } from "../session-incarnation.js";
 import type { SessionWriteHooks } from "./session-write-hooks.js";
 import { type IndexSpec } from "../plugins/ensure-index.js";
+import { type SessionDeleteCondition } from "./tidb-session-store.js";
 import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
@@ -31,7 +33,7 @@ export declare class PgSessionStorage extends WindowedSessionStorage {
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
     /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin: the same reading
-     *  ({@link scanEpochAnchor}, the record as stored), this backend's page query. */
+     *  ({@link scanEpochAnchor}: the floor's parent chain, the record as stored), the same page in this dialect's spelling. */
     getEpochAnchor(): Promise<unknown>;
     /** @see TiDBSessionStorage.wake — F3 bounded `[floor..leaf]` rebuild; null if the session does not exist. */
     static wake(pool: Pool, sessionId: string): Promise<PgSessionStorage | null>;
@@ -75,6 +77,10 @@ export declare class PgSessionStore implements SessionStore {
     private load;
     /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
+    /** 出生回执面(TiDB 孪生 {@link TiDBSessionStore.registerWithReceipt} 同义:候选 = 这一次 INSERT 入参里铸的化身)。 */
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    /** 条件删除(TiDB 孪生 {@link TiDBSessionStore.deleteSessionIf} 同义)。 */
+    deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /** acquire 的建行(唯一一处;placed 会话的属主 = `placement.owner` 原样,core 7.62.0 [ref] 盒义务 7 —— TiDB 孪生同名方法同注)。 */
     private createOnAcquire;
     /** The one session_meta INSERT. Existing owner is never overwritten.
@@ -151,10 +157,6 @@ export declare class PgSessionStore implements SessionStore {
      *  under a `%#stg-%` id with NO session_meta whose oldest row is older than the grace window (in-flight stays fresh).
      *  Returns the affected row count. Driven by main.ts's reaper. */
     sweepStagingSessions(): Promise<number>;
-    /** @see TiDBSessionStore.deleteSession — purge session_meta + session_event; idempotent (false if absent).
-     *  Owner-guarded on session_meta.owner (`IS NOT DISTINCT FROM` = the PG `<=>`); the event purge is gated on the
-     *  owner-matched meta delete (session_event has no owner column). A live run claim read inside the txn ⇒ `SessionActiveRunError`. */
-    deleteSession(sessionId: string, owner: string | null): Promise<boolean>;
     get size(): number;
     dispose(): void;
 }