@sema-agent/server 7.146.0 → 7.148.0

package/dist/session-deletion.d.ts

@@ -0,0 +1,88 @@
+/**
+ * **会话的三态:活 → 在删 → 没了**(删会话 × 提交只赢一个的律;规则只写在这里一次,三只会话店与删除协调器同读)。
+ *
+ * ## 律
+ * 一只会话行此刻是三态之一:
+ *  · **活** —— 接受一切读写;
+ *  · **在删** —— 一次删除已经在根行锁里判过「没有在跑的 run、属主是调用方」并立了围栏(写下自己的**删除尝试令牌**),还没删完。在删由持令牌的那一次删除**独占**:
+ *    删除门之外的一切读者与写者把它读作「行不在」(头读、列表、认领点的规则 L、登记 —— 撞上即「已存在」,不新建);认领落不下,于是删除级联的每一腿都只作用在一只
+ *    不会再起回合的会话上;
+ *  · **没了** —— 行删掉了;同 id 的下一次登记是新住客。
+ * 在删**不回到活**(没有放弃删除的臂:子代可达性预检在围栏之前,终刀失败只会重试)⇒ 围栏之后立的外部围栏(会话盒墓碑)不会挡错一只活会话。
+ *
+ * ## 谁写、谁读
+ *  · 围栏(活 → 在删 / 在删 → 在删 = 接管已死的那一次、换令牌)= {@link SessionDeletionFace.fence}:删除路**唯一**的认领判;一次仍可能活着的删除持有的行**不接管**
+ *    (答「在删中」)—— 否则陈旧尝试与接管者交错、接管者删完而同 id 重登记之后,陈旧尝试的下一腿会落在新住客身上;
+ *  · 终刀(在删 → 没了)= 删净一只会话的**执行体**(`src/session-erase.ts`;SQL = 执行器的 `eraseSession`,local = 会话店的删除锁节 `deleteSession(id, owner, token, legs)`):
+ *    根行锁里比属主、判「这一行处于本令牌的在删态」(判官 `judgeSessionWrite` 的 `erase` 词),不是 ⇒ 一行不删;是 ⇒ 同一个事务 / 锁节删完会话挂靠的全部行、行最后删;
+ *  · 执行体之前的每一步进程面动作(不在根行锁里)之前,协调器问 {@link SessionDeletionFace.holds}:令牌被换了(另一次删除接管)⇒ 这次尝试就此停,答「被接管」;
+ *  · 唯一收尾者 = 删除协调器:起服装配完之后按 {@link SessionDeletionFace.pending} 逐只再跑一遍(= 接管**那一只令牌**:读到之后那一次删完、同 id 重登记的新行不被碰);
+ *    持有者已死的在删行,重发的 DELETE 同样是接管。
+ * 持久面:SQL = 旁表 `session_ext.deleting_token`(列属主 `plugins/session-ext-table.ts`);local = 会话元数据边档那一格的 `deleting`。
+ */
+/** 围栏的回执:这一次删除的令牌 + 被删的那一位住客的化身(空间回收的键;存量行没有化身 ⇒ `undefined`)。 */
+export interface SessionDeletionTicket {
+    readonly token: string;
+    readonly incarnation: string | undefined;
+}
+/** 此刻处于在删态的一行(收尾者的输入):它的 id、属主与持有它的令牌(收尾按这一位属主、**只接管这一只令牌**再跑一遍协调器)。 */
+export interface PendingSessionDeletion {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly token: string;
+}
+/**
+ * 一只在删令牌的持有者此刻在哪(协调器答,它记得本进程铸过的每一只令牌):`running` = 本进程里那一次删除还在跑;`ended` = 本进程里那一次已经结束而没删完
+ * (某腿失败 / 被接管)—— 死的;`elsewhere` = 不是本进程铸的(上一个进程 / 别的副本)。
+ */
+export type DeletionHolder = "running" | "ended" | "elsewhere";
+/** 围栏的选项:`holder` = 令牌持有者在哪(协调器的在飞表);`expect` = 只接管这一只令牌(收尾者;活行 / 别的令牌 ⇒ `undefined`)。 */
+export interface SessionDeletionFenceOptions {
+    readonly holder: (token: string) => DeletionHolder;
+    readonly expect?: string;
+}
+/** 围栏的答复:回执(本次立了 / 接管了)· `inProgress`(一次仍可能活着的删除持有这一行 —— 不接管)· `undefined`(行不在 / 属主不是这一位 / 收尾者的令牌对不上)。 */
+export type SessionDeletionFenceAnswer = SessionDeletionTicket | {
+    readonly inProgress: true;
+} | undefined;
+/**
+ * 别的进程里一次删除的令牌**多久之后**才可以被接管(SQL 多副本:另一副本上那一次删除可能还活着,本进程看不见它)—— 令牌是 uuidv7,它的时刻就是那一次尝试的起点。
+ * 一次删除的各腿通常几秒内跑完(子代停止有轮次上界、后台 shell 的硬杀宽限是秒级);十分钟之后仍未删完的读作那一次已死(崩溃 / 进程被杀)。
+ * 如实的边:一次活着却卡过十分钟的删除会被接管,它此后的每一腿之前读到令牌已换、就此停 —— 两腿之间的那一拍是披露的残余(`src/boot/session-faces.ts` 的协调器注)。
+ * local 数据根独占(一个数据根恒一个进程),别的进程的令牌一律是死的 ⇒ 不读这只数。
+ */
+export declare const CROSS_PROCESS_TAKEOVER_AFTER_MS: number;
+/** 一只令牌(uuidv7)的铸造时刻(ms;读不出 ⇒ `undefined`,读者按「刚铸」处置 —— 不接管)。 */
+export declare function deletionTokenMintedAt(token: string): number | undefined;
+/** 会话店的删除面(三只会话店各一只实现,暖缓存包装原样转发;一只能力位 —— 三个动词同在或同缺)。 */
+export interface SessionDeletionFace {
+    /**
+     * 立围栏:根行锁里 ——
+     *  · 活行 ∧ 属主是 `owner`(字面相等,`null` 与 `null` 相等)∧ 不带 `expect` ⇒ 判认领(在 ⇒ 抛 `SessionActiveRunError`,一个字节不写)、写新令牌;
+     *  · 在删行 ∧ 属主等 ∧(不带 `expect` 或持有的就是它)⇒ 持有它的那一次**仍可能活着**(`holder` 答 `running`;SQL 另加:答 `elsewhere` 而令牌铸于
+     *    {@link CROSS_PROCESS_TAKEOVER_AFTER_MS} 之内 —— 别的副本上那一次可能还在跑)⇒ `{ inProgress }`(不接管、不写);否则(那一次已死)⇒ **接管**:换新令牌
+     *    (在删期间认领落不下,不再判);带 `expect` 而持有的不是它 ⇒ `undefined`;
+     *  · 行不在 / 属主不等 / 带 `expect` 而这一行是活的 ⇒ `undefined`(一个字节不写)—— 收尾者永远不把一只活行送进在删。
+     */
+    fence(sessionId: string, owner: string | null, opts: SessionDeletionFenceOptions): Promise<SessionDeletionFenceAnswer>;
+    /** `token` 此刻仍是这只会话的在删令牌(无锁一读;行不在 / 活 / 别的令牌 ⇒ `false`)。 */
+    holds(sessionId: string, token: string): Promise<boolean>;
+    /** 此刻处于在删态的全部行(按 id 排序)。 */
+    pending(): Promise<readonly PendingSessionDeletion[]>;
+}
+/**
+ * 删除协调器的结局(`DELETE /v1/sessions/:id` 读它,一形一句):
+ *  · `{ deleted: true }` —— 这一次删完了(终刀删掉了行);`{ deleted: false }` —— 门验过之后行已不在 / 不是这一位的(什么都没删);
+ *  · `{ active }` —— 围栏判到认领(409 `conflict.session_active_run`,一字节没写);`{ childrenAlive }` —— 子代预检拒(409 `conflict.session_children_alive`,一字节没写);
+ *  · `{ inProgress: true }` —— 同一只会话的另一次删除持有它(仍在跑,或接管了这一次)—— 409 `conflict.session_deleting`,由那一次删完;这次请求不再删任何东西。
+ */
+export type SessionPurgeOutcome = {
+    readonly deleted: boolean;
+} | {
+    readonly active: string;
+} | {
+    readonly childrenAlive: readonly string[];
+} | {
+    readonly inProgress: true;
+};
+//# sourceMappingURL=session-deletion.d.ts.map

package/dist/session-deletion.js

@@ -0,0 +1,8 @@
+export const CROSS_PROCESS_TAKEOVER_AFTER_MS = 10 * 60_000;
+export function deletionTokenMintedAt(token) {
+    const hex = token.replace(/-/g, "");
+    if (!/^[0-9a-f]{32}$/i.test(hex) || hex[12] !== "7")
+        return undefined;
+    return parseInt(hex.slice(0, 12), 16);
+}
+//# sourceMappingURL=session-deletion.js.map

package/dist/session-erase.d.ts

@@ -0,0 +1,145 @@
+/**
+ * **删净一只会话 —— 一只执行体**(两个决定者共用:`DELETE /v1/sessions/:id` 的删除协调器 `boot/session-faces.ts`,与托管留存的会话树清扫)。
+ *
+ * ## 律
+ * 删净一只会话 = **在这只会话的行锁下**删完它挂靠的全部行,行本身最后删:
+ *  · SQL 后端:一个事务(执行器 `stores-sql/retention-store-sql.ts` 的 `eraseSession` / `deleteExpiredSessions`,两只入口跑同一段事务体
+ *    —— 锁行 → 会话座事务内钩判 → 部署行 → 引擎座行 → 行与日志 → 墓碑);
+ *  · local 后端:{@link createLocalSessionEraser} —— 会话店这只会话的写锁一节(判 → 各店动词按 {@link SESSION_TREE_LEGS} → 删行)。
+ * 锁里那一判按决定者:在线删除 = 行的属主是围栏判过的那一位 ∧ `erase`(这一行处于**这一次删除的在删态** —— 令牌比对;会话三态 活 → 在删 → 没了,
+ * 律在 `session-deletion.ts`,围栏是删除协调器的事);留存 = `retention-delete`(没有认领、不在删)。令牌只在围栏判过属主之后写下,同 id 的下一位住客是新行、不带它 ⇒
+ * 一次陈旧 / 被接管的删除在锁里读到的不是自己的令牌,一行不删(`superseded`)。属主那一比是域键的一致性(SQL 的部署行与墓碑按域写,域在事务开之前就要定)。
+ * 会话挂靠的**行**都在锁里(含完成信箱的清除围栏与会话盒):删不掉 ⇒ 行留在删、删除可重试;锁着 ⇒ 碰不到下一位住客。提交之后由**同一只**收尾
+ * {@link createSessionEraseSettler} 处理按内容 / 按住客化身寻址的残余(附件字节、住客空间);SQL 组合座另在提交之后按「入队不晚于提交」清一次
+ * 事务进行中落下的迟到完成行(`retention-deployment.ts` 的 `sweepLateCompletionRows`)。
+ * 不在锁里的:在线删除在围栏之后、执行体之前对这只在删会话做的进程面动作(信箱 retire 围栏、子代结束、scratchpad、后台 shell、删过的 id)——
+ * 删除协调器每一步之前核令牌(`boot/session-faces.ts`);一步已经开跑时被接管的那一拍是协调器注里披露的残余(不是行)。
+ *
+ * ## 决定者之差
+ * 在线删除删的是一只**可能还活着**的会话(删前:子代预检 → 围栏 → 信箱 retire 围栏、子代结束、本进程删过的 id;删后:本副本的进程态);留存只删闲到视界外、
+ * 无活引用、不在删的会话(hold / 候选 / 活引用 / 审计)。行面唯一的差:规则行的 rev 高水位记号(在线留、留存删;`retention-store-sql.ts` 的 `RuleMarks`)。
+ */
+import { type MailboxStore, type ToolResultStore } from "@sema-agent/core";
+import type { Logger } from "./observability/logger.js";
+import type { WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
+import type { SpaceReclaimer } from "./workspace-space.js";
+/** 锁里读到的这一位住客(会话行上的属主 + 化身;存量行没有化身 ⇒ `undefined`)。 */
+export interface SessionOccupant {
+    readonly owner: string | null;
+    readonly incarnation: string | undefined;
+}
+/** 一次执行体提交之后交收尾的东西:真删掉的会话(id + 删前属主 + 住客)、本次删掉的附件行的字节哈希、全库无出处卸载结果数。 */
+export interface SessionTreesErased {
+    readonly sessions: readonly {
+        readonly sessionId: string;
+        readonly owner: string | null;
+        readonly incarnation: string | undefined;
+    }[];
+    /** 本次删掉的附件行的字节哈希(收尾按「无行引用才删」释放;local 的附件店随行删字节,恒空)。 */
+    readonly attachmentShas: readonly string[];
+    /** 全库无出处的卸载结果行数(core 口径:这类行任何会话删除都删不到 ⇒ 删除不完整;实体清理归 TTL)。 */
+    readonly unattributableToolResults: number;
+}
+/** 执行体的回执(闭集)。 */
+export type SessionEraseReceipt = 
+/** 这一行此刻不是这一次删除的在删态 —— 另一次删除接管了它(换了令牌)或已经删完(行不在 / 同 id 的新住客)。一行没删。 */
+{
+    readonly outcome: "superseded";
+}
+/** 全部行已删、已提交。 */
+ | {
+    readonly outcome: "erased";
+    readonly trees: SessionTreesErased;
+};
+/** 执行体的入参:哪只会话 + 删除协调器的围栏判过的那一位属主(域键)+ 围栏写下的令牌(判官比的那一只)。 */
+export interface SessionEraseInput {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly token: string;
+}
+/** 删净一只在删会话的执行体(SQL:执行器的组合座交出;local:{@link createLocalSessionEraser})。 */
+export interface SessionEraser {
+    erase(input: SessionEraseInput): Promise<SessionEraseReceipt>;
+}
+/**
+ * 会话树的行腿 —— **闭集,序即执行序**(SQL 事务体的语句序对它:`test/session-erase-single-executor.test.ts` 录制钉按首次出现序比)。
+ * `checkpoint` 腿含停驻 ctx 旁表(SQL 上 ctx 在部署段、检查点行在引擎座段,首次出现序落在这里)。`mailbox` 是行删除之前的**最后一腿**:会话盒的 `drop`
+ * 同时撤掉投递围栏(墓碑随箱亡),之后除了会话行不许再有别的腿(local 上各店逐个落盘,围栏撤了而行还在的那一段窗只容会话行那一步)。
+ */
+export declare const SESSION_TREE_LEGS: readonly ["runs", "approval", "checkpoint", "anchors", "exemption", "attachment", "user_input", "task_list", "workflow_inbox", "tool_result", "policy", "file_history", "mailbox"];
+export type SessionTreeLeg = (typeof SESSION_TREE_LEGS)[number];
+/** local 执行体的各店(缺席 = 本部署没有这只店 ⇒ 这一腿无行可删)。动词与在线协调器此前逐店调的同一组。 */
+export interface LocalSessionTreeStores {
+    readonly runStore: {
+        deleteBySession(sessionId: string): Promise<{
+            removed: number;
+        }>;
+    } | undefined;
+    readonly approvalAskStore: {
+        deleteBySession(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly checkpointStore: {
+        deleteBySession(sessionId: string, owner: string | null): Promise<number>;
+    } | undefined;
+    readonly resumeAnchorStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly approvalExemptionStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly taskAttachmentStore: {
+        deleteBySession(sessionId: string): Promise<number>;
+    } | undefined;
+    readonly userInputLedgerStore: {
+        deleteBySession(sessionId: string): Promise<unknown>;
+    } | undefined;
+    readonly taskListLane: {
+        deleteBySession(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly workflowCompletionInbox: Pick<WorkflowCompletionInbox, "purge"> | undefined;
+    readonly mailboxStore: Pick<MailboxStore, "drop"> | undefined;
+    readonly toolResultStore: Pick<ToolResultStore, "deleteBySession"> | undefined;
+    readonly sessionPolicyStore: {
+        deleteBySession?(sessionId: string): Promise<void>;
+    } | undefined;
+    readonly fileHistoryErasure: {
+        deleteBySession?(scope: string): Promise<unknown>;
+        reap(scope: string, keep: readonly string[]): Promise<unknown>;
+    } | undefined;
+}
+/**
+ * local 会话店的删除锁节(`plugins/local-session-store.ts` 的 `deleteSession`):这只会话的写锁里 —— 行不在 / 属主不是 `owner` ⇒ `undefined`;
+ * `erase` 判(这一行处于 `token` 那一次删除的在删态;不是 ⇒ 抛 `SessionDeletionSupersededError`)—— 两支都一行不删;→ `legs(锁里读到的住客)` → 删行,交回那一位住客。
+ */
+export type LocalSessionDeletionSection = (sessionId: string, owner: string | null, token: string, legs: (occupant: SessionOccupant) => Promise<void>) => Promise<SessionOccupant | undefined>;
+/**
+ * local 后端的执行体:会话店写锁一节里按 {@link SESSION_TREE_LEGS} 跑各店动词(闭集 `switch`,漏一腿 = 编译红)。一腿抛 ⇒ 锁节抛、行不删(重发收敛)。
+ */
+export declare function createLocalSessionEraser(deleteSession: LocalSessionDeletionSection, stores: LocalSessionTreeStores, logger: Pick<Logger, "warn">): SessionEraser;
+/** 收尾要的座(缺席 = 本部署没有这一样残余)。 */
+export interface SessionEraseSettleSeats {
+    /** 附件字节的释放口(SQL 附件店:无行引用才删对象)。 */
+    readonly attachments: {
+        releaseBytes(shas: readonly string[]): Promise<{
+            readonly failed: readonly string[];
+        }>;
+    } | undefined;
+    readonly spaceReclaimer: SpaceReclaimer | undefined;
+    readonly logger: Pick<Logger, "warn">;
+}
+/**
+ * 收尾:一次执行体提交之后对真删掉的会话处理库外残余。答出时附件字节那一步已做完;`spaces` = 住客空间回收那一步
+ * (对象存储上的一串请求,座按契约不抛、抛了已被这里响亮接住 ⇒ 它永不拒):在线删除不等它(应答不等对象存储),留存清扫等它(一轮在截止上收手)。
+ */
+export type SessionEraseSettler = (trees: SessionTreesErased) => Promise<{
+    readonly spaces: Promise<void>;
+}>;
+/**
+ * 两个决定者共用的**收尾**(行已删、已提交)。只收**按内容寻址 / 按住客化身寻址**的残余 —— 碰不到同 id 重登记的下一位住客;
+ * 会话挂靠的行(含完成信箱围栏与行、会话盒)都在执行体的锁里(删不掉 ⇒ 行留着、删除可重试)。每一步失败只记一行 warn,各有兜底:
+ *  ① 附件字节 —— 本次删掉的附件行的哈希,无行引用才删对象(孤儿 GC 兜底);
+ *  ② 住客空间 —— 住客化身在的会话交回收座(答案里的 `spaces`:等不等它是决定者的事;座按契约不抛,抛了这里响亮接住;桶的生命周期规则兜底);
+ *  ③ 全库无出处卸载结果数 > 0 ⇒ 一行 warn(删除不完整的如实告知)。
+ */
+export declare function createSessionEraseSettler(seats: SessionEraseSettleSeats): SessionEraseSettler;
+//# sourceMappingURL=session-erase.d.ts.map

package/dist/session-erase.js

@@ -0,0 +1,115 @@
+import { peerSessionBoxHandle } from "@sema-agent/core";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { redactIncarnations } from "./session-incarnation.js";
+import { seatText } from "./trace/exit-seat.js";
+import { sessionTenantScope } from "./session-children-retire.js";
+import { SessionDeletionSupersededError } from "./execution-placement.js";
+export const SESSION_TREE_LEGS = ["runs", "approval", "checkpoint", "anchors", "exemption", "attachment", "user_input", "task_list", "workflow_inbox", "tool_result", "policy", "file_history", "mailbox"];
+export function createLocalSessionEraser(deleteSession, stores, logger) {
+    return {
+        async erase({ sessionId, owner, token }) {
+            let unattributable = 0;
+            const leg = async (which, occupant) => {
+                switch (which) {
+                    case "runs":
+                        return void (await stores.runStore?.deleteBySession(sessionId));
+                    case "approval":
+                        return void (await stores.approvalAskStore?.deleteBySession(sessionId));
+                    case "checkpoint":
+                        return void (await stores.checkpointStore?.deleteBySession(sessionId, occupant.owner));
+                    case "anchors":
+                        return void (await stores.resumeAnchorStore?.deleteBySession(sessionId));
+                    case "exemption":
+                        return void (await stores.approvalExemptionStore?.deleteBySession(sessionId));
+                    case "attachment":
+                        return void (await stores.taskAttachmentStore?.deleteBySession(sessionId));
+                    case "user_input":
+                        return void (await stores.userInputLedgerStore?.deleteBySession(sessionId));
+                    case "task_list":
+                        return void (await stores.taskListLane?.deleteBySession(sessionId));
+                    case "workflow_inbox":
+                        return void (await stores.workflowCompletionInbox?.purge(sessionId, occupant.owner));
+                    case "tool_result": {
+                        const report = await stores.toolResultStore?.deleteBySession?.(sessionId);
+                        if (report !== undefined)
+                            unattributable = report.unattributable;
+                        return;
+                    }
+                    case "policy":
+                        return void (await stores.sessionPolicyStore?.deleteBySession?.(sessionId));
+                    case "file_history": {
+                        const erasure = stores.fileHistoryErasure;
+                        if (erasure === undefined)
+                            return;
+                        if (typeof erasure.deleteBySession === "function")
+                            return void (await erasure.deleteBySession(sessionId));
+                        await erasure.reap(sessionId, []);
+                        logger.warn("session_file_history_baselines_retained", {
+                            sessionId,
+                            note: "this file-history store has no whole-scope erase verb (deleteBySession); boundaries were reaped but v1 baselines (original file bytes) remain in the store until it implements that verb — an open deletion-rights gap, not silent",
+                        });
+                        return;
+                    }
+                    case "mailbox":
+                        return void (await stores.mailboxStore?.drop(sessionTenantScope(occupant.owner), peerSessionBoxHandle(sessionId)));
+                    default: {
+                        const unknownLeg = which;
+                        throw new Error(`session erase: no arm for leg ${JSON.stringify(unknownLeg)}`);
+                    }
+                }
+            };
+            let erased;
+            try {
+                erased = await deleteSession(sessionId, owner, token, async (occupant) => {
+                    for (const which of SESSION_TREE_LEGS)
+                        await leg(which, occupant);
+                });
+            }
+            catch (err) {
+                if (err instanceof SessionDeletionSupersededError)
+                    return { outcome: "superseded" };
+                throw err;
+            }
+            if (erased === undefined)
+                return { outcome: "superseded" };
+            return { outcome: "erased", trees: { sessions: [{ sessionId, ...erased }], attachmentShas: [], unattributableToolResults: unattributable } };
+        },
+    };
+}
+export function createSessionEraseSettler(seats) {
+    const { logger } = seats;
+    return async (trees) => {
+        if (trees.attachmentShas.length > 0 && seats.attachments !== undefined) {
+            const released = await seats.attachments.releaseBytes(trees.attachmentShas).catch((err) => ({ failed: trees.attachmentShas, err: seatText("operator-log-text", String(err)) }));
+            if (released.failed.length > 0) {
+                logger.warn("session_erase_attachment_bytes_release_failed", {
+                    shas: trees.attachmentShas.length,
+                    failed: released.failed.length,
+                    ...("err" in released ? { err: released.err } : {}),
+                    effect: "these objects stay until the orphan-object sweep collects them (its grace applies)",
+                });
+            }
+        }
+        const spaces = trees.sessions.flatMap((s) => (s.incarnation === undefined ? [] : [{ sessionId: s.sessionId, spaceKey: s.incarnation }]));
+        let reclaimed = Promise.resolve();
+        if (spaces.length > 0 && seats.spaceReclaimer !== undefined) {
+            reclaimed = seats.spaceReclaimer.reclaim(spaces).catch((err) => {
+                recordFailOpen("server.workspace-space.reclaim-failed", "stage=seat_threw");
+                logger.warn("workspace_space_reclaim_failed", {
+                    sessions: spaces.length,
+                    stage: "seat_threw",
+                    error: seatText("operator-log-text", redactIncarnations(String(err))),
+                    effect: "the ended space's cache volume and snapshot objects may stay (the reclaim seat threw, which its contract forbids; the session delete went ahead) — the bucket's lifecycle rule is the fallback for objects, the volume is deleted by label sema.space",
+                });
+            });
+        }
+        if (trees.unattributableToolResults > 0) {
+            logger.warn("tool_result_unattributable_rows_survive_session_delete", {
+                sessions: trees.sessions.map((s) => s.sessionId),
+                unattributable: trees.unattributableToolResults,
+            });
+        }
+        return { spaces: reclaimed };
+    };
+}
+//# sourceMappingURL=session-erase.js.map

package/dist/session-error-wire.d.ts

@@ -21,7 +21,7 @@
  *    (悬空父而回放没丢记录 / 自指 / 成环 / 叶子缺席 / 分叉走链 —— 7.137.0–7.143.0 那一形是 `invalid_session`,见下一词)。不是 4xx:调用方没做错
  *    任何事;不是 503:重试改不了判(修复在运维手里)—— 与会话规则店的 `corrupt` 同一档同一理由。码不另铸(core 的词
  *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
- *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
+ *    `stores-sql/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
  *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);`open` 面**留白**:core 7.62.0
  *    ([ref] / [ref])起它只是导入门的词,打开已存日志从不抛它 —— 走不成一棵树的已存日志是 `corrupt_session`(上一词);回放丢了记录的悬空父不再失败,
  *    run 从断点续上并在流上说 `session.lineage_rerooted`。7.137.0–7.143.0 本表在 open 面给过它一格 500 `invalid_session`(那时 core 用它说已存日志的结构坏),
@@ -30,14 +30,14 @@
  *      (同 `placement_kind` 的先例),不在这里解析句子。
  *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
  *    列表里的缺席),码位各不相同,不由本表统一。
- *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `detail.placement_kind`,固定句);`open` 面留白。
+ *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `placement_kind`,在拒体根上;固定句);`open` 面留白。
  *    同一个词在两面上说的不是同一件事:import 面只有「会话同步往一只**分区会话**(委派子代的转录)上写」一个来源
  *    (三只持久会话店的整段换装 / 暂存提交门:目标 id 的 `placement_kind` 在场 ⇒ 不适用),调用方没做错格式、是**目标**不收这种写;
  *    open 面上同一个词还含「声明了分区的创建撞上了分区外 / 异组的行」两形(core `TtlSessionStore.assertPlacementAdmission` 的后两条),
  *    那不是「目标是分区会话」。而 run 终局上它是引擎词汇(`terminal.code`),原样随 failed 体走 —— 若在这里分诊成 409,
  *    体上的 `errorCode` 仍是引擎词 `placement_refused`,一个状态两个名字。所以 open 面留白。
  *    409 的语义:目标会话**状态**不收这种写(重试同一个 id 同一结果;换一个会话 id 推)—— 与 `conflict.session_ownerless` / `conflict.session_children_alive` 同族。
- *    `detail.placement_kind` 是**常量**,不是从错误里读的:core 的 `SessionError` 只带 `code` 与句子,不带种类;今天分区种类闭集只有
+ *    `placement_kind` 是**常量**,不是从错误里读的:core 的 `SessionError` 只带 `code` 与句子,不带种类;今天分区种类闭集只有
  *    `"subagent"` 一个词,所以常量就是事实。core 给 `SessionPlacementRecord["kind"]` 加第二个词 ⇒ 下面的守卫编译红,由人裁定种类从哪儿读
  *    (请求 core 把种类放进错误,而不是在这里解析句子)。
  *  · `invalid_entry` / `invalid_fork_target` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
@@ -76,8 +76,8 @@ export interface SessionErrorWire {
      * 点名条目 id / 会话 id / 引擎内部词,wire 上只回一句固定话(各自冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
      */
     readonly sentence?: string;
-    /** 机读事实(体顶层的 `detail` 键;缺席 = 体里不带这个键)。只有 import 面的 `placement_refused` 用它:`{ placement_kind }`。 */
-    readonly detail?: Readonly<Record<string, string>>;
+    /** 机读事实(摊在拒体根上;缺席 = 没有可机读的事实)。只有 import 面的 `placement_refused` 用它:`{ placement_kind }`(键名随 SQL 列)。 */
+    readonly facts?: Readonly<Record<string, string>>;
 }
 /** import 面 `invalid_session` 的固定句(修前 session-sync 暂存导入腿那一行的原文)。 */
 export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
@@ -108,7 +108,7 @@ export declare class StampedSessionArchiveError extends SessionError {
  *
  * 码与句子**就是**那只存档故障的(`cause` = 它;码不另铸 —— 只会是 `corrupt_session`,读不出而说不出在不在的 I/O 级故障不换型):
  * 不认识本型的站点看到的与此前逐字相同(`sessionErrorHttp` 按码映射,wire 与运维日志不变)。认识本型的站点 —— 会话读面的属主读
- * (`http/owner-access.ts` 的 `foldOwnerUnreadable`)—— 把它读成「没有这一行」:与对非属主、对不存在的会话同一只 404,原故障进运维日志。
+ * (`http/owner-access.ts` 的 `readOwnerCell`)—— 把它读成「没有这一行」:与对非属主、对不存在的会话同一只 404,原故障进运维日志。
  */
 export declare class SessionOwnerUnreadableError extends SessionError {
     constructor(fault: SessionError);

package/dist/session-error-wire.js

@@ -22,7 +22,7 @@ export class SessionOwnerUnreadableError extends SessionError {
 export const STAMPED_SESSION_ARCHIVE_SENTENCE = "this session's stored archive still carries an owner stamp written by an earlier server version, so it cannot be forked or have its log replaced; nothing was written — delete the session and push it again";
 const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
 const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
-const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, detail: { placement_kind: PLACEMENT_KIND } };
+const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, facts: { placement_kind: PLACEMENT_KIND } };
 const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
 const STAMPED_SESSION_ARCHIVE = { status: 409, errorCode: "conflict.session_archive_stamped", sentence: STAMPED_SESSION_ARCHIVE_SENTENCE };
 export function sessionErrorWireOf(e, face) {

package/dist/session-incarnation.d.ts

@@ -7,7 +7,7 @@
  *
  * ## 规则(全仓唯一处写)
  *  · **铸点只在新建行**:会话店的 `register` / 无 id 创建 / fork / session-sync 的导入新行。已存在的行化身一个字节都不动;
- *    session-sync 的整段换装(replace / staged commit)换的是**同一位住客**的日志,化身沿用 —— 属主却可以被换装重戳为导入者(local 的 M10 认领同理),
+ *    session-sync 的整段换装(replace / staged commit)换的是**同一位住客**的日志,化身沿用 —— 属主却可以被换装重戳为导入者,
  *    所以化身与属主不是同一条律(读法分三种,见下「两读」)。删除随行消失,同 id 重新登记铸新的。
  *  · **两读(住客的三种问法,各读各的格,不混用)**:
  *    K1 **住客自己的记录**(工作区、记忆、空间分区……按「这一位住客」落的东西)只按化身绑 —— 同一位住客的属主换代(推送重戳 / 认领)不换住客,记录照落;
@@ -15,7 +15,7 @@
  *    (`execution-placement.ts` 的 `sameOccupant`,SQL `incarnation = ? AND owner <=> ?` 的对位)—— 读与写之间属主换了一代 ⇒ 不是判过的那一行;
  *    K0 **只问属主的门**(授权门、暂存提交的属主 CAS)只读属主那一格。三种都读会话**行**;local 店的行 = 会话元数据边档那一格(引擎仓里的存档是匿名内容仓,
  *    存档头上的属主不是行事实 —— `plugins/local-session-store.ts` 头注)。
- *  · **值是不透明随机串**(`randomUUID()`,v4:没有时间戳、没有机器信息 —— 刻意不用 uuidv7,那一形带铸造时刻)。只拿来比较。
+ *  · **值是不透明随机串**(铸法只有 core 的 `incarnationCell(undefined)`,v4:没有时间戳、没有机器信息 —— 刻意不用 uuidv7,那一形带铸造时刻)。只拿来比较。
  *  · **一格、一个解码**:住客令牌是会话**行**上的一格 —— SQL `session_meta.incarnation`(两方言)、local 后端的会话元数据边档那一格
  *    (`plugins/local-session-store.ts` 的 `session-incarnations.json`)。行上的值只经 {@link incarnationFromCell} 解码。
  *  · **按 id 读只有一只:core 的 `SessionStore.headOf(id)`**(core 7.55.0 [ref] S2;`{ owner, incarnation, leafId }`,同一行、同一次读 ——
@@ -28,11 +28,14 @@
  *    内容读不出时,头照答行上的属主与住客,叶子那一格带着读它时撞上的那只故障({@link UnreadableLeaf}),**谁读叶子谁收到它**。
  *    于是只判归属的读者(授权门、各路由的属主门、删除的围栏、住客读)对坏内容与好内容同答,内容的故障只让门放行之后读内容的那一位看见;
  *    行本身读不出(local:边档里还没有这只会话的那一格、要从存档推出它在不在,而存档读不出)⇒ 头读整只拒(读故障,不是答案)。
- *  · **两头是不是同一位住客:core 的 `compareOccupants`**(三答 `same` / `different` / `unknown`;任一侧没有行或没有令牌 ⇒ `unknown`,
- *    `unknown` 永不当 `same`)。本仓自写的比较(`sameSessionOccupant`)退役:同一个问题只有引擎那一只判官。
+ *  · **两头是不是同一位住客:core 的 `compareOccupants`**(三答 `same` / `different` / `unknown`;core 7.65.0 起:任一侧没有行 ⇒ `unknown`;
+ *    两侧都有行时按引擎的一种读法比两格 —— 都有令牌且相等,或都没有令牌(缺席 / `""` / 非串)⇒ `same`,一侧有一侧没有 ⇒ `different`;
+ *    `unknown` 永不当 `same`,没有令牌也永不当通配)。本仓自写的比较(`sameSessionOccupant`)退役:同一个问题只有引擎那一只判官。
+ *    「这只头有没有令牌」不从 `compareOccupants` 推,读头本身(`head.incarnation`)。
  *  · **一位活住客必须有令牌 —— 读到空化身 ⇒ 响亮拒**({@link SessionIncarnationMissingError}):本仓比 core 多的那一条律,只住在一处 ——
  *    把头投成 {@link SessionFace}(属主 + 一只令牌)的 {@link sessionFaceOfHead}(批量来源读与换装回读用同一只 {@link sessionFaceFromRow})。
- *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`。
+ *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`
+ *    (它对两只无令牌的头答 `same` —— 拒无令牌行从来不是它的答案,是这一只的)。
  *    空值只可能来自没铸化身的写腿、人为改库,或跳过了 7.104.0–7.135.x(那几版的起服迁移给存量行铸令牌,窗关后已删码)直接升上来的库 ——
  *    把它当「通配」就是让任何人都能和这一行比成同一位住客。
  *  · **不上 wire、不进模型上下文、不进日志正文**:日志里要点名时只打 {@link incarnationLogPrefix}(前 8 位)。值本身不出进程;唯一出进程的形是
@@ -44,10 +47,11 @@
  *    认领之后唯一写口按那一读的住客定址判一次(化身 ∧ 属主;不在或不是那一位 ⇒ 回滚认领、答既有的 `409 decide.not_parked`);
  *    赎回面(`parked-revive-surface.ts`)只收写口放行的那一位,属主 = 卡的 principal 时交继承座。
  *  · core 的记忆引擎:Runner 读**它取到的那只会话**的 `getMetadata().incarnation`(SQL 两店的 wake 带出这一列;local 店交出的会话
- *    在元数据上答边档那一格),不再有宿主座。
+ *    在元数据上答边档那一格),不再有宿主座。local 数据根上两条入口(HTTP 服务的 local 臂、run-local)经**同一只** local 店打开会话
+ *    (`plugins/store-backend.ts` 的 `openLocalBackend`)⇒ 同一只会话在两条入口上是同一位住客;引擎存档头上另铸的那只令牌不作住客读(只当存档的行代号)。
  *  · 没取会话的那一侧(k8s 工作区空间的分区,`boot/execution-env.ts`):会话店的 `headOf`,经 {@link sessionFaceOfHead} 拿令牌;缓存包装层原样转发。
  */
-import type { SessionHead } from "@sema-agent/core";
+import { type SessionHead, type SessionMetadata } from "@sema-agent/core";
 /** 一位活住客:属主 + 它的令牌(同一行、同一次读;投影自会话店的头,见 {@link sessionFaceOfHead})。 */
 export interface SessionFace {
     /** `null` = 登记为无主的会话。 */
@@ -57,7 +61,10 @@ export interface SessionFace {
 }
 /** 会话店的按 id 读(core `SessionStore.headOf` 的形):`undefined` = 没有这只会话;读抛 = 读故障,不是答案。 */
 export type HeadRead = (sessionId: string) => Promise<SessionHead | undefined>;
-/** 铸一只新化身(铸点见头注,只在新建行)。 */
+/**
+ * 铸一只新化身(铸点见头注,只在新建行)。**铸法只有 core 那一只**:`incarnationCell(undefined)` —— 引擎自带仓的唯一铸点(新行一只随机 v4 串,无时间无机器);
+ * 本仓不再自带第二份铸法。core 的返回型把这一格写作可选(`existing` 非空时可以无令牌),新行永远有 —— 这里只收窄成 `string`,缺了是响亮的不变量破,不补铸。
+ */
 export declare function mintSessionIncarnation(): string;
 /** 日志里点名一只化身时唯一允许的形:前 8 位。完整令牌不进任何日志正文。 */
 export declare function incarnationLogPrefix(incarnation: string): string;
@@ -125,16 +132,21 @@ export declare function sessionFaceOfHead(sessionId: string, head: SessionHead |
  * 一次性迁移 M23(窗内)的回填读的都是这一只返回值。缺席 = 店没有实装 `headOf`(读不出属主 / 住客 / 叶子,调用方各按自己的 fail-closed 臂处置)。
  */
 export declare function headReadOf(store: object | undefined): HeadRead | undefined;
+/**
+ * 删除门(`DELETE /v1/sessions/:id` 的属主门 + 协调器的化身围栏)的头读 —— **只判这一处**:店交了 `deletionHeadOf`(删除已开始、还没收完的那一行也答得出属主与住客;local)⇒ 它;
+ * 否则 ⇒ {@link headReadOf}(删除是一个事务的店,没有删到一半的行)。缺席 = 店没有按 id 读。
+ */
+export declare function deletionHeadReadOf(store: object | undefined): HeadRead | undefined;
 /** 换装沿用的行格(化身 + fork 键):{@link carriedRowCells} 的答案。`forkKey: null` = 没有可沿用的键(新建行 / 行上本来没有)。 */
 export interface CarriedRowCells {
     readonly incarnation: string;
     readonly forkKey: string | null;
 }
 /**
- * session-sync **换装**(整段换装 / 暂存提交)时行格的去留 —— 三只店共用的一句判据:换装只换内容,换的是**同一行**
+ * session-sync **换装**(整段换装 / 暂存提交)时行格的去留 —— local 店的判据(SQL 两店的换装就地改写同一行,化身与旁表行原地不动,同一结局、无需沿用判):换装只换内容,换的是**同一行**
  * ⇒ 行在且那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 化身与 fork 键(`fork_key` / local `forkKey`:建这一行的那次 fork
  * 请求的键,只由 fork 创建点写、此后每个写携带)**一起沿用**(属主重戳与否不改这一判:同一行 = 同一位住客);行不在(这是一次新建)或还是空的存量形 ⇒
- * 铸一只新化身、没有 fork 键。属主不在这里判:每只店在自己的属主门上判过被换的那一行(SQL 孪生的 replace 只交「属主门删得到的那一行」),读不中的换装一个字节不写。
+ * 铸一只新化身、没有 fork 键。属主不在这里判:店在自己的属主门上判过被换的那一行,读不中的换装一个字节不写。
  */
 export declare function carriedRowCells(sessionId: string, prior: {
     incarnation?: unknown;
@@ -155,4 +167,42 @@ export declare const SESSION_META_INCARNATION_COLUMN: {
     readonly mysql: "incarnation VARCHAR(64) NOT NULL DEFAULT ''";
     readonly pg: "incarnation VARCHAR(64) COLLATE \"C\" NOT NULL DEFAULT ''";
 };
+/**
+ * SQL 两方言 `session_meta` 的 fork 谱系两列(列定义的唯一属主;两方言建表语句各插一处 —— 与上面的化身列同住:谱系的住客那一半就是源行那一刻的化身;
+ * 谁写、怎么铸见 `plugins/session-fork.ts`「fork 谱系」)。宽度 = 会话 id 列 / 化身列的宽度(两格存的就是这两种值)。
+ * 可空:NULL = 不是 fork 建的行,或谱系落地之前建的 fork(不回填)。存量库缺这两列 ⇒ 起服列册对账拒启,拒句给 ALTER(由本建表语句生成)。
+ */
+export declare const SESSION_META_LINEAGE_COLUMNS: {
+    readonly mysql: "forked_from VARCHAR(64) NULL,\n     forked_from_incarnation VARCHAR(64) NULL";
+    readonly pg: "forked_from VARCHAR(64) COLLATE \"C\",\n     forked_from_incarnation VARCHAR(64) COLLATE \"C\"";
+};
+/**
+ * 行上谱系两格 → 交出的会话元数据的谱系两键(三店的唯一读法:SQL 唤醒读两列、列表读 `forked_from`;local 读那一格的两位)。
+ * 非空串 ⇒ 在;NULL / 缺 / 空串 ⇒ 键缺席(omit-when-absent,恒不铸 `null`)。来源住客读法 = 化身的宽读臂(与头读的住客同一只解码);它是谱系的住客那一半 ——
+ * 没有源 id 就没有谱系,来源住客也不单独交出。
+ */
+export declare function forkLineageOfRow(sessionId: string, forkedFrom: unknown, forkedFromIncarnation: unknown): Pick<SessionMetadata, "forkedFrom" | "forkedFromIncarnation">;
+/** 一次新建行交回的候选:哪只会话、记下的属主、这一次 INSERT 铸的化身(入参里铸的那一只,不是登记之后的复读)。 */
+export interface SessionBirth {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly incarnation: string;
+}
+/** 登记回执:`minted` 只在这一笔真建了新行时在场。 */
+export interface RegisterReceipt {
+    readonly minted?: SessionBirth;
+}
+/** 撤回判下来「留」的店内词(闭集;出口的计数词表在它之上加座内的词,`src/submission-exit.ts`)。`claim` = 这一行被持有:活 run 的认领,或一次删除的在删态(会话三态,`session-deletion.ts`)。 */
+export type StoreKeptWord = "absent" | "incarnation" | "content" | "claim" | "client_writes" | "runs" | "upgrade_pending";
+/** 撤回的结局。 */
+export type WithdrawOutcome = {
+    readonly withdrawn: true;
+} | {
+    readonly withdrawn: false;
+    readonly kept: StoreKeptWord;
+};
+/** 部署判据的答案(店的条件删除在同一事务里问部署):放行(本次 run 的部署行已在同一事务里删掉)或留(部署那一半的哪一条)。 */
+export type WithdrawJudgeVerdict = "proceed" | {
+    readonly keep: Extract<StoreKeptWord, "client_writes" | "runs" | "upgrade_pending">;
+};
 //# sourceMappingURL=session-incarnation.d.ts.map

package/dist/session-incarnation.js

@@ -1,6 +1,9 @@
-import { randomUUID } from "node:crypto";
+import { incarnationCell } from "@sema-agent/core";
 export function mintSessionIncarnation() {
-    return randomUUID();
+    const { incarnation } = incarnationCell(undefined);
+    if (incarnation === undefined)
+        throw new Error("core's incarnationCell(undefined) minted no token for a new row — refusing to invent one");
+    return incarnation;
 }
 export function incarnationLogPrefix(incarnation) {
     return incarnation.slice(0, 8);
@@ -67,6 +70,10 @@ export function headReadOf(store) {
     const read = store?.headOf;
     return typeof read === "function" ? read.bind(store) : undefined;
 }
+export function deletionHeadReadOf(store) {
+    const read = store?.deletionHeadOf;
+    return typeof read === "function" ? read.bind(store) : headReadOf(store);
+}
 export function carriedRowCells(sessionId, prior) {
     const held = prior === undefined ? undefined : incarnationFromCell(sessionId, prior.incarnation, "absent");
     if (held === undefined)
@@ -78,4 +85,14 @@ export const SESSION_META_INCARNATION_COLUMN = {
     mysql: "incarnation VARCHAR(64) NOT NULL DEFAULT ''",
     pg: `incarnation VARCHAR(64) COLLATE "C" NOT NULL DEFAULT ''`,
 };
+export const SESSION_META_LINEAGE_COLUMNS = {
+    mysql: "forked_from VARCHAR(64) NULL,\n     forked_from_incarnation VARCHAR(64) NULL",
+    pg: `forked_from VARCHAR(64) COLLATE "C",\n     forked_from_incarnation VARCHAR(64) COLLATE "C"`,
+};
+export function forkLineageOfRow(sessionId, forkedFrom, forkedFromIncarnation) {
+    if (typeof forkedFrom !== "string" || forkedFrom === "")
+        return {};
+    const occupant = incarnationFromCell(sessionId, forkedFromIncarnation, "absent");
+    return { forkedFrom, ...(occupant !== undefined ? { forkedFromIncarnation: occupant } : {}) };
+}
 //# sourceMappingURL=session-incarnation.js.map

package/dist/session-policy-wire.d.ts

@@ -21,7 +21,7 @@
  *  · 本仓自己的形读者、桶表与逐键问引擎的那一圈(同一问的第二个读者,[ref])⇒ 读回直接读引擎的形读法。
  */
 import { SessionPolicyError } from "@sema-agent/core";
-import type { SessionPermissionRules, SessionRuleEntryRefusal, SessionRuleShapeRefusal, SessionRulesRecord } from "@sema-agent/core";
+import type { SessionPermissionRules, SessionRuleEntryRefusal, SessionRulesRecord } from "@sema-agent/core";
 /** 引擎的两只**内容**拒(规则体自己的问题;`conflict` / `loosen_forbidden` / `corrupt` 是店与这一次写的关系,不在此列)。 */
 export type SessionRulesRefusal = SessionPolicyError & {
     readonly code: "invalid_shape" | "inert_entry";
@@ -120,8 +120,11 @@ export declare function describeInertEntry(r: SessionRuleEntryRefusal): string;
  * 引擎契约破了(`inert_entry` 不带条目读数)⇒ 抛,不编一句。
  */
 export declare function sessionPolicyErrorSentence(e: SessionPolicyError): string;
-/** 一只 `SessionPolicyError` 上 wire 的拒体格(引擎的 `detail` 原样摊在体顶层;只在两只内容码上有)。 */
-export declare function sessionPolicyErrorFacts(e: SessionPolicyError): Readonly<SessionRuleShapeRefusal | SessionRuleEntryRefusal> | undefined;
+/**
+ * 一只 `SessionPolicyError` 上 wire 的拒体事实(只在两只内容码上有):引擎的 `detail` 经**闭集映射**进拒体根(对位 `http/refusal-body.ts` 的 `resumeRefusalFacts`)——
+ * 按码取那一张键表,逐键过境、值原样;表外的键(引擎多带的成员、句子专用的 `carriedBy`)不过境,值为 `undefined` 的键不铸。
+ */
+export declare function sessionPolicyErrorFacts(e: SessionPolicyError): Readonly<Record<string, unknown>> | undefined;
 /**
  * 🔴 **`SessionPolicyError` 的闭集 → HTTP 的**唯一**映射(core 7.25.0 提货批新建)。**
  *