@xrn1997/dsh-session-delete 0.3.1 → 0.4.0

package/lib/types/shared/wire.d.ts

@@ -1,18 +1,9 @@
 /**
- * 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、六个端点段、请求字段名**——
- * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
- * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
+ * 跨半 wire 契约：前缀、九个端点、请求/响应形状与失败码。
+ * Node 半（src/api/dispatch.ts）与浏览器半（src/client/remote.ts）共用这一份，不各写字面量。
  *
- * 两条构建期硬约束（不是偏好）：
- *  ① tsdown 的浏览器半纯度门拦 Node 内建与平台模块表外的 `@deepseek-ai/*` 值 import——
- *     本文件两者都不涉及，且**零运行时依赖**（client 半把它整个 inline 进 bundle）；
- *  ② 跨插件一律 `import type`——本文件干脆没有 import。
- *
- * 信封（`RemoteResult`）与失败形状（`RemoteFailure`）也在这里——**因为它们本来就是两半的共同契约**：
- * Node 半按它产出（`src/api/dispatch.ts` 的失败支就是 `RemoteFailure` 那三件），浏览器半按它判别
- * （`src/client/remote.ts` 的 `unwrapRemoteResult` / `failureOf`）。形状取自宿主网关客户端面的原文
- * 「每次 unary 调用 resolve 成 RemoteResult、不为载体问题 reject」，但**它是本仓自己的 wire 契约**，
- * 不是对宿主模块的 import。
+ * 构建约束：本文件零运行时依赖、无 import；浏览器半把整个文件 inline 进 bundle。
+ * 信封 {ok:true,value} / {ok:false,error:{code,message,details?}} 也是两半的共同契约。
  */
 /**
  * 插件专属前缀。
@@ -22,15 +13,18 @@
  * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
  */
 export declare const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 六个段名（相对前缀）。2026-10-17 批量重构：写动词从「一条一段」收成**一段 `/apply`**——
- *  一次 HTTP 带一组 id、逐条回结果；单条就是长度为 1 的批量，仓里不再留第二条执行路径。
- *  - `GET /list`：**对账并读**清单（`session-trash/` 里的目录是准）。
- *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链）——客户端探测用它，不用一次全表读。
- *  - `POST /detail`：单条详情（用 POST 表达一个读：判据就写在 `src/api/route-table.ts` 那一行的上方）。
+/** 九个段名（相对前缀）。写动作统一走一段 `/apply`：一次 HTTP 带一组 id、逐条回结果；
+ *  单条就是长度为 1 的批量，仓里不留第二条执行路径。
+ *  - `GET /list`：对账并读清单（`session-trash/` 里的目录是准）。
+ *  - `GET /ping`：最便宜的在/不在（不碰清册、不碰盘、不进链），供客户端探测。
+ *  - `POST /detail`：单条详情（用 POST 表达一个读，判据在 `src/api/route-table.ts`）。
  *  - `POST /apply`：批量执行一个动作（`delete` / `restore` / `purge` / `count` / `orphan-clean`），逐条回 `ApplyOutcome`。
- *  - `POST /empty`：清空回收站（聚合回执，**不**按条回）。
- *  - `GET /orphans`：无主子会话的扫描报告（纯读，2026-10-19）。**清理不在这里**——它是 `/apply` 的
- *    第五个动作，这一段只负责"有多少、在哪、多大"。 */
+ *  - `POST /empty`：清空回收站（聚合回执，不按条回）。
+ *  - `GET /orphans`：无主子会话的扫描报告（纯读）。清理是 `/apply` 的第五个动作，
+ *    这一段只负责"有多少、在哪、多大"。
+ *  - `GET /attachment`：附件原始字节（全仓唯一的二进制响应段；失败仍回 JSON 信封）。
+ *  - `GET /attachment-orphans`：无引用图片对象的扫描报告（纯读；数量/字节 + 供预览的对象清单）。
+ *  - `POST /attachment-clean`：清掉报告那一刻无引用的图片对象（聚合回执 `AttachmentCleanupWire`）。 */
 export declare const ROUTES: {
     readonly list: "/list";
     /** 通道的"在不在"专用：没有入参、没有副作用、没有磁盘读。 */
@@ -43,9 +37,17 @@ export declare const ROUTES: {
     readonly empty: "/empty";
     /** 纯读：扫描回收站之外的无主子会话（父已不在语料/清册）。 */
     readonly orphans: "/orphans";
+    /** 附件字节（图片/普通文件）：全仓唯一的二进制响应段，读的是宿主附件库。 */
+    readonly attachment: "/attachment";
+    /** 纯读：扫全部引用源与附件库 `objects`，报无引用图片的数量、字节与预览清单。 */
+    readonly attachmentOrphans: "/attachment-orphans";
+    /** 聚合清理：只删 `objects` 下无引用的图片，回 `AttachmentCleanupWire`。 */
+    readonly attachmentClean: "/attachment-clean";
 };
 /** `/apply` 的五个动作。id 的含义随动作走：`delete`/`count`/`orphan-clean` 是**宿主会话 id**
- *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。 */
+ *  （前两个还没进回收站，第三个压根没有回收站行），`restore`/`purge` 是**回收站条目 id**。
+ *  两域都是 string（线上形状）；这里不引入品牌类型——错域不靠类型拦，交给各动词在运行期按自己的
+ *  语义处理，批处理不猜格式。 */
 export type ApplyAction = 'delete' | 'restore' | 'purge' | 'count' | 'orphan-clean';
 /** 每个动作的成功值：`count` 是一个数（拿不到就是 0，界面上那半句整句不出现）；
  *  `delete`/`restore` 是回收站那一行（`null` = 这一条已被**同批前一条**带走，幂等 no-op）；
@@ -112,12 +114,25 @@ export interface TrashRowWire extends TrashEntryWire {
     /** 删除时记下的工作区**已经不在账本里**（宿主的「删除工作区」只删注册、保留日志）。 */
     workspaceMissing?: boolean;
 }
-/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。 */
+/** 单条详情里的一条附件读数（`trash/attachments.ts` 的 `attachmentsInContent` 产出、详情投影上线）。
+ *  `attachmentId` 是宿主附件库的 sha256 键，也是 `GET /attachment` 的唯一寻址依据。 */
+export interface TrashDetailAttachmentWire {
+    attachmentId: string;
+    kind: 'image' | 'file';
+    name?: string;
+    mediaType?: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+}
+/** 单条详情里的一条消息（`trash/detail.ts` 读出来的那一份）。
+ *  `attachments` 必填：没有附件就是空数组（界面上"这一条带没带附件"不靠字段缺席判断）。 */
 export interface TrashDetailMessageWire {
     role: 'user' | 'assistant';
     time: number;
     text: string;
     truncated: boolean;
+    attachments: TrashDetailAttachmentWire[];
 }
 /** 回收站单条详情的线上形状（`POST /detail`）。 */
 export interface TrashDetailWire {
@@ -137,10 +152,33 @@ export interface TrashDetailWire {
     messages: TrashDetailMessageWire[];
     omittedByPayloadCap: number;
 }
-/** 清空回收站的回执（与旧 `purge` 同形）。 */
+/** 一次永久删除顺带、或一次孤儿附件清理的附件读数。`skipped` 有值 = 这一轮**部分或整体没清**：
+ *  有候选日志或剩余引用源读不出（原因上屏）。此时 `removed` 仍可能 > 0——损坏的只是某一组候选，
+ *  其余照常清；跳过不是失败：`failed` 是逐文件真出错的那几件。 */
+export interface AttachmentCleanupWire {
+    removed: number;
+    freedBytes: number;
+    failed: number;
+    skipped?: string;
+}
+/** 孤儿附件报告里的一条：内容哈希 + 实测字节。没有原始文件名（附件库只存内容）。 */
+export interface AttachmentOrphanItemWire {
+    attachmentId: string;
+    bytes: number;
+}
+/** 孤儿附件报告（`GET /attachment-orphans`）：数量、总字节与对象清单。
+ *  清单只带 id/bytes（不含路径/文件名），供设置页预览缩略图，最多 200 条；数量与字节按全量算。
+ *  读不出任何一处引用源时**不返回这一形状**，而是 `io` 失败——不拿 0 冒充"没有孤儿"。 */
+export interface AttachmentOrphanReportWire {
+    count: number;
+    totalBytes: number;
+    items: AttachmentOrphanItemWire[];
+}
+/** 清空回收站的聚合回执。`attachments` 缺席 = 这一版/这一轮没有附件清理读数（不拿零冒充"清过"）。 */
 export interface PurgeStatsWire {
     removed: number;
     freedBytes: number;
+    attachments?: AttachmentCleanupWire;
 }
 /** 无主子会话扫描里**一个项目目录**的汇总（界面上那条"哪一家还剩多少"的读数）。 */
 export interface OrphanProjectGroupWire {
@@ -157,16 +195,22 @@ export interface OrphanReportWire {
     missingParents: number;
     groups: readonly OrphanProjectGroupWire[];
 }
-/** 清理一组无主子会话的回执（与 {@link PurgeStatsWire} 同形，但计的是"删掉的会话目录"）。 */
+/** 清理一组无主子会话的回执（与 {@link PurgeStatsWire} 同形，但计的是"删掉的会话目录"）。
+ *  `attachments` 的口径与 purge 相同。 */
 export interface OrphanCleanStatsWire {
     removed: number;
     freedBytes: number;
+    attachments?: AttachmentCleanupWire;
 }
-/** 请求体字段名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。 */
+/** 请求参数名：浏览器半发、Node 半读，同名同义（`empty` 没有入参）。
+ *  附件段是 **query 参数**（GET 二进制响应，没有请求体）。 */
 export declare const PARAMS: {
     readonly entryId: "entryId";
     readonly action: "action";
     readonly ids: "ids";
+    readonly attachmentId: "id";
+    readonly attachmentKind: "kind";
+    readonly attachmentName: "name";
 };
 /**
  * 失败信封的**线上形状**（本文件）：`code` 是判别依据、`message` 是上屏原文、

package/lib/types/trash/attachments.d.ts

@@ -0,0 +1,85 @@
+import type { FsPort } from '../ports/fs-port.js';
+import { type AttachmentCleanupWire } from '../shared/wire.js';
+export interface ImageRef {
+    kind: 'image';
+    id: string;
+    mediaType?: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    name?: string;
+}
+export interface FileRef {
+    kind: 'file';
+    id: string;
+    name: string;
+    bytes: number;
+}
+export type AttachmentRef = ImageRef | FileRef;
+export declare function isAttachmentId(value: unknown): value is string;
+/** `statFile` / `readFile` / `sizeOfDir` 里只有 ENOENT 能当"不在"；权限、盘挂、I/O 错误都必须露成读不出。 */
+export declare function isMissing(error: unknown): boolean;
+/** 合法附件 ID → 宿主附件库里的绝对路径。`name` 不参与拼接。 */
+export declare function attachmentPathOf(home: string, kind: 'image' | 'file', id: string): string;
+/** 一条消息的 `content[]` 里的附件块；畸形 id / 非附件段一律跳过。 */
+export declare function attachmentsInContent(content: unknown): AttachmentRef[];
+export interface AttachmentReadDeps {
+    fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath'>;
+    home: string;
+}
+export interface AttachmentRemovalDeps extends AttachmentReadDeps {
+    fs: Pick<FsPort, 'exists' | 'listFiles' | 'listDirs' | 'readFile' | 'statFile' | 'realpath' | 'removeFile'>;
+}
+/** 一个会话目录里的图片引用；`unreadable` 有值 = 这一组不可知（调用方按"跳过它"处理）。
+ *
+ *  **没有规范 zstd 日志 ≠ 没有引用**：明文日志、别的版本/布局、以及子目录都可能藏着引用。
+ *  **有规范日志但目录里还有子目录也不够**：日志只覆盖本目录，子目录里的引用读它看不见——
+ *  同样按不可读处理（宁可留下对象等维护卡兜底，不冒"没引用"）。
+ *  **规范日志旁的文件也要过关**：老一代规范日志可以并存（新代包含旧代）；0 字节临时日志是
+ *  写盘未完成的空产物，也没有引用。非空临时日志、明文日志或其他任何文件仍按不可读处理（fail closed）。
+ */
+export declare function imageIdsOfDir(deps: AttachmentReadDeps, dir: string): Promise<{
+    ids: Set<string>;
+    unreadable?: string;
+}>;
+interface PlannedImageRemoval {
+    id: string;
+    path: string;
+    bytes: number;
+}
+export interface ImageRemovalPlan {
+    entries: readonly PlannedImageRemoval[];
+    bytes: number;
+    skipped?: string;
+}
+/**
+ * 独占计划：候选 = 本次被删会话日志里的图片 id；剩余引用 = 活动会话 + 全部未删 `session-trash`
+ * 目录 + storages/cache。
+ * 剩余引用源读不出 ⇒ 整体跳过；候选日志读不出 / 附件对象 stat 失败 ⇒ 只跳过那一部分，其余照常。
+ */
+export declare function planImageAttachmentRemoval(deps: AttachmentReadDeps, removedDirs: readonly string[]): Promise<ImageRemovalPlan>;
+/**
+ * 逐文件删；ENOENT 由端口的 `force` 吞掉；其他错误计数并继续。
+ *
+ * 删除动作只认「`home` + `id` 自己推导出来的那一条路径」：计划是数据，手搭的/被改过的条目
+ * 只要路径与推导不一致就拒绝（计数为失败，不删），源文件因此没有删除入口。
+ */
+export declare function executeImageAttachmentRemoval(deps: AttachmentRemovalDeps, plan: ImageRemovalPlan): Promise<{
+    removed: number;
+    freedBytes: number;
+    failed: number;
+}>;
+/**
+ * 扫「当前没有任何引用源引用」的图片对象。
+ *
+ * 引用侧与删除计划共用同一条判据：活动会话 + 全部 `session-trash` 目录 + `storages/cache` JSON。
+ * 任何一处读不出 ⇒ 整份报告跳过（fail closed），绝不把"读不出"折成"没有引用"。
+ * 候选侧只认 `attachments/v1/objects` 下 `<2 hex>/<64 hex>` 这一种真实形状：`file-objects` /
+ * `tmp` / `v2` / `cache` 与非规范名字一律不进候选——清理只处理 `.dsh` 内的图片副本。
+ *
+ * 对象列表或 stat 读不出同样整份跳过：报告宁可失败，也不给一份"少算了一些"的清理计划。
+ */
+export declare function scanOrphanImageAttachments(deps: AttachmentReadDeps): Promise<ImageRemovalPlan>;
+/** 清掉扫描那一刻无引用的图片对象；扫描跳过 ⇒ 零删，并原样带回跳过的原因。 */
+export declare function cleanOrphanImageAttachments(deps: AttachmentRemovalDeps): Promise<AttachmentCleanupWire>;
+export {};

package/lib/types/trash/detail.d.ts

@@ -1,20 +1,40 @@
-import type { TrashLedger } from './ledger.js';
+/**
+ * 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（用例见 `tests/trash-detail.test.ts`）。
+ *
+ * 三层里的策略层——编解码在 `src/log/*`，这里只回答"给谁看、给多少、算不算失败"。
+ *
+ * 三条硬口径，都不是口味：
+ * ① **寻址只认清册（raw 索引）**：`entryId` 先在对账之外的 raw 索引里查，目录一律由 `trashDirOf(record.id, home)` 推
+ *    ⇒ 外部输入进不了文件系统寻址（不给"传个路径就读任意目录"留缝）。
+ * ② **正文只认 `source.kind === "user"`**：`user/message` 里绝大多数是宿主注入的上下文
+ *    （本机实测一条会话：真实提问 21 条、注入 241 条），不过滤就被淹掉；注入条数照样上线
+ *    （`injectedCount`），让"为什么少了这么多条"能与页面上的数字对账。
+ * ③ **两个闸是载荷闸，不是读盘闸**：每条 3 000 字符、累计 50 万字符（CJK 最坏 ≈ 1.5 MB UTF-8）。
+ *    本机存量一条都触发不了（量级随盘上会话数摆动，不在这里钉数）⇒ 它们是防异常
+ *    膨胀的；**不设"文件太大就拒绝"**，那种阈值只会把真读得出来的正文挡在外面。
+ *
+ * 计数与正文**同源过滤、各过各的闸**：`user/message` 先要求 `source.kind === 'user'`，两类都过"空文本**且**
+ * 无附件"过滤；`userMessageCount` / `assistantMessageCount` 数的是通过过滤的条数，**不受载荷闸影响**。正文再受
+ * 单条/累计两个闸：单条超限截断并把那一条标成 `truncated`，累计到上限后剩下的整条不再收、只累进
+ * `omittedByPayloadCap`——所以计数可以大于正文条数，详情里两件事分开说。
+ * 附件随消息一起收（`attachmentsInContent`），也有两个闸：每条 20、总量 200；超出的**静默丢**，
+ * 不累进 `omittedByPayloadCap`——那个计数说的是"整条正文没进来"，拿它兼报少了几张附件会让两个数都对不上。
+ */
+import { type TrashEntry } from './entry.js';
 import type { FsPort } from '../ports/fs-port.js';
-import type { TrashDetailMessageWire, TrashDetailWire } from '../shared/wire.js';
+import type { TrashDetailWire } from '../shared/wire.js';
 /** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
 export declare const PER_MESSAGE_CHAR_CAP = 3000;
 /** 一次回信的正文总量上限（字符）。 */
 export declare const TOTAL_CHAR_CAP = 500000;
-/** 详情正文里的一条消息 / 整份详情：**线上形状的家在 `shared/wire.ts`**（ADR-0003）——
- *  Node 半产出它，浏览器半按同一份类型消费，这里只留旧名做别名。 */
-export type TrashDetailMessage = TrashDetailMessageWire;
 export type TrashDetail = TrashDetailWire;
 export type DetailDeps = {
     /** 详情自己直接要的三件（判目录在不在、挑日志、读日志）。对账不在这条路上，所以不需要 `listDirs`。 */
     fs: Pick<FsPort, 'exists' | 'listFiles' | 'readFile'>;
-    /** 详情只读清册的 **raw 面**：`/detail` 声明为 pure，读一次不能顺手对账——对账会写清册行，那是写动作，
-     *  必须排在到达序链上。代价是有意的：只有目录、清册还没这一行的手工搬入条目读不到（`/list` 对账后可见）。 */
-    ledger: Pick<TrashLedger, 'raw'>;
+    /** 路由交来的清册 **raw 行**：`/detail` 声明为 pure，读一次不能顺手对账——对账会写清册行，那是写动作，
+     *  必须排在到达序链上。读面由路由记录选好（`read: 'raw'`），这里只消费行，不再自己挑 `list()` / `raw()`。
+     *  代价是有意的：只有目录、清册还没这一行的手工搬入条目读不到（`/list` 对账后可见）。 */
+    rows: () => Promise<readonly TrashEntry[]>;
     home: string;
 };
 /** 两个载荷闸（可调是为把策略单独验穿；生产走的就是这两个默认值，用例里钉着）。 */

package/lib/types/trash/entry.d.ts

@@ -8,8 +8,8 @@ export interface TrashEntry {
     /** 删除时它所属的工作区；**空串 = 删除时就没有账目**（「未分组」的会话，宿主的"删除工作区"会造出这种），
      *  恢复时据此跳过 `attach`。 */
     workspaceId: string;
-    /** 删除**之前**的归档态，**只作事实记录**：2026-10-21 起删除不归档、恢复也不按它还原可见性。
-     *  旧清单迁移只用它区分"删除时是我们归档的"（false 且当前仍归档）与"用户删前自己归档的"（true，保持归档）。 */
+    /** 删除前的归档态，只作事实记录：删除不再改变归档，恢复也不按它还原可见性。
+     *  旧条目迁移用它区分“删除时被我们归档的”（false 且当前仍归档）与“用户删前自己归档的”（true）。 */
     wasArchived: boolean;
     deletedAt: number;
     /** 删除时**尽力**取的会话标题（来源：宿主 projection cache 服务；底层是
@@ -19,7 +19,7 @@ export interface TrashEntry {
     sizeBytes: number;
     /** **组语义**：这一条是跟着父一起进回收站的子会话 ⇒ 记父那一行的 `id`。
      *  缺席 = 这一行是父（或它自己就是被单独删掉的）。清单据此把孩子折进父行、不单独列。
-     *  老代留底 / 清册被清后由目录重建出来的行**没有这个字段**（文件侧没有它的副本，与
+     *  清册被清后由目录重建出来的行没有这个字段（文件侧没有它的副本，与
      *  `workspaceId`/`wasArchived`/`title` 同一类降级），那一趟它们会各占一行——那是"分组信息随清册一起没了"
      *  的如实结果，不假装知道（CONTEXT.md 的「无主子会话」条）。 */
     parentEntryId?: string;

package/lib/types/trash/groups.d.ts

@@ -1,17 +1,10 @@
 /**
- * **组语义的唯一家**（ADR-0001）：回收站里「这一组有谁」以及「哪些行在清单里露面」。
+ * 组语义的唯一家（ADR-0001）：回收站里「这一组有谁」以及「哪些行在清单里露面」。
  *
- * 此前这条关系在四个地方各算一遍，而且已经算出两种答案：
- * `assembleTrashRows` 与 `restoreSession` 都认为「父自己也是孩子时，它接不住孩子」，
- * 而 `purgeTrash` 的 `id === x || parentEntryId === x` 不认这条 ⇒ 嵌套组上它会连带删掉不属于这一组的孙代
- * （不可恢复）。判据原文只在这里写一次：
+ * 接得住孩子的只有组根——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
+ * 孩子必须自己占一行，否则它的字节会被头部合计数两遍，而它自己既看不见也清不掉。
  *
- * **接得住孩子的只有组根**——自己不记 `parentEntryId` 的那一行。父行不在、或父行自己也是孩子时，
- * 孩子必须自己占一行，否则它的字节会被头部合计数两遍（而它自己既看不见也清不掉）。
- *
- * 三个函数都是**纯函数**、都吃一份快照：`/apply` 那条路会在同一批里多次重问；批量层持有一份
- * 会收缩的当前视图（`verbs/batch-carried.ts`），收缩时机归调用方——groups module 不持有可变状态，
- * 也就没有"这份快照谁负责更新"的第二套契约。
+ * 三个函数都是纯函数、都吃一份快照；收缩时机归调用方，本模块不持有可变状态。
  */
 import type { TrashEntry } from './entry.js';
 /** 一条露面的组根，连同它接住的孩子（顺序与清册一致）。 */

package/lib/types/trash/storage-manifest.d.ts

@@ -4,7 +4,7 @@ import { type ManifestPort } from './manifest.js';
  * 清单的真实绑定：官方 storage domain → `ManifestPort`（`StorageDomainLike` 在动词层保持一种读法）。
  * 域**懒开**且成功句柄只开一次（`apply` 是同步的，而 `open()` 是异步的），并挂一条 `ctx.effect` 清理：
  * 插件卸载时关掉句柄并把 `close()` 的落地交回框架（句柄归调用方所有，这是 `open()` 的 JSDoc 明写的契约；
- * 2026-10-17 起不再 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
+ * 不能 `void` 走掉——没关严的句柄会让下一份同名域撞 `already-open`）。
  *
  * **失败不缓存**：`open()` 被拒是瞬态（域被别的持有者占着、装载竞态），把第一次的 rejected promise
  * 缓存起来等于"这个会话永远删不掉"——下一次读会重新走 `open()`，成功才落下活句柄。

package/lib/types/verbs/delete-session.d.ts

@@ -1,5 +1,5 @@
 import { type TrashEntry } from '../trash/entry.js';
-import type { DeleteDeps } from '../deps.js';
+import type { DeleteSessionDeps } from '../deps.js';
 export interface DeleteResult {
     readonly entry: TrashEntry;
     /** 这一次真的搬进回收站的成员（父 + 盘上存在的孩子）；批量层用它建同批已带走集。 */
@@ -22,4 +22,4 @@ export interface DeleteResult {
  * 组语义归 `trash/groups.ts`）。
  * 结果带回这次真的搬走的整组（`movedSessionIds`）——它是动词交回的内部数据，不再靠回调借用动词的手。
  */
-export declare function deleteSession(deps: DeleteDeps): (sessionId: string) => Promise<DeleteResult>;
+export declare function deleteSession(deps: DeleteSessionDeps): (sessionId: string) => Promise<DeleteResult>;

package/lib/types/verbs/errors.d.ts

@@ -9,6 +9,8 @@ export interface VerbError extends Error {
     cause?: unknown;
 }
 export declare function verbError(code: VerbCode, message: string, cause?: unknown, details?: Record<string, unknown>): VerbError;
+/** `trash-empty` 的原文：有具体条目就点名那个 id，拿不到时只报通用那句。 */
+export declare function trashEmpty(entryId?: string): VerbError;
 /** 路由自检用的失败：带 HTTP 状态语义，**不**冒充五个动词码。 */
 export declare function routeError(code: RouteCode, httpStatus: number, message: string): VerbError & {
     httpStatus: number;

package/lib/types/verbs/live-admission.d.ts

@@ -1,12 +1,9 @@
 /**
- * 活体准入：一次删除 / 永久删除 / 孤儿清理之前，逐个问「这个会话在宿主内存里 attach 着吗」——
- * 任一个在跑就整组拒绝、零副作用（词表见 CONTEXT.md 的「活体」条；裁决见 ADR-0008）。
+ * 活体准入：删除 / 永久删除 / 孤儿清理之前，逐个问会话是否在宿主内存里 attach 着；
+ * 任一在跑就整组拒绝、零副作用（ADR-0008）。
  *
- * 为什么单独一个 module：删除的逐个成员与永久删除计划的 targets + 盘上后代，此前各手写一遍同一条
- * 循环、同一句原文。两处只要有一处改了措辞或漏查一个 id，客户端拿到的就是两种「还在跑」。
- *
- * 边界：**什么时候查归调用方**。永久删除的准入仍住在计划里、在任何写之前（ADR-0006：计划就是执行前的闸）；
- * 这个 module 只拥有「查什么、怎么判、怎么说」。
+ * 边界：什么时候查归调用方——永久删除的准入在计划里、任何写之前（ADR-0006）；
+ * 本模块只拥有「查什么、怎么判、怎么说」。
  */
 import type { HostIdentityPort } from '../ports/host-port.js';
 /** 逐个问，任一在跑就抛 `live`。名单的挑选（哪些成员算这一组）归调用方，这里只按传入顺序问完。 */

package/lib/types/verbs/member-journal.d.ts

@@ -16,7 +16,7 @@ export interface JournalUndo {
 export interface JournalStep {
     /** 稳定的领域键，给 `restored(key)` 用。 */
     readonly key: JournalStepKey;
-    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼——与迁移前那 22 处 `rollbackReason` 的措辞同形。 */
+    /** 这一步在做什么。失败原文按「`<label>：<原错误>`」拼。 */
     readonly label: string;
     /** 做这一步。抛什么都由 journal 折成 `sessiondelete/io`（除非它自己已经是一个动词码）。 */
     run(): Promise<void>;
@@ -39,8 +39,7 @@ export declare function attempt(label: string, run: () => Promise<unknown>): Pro
 export declare function stepUndo(label: string, run: () => Promise<unknown>): Promise<StepUndo>;
 /**
  * **组级回滚**：把已经做成的成员按相反顺序退回；某一步退不干净时把失败并进原错误的
- * `details.rollbackFailures`，绝不让原错误独走（2026-10-19 `f2a7757`；那些失败句子的合并与措辞住
- * `src/verbs/errors.ts`，这里只是唯一的调用方）。删除与恢复两个按组走的动词共用这一处，
- * "相反顺序 + 失败合并"不再各写一遍。
+ * `details.rollbackFailures`，绝不让原错误独走。那些失败句子的合并与措辞住 `src/verbs/errors.ts`；
+ * 删除与恢复两个按组走的动词共用这一处。
  */
 export declare function rollbackJournals(journals: readonly Journal[], error: unknown): Promise<never>;

package/lib/types/verbs/member-presence.d.ts

@@ -1,42 +1,23 @@
 /**
  * 成员离场 / 归位的通告协议：摘活体、三态判断、成对事件只在这里做。
  *
- * 为什么要有它：delete（成功与回滚）/ restore 回滚 / purge（两个分支）/ orphan-clean
- * 六处调用曾经各写一遍
- * `evictLive → !== 'unknown' → announceRemoved`；删除回滚还要自己拼目录与账本两个布尔
- * 才发 `announceRestored`。
- * 这条协议说错一次就是客户端留着假行、或删掉真行，所以只留一个家。
+ * 调用方包括 delete、restore 回滚、purge、orphan-clean；协议说错一次就是客户端留假行或删真行。
  *
  * 边界：
- * - 批量恢复自己发起的那次通告（`announceRestored(ids)`）归 `verbs/batch.ts`（ADR-0002）：同一个方法、
- *   同一份预取，只是调用方是那一批的主人。这里只判单成员事实。
- * - 本模块不决定哪个键算归位：动词在 `tail.onUndone` 里把 `restored(key)` 读成事实再交进来，真值表住这里；
- *   `run` / `undo` 之后补一条通告的**形状**由 {@link withPresenceTail} 拥有。
- * - 本模块用到的三条（`evictLive` / `announceRemoved` / `announceRestored`）按契约不抛（evictLive 三态、
- *   announce* 内部吞异常），这里不再叠 catch。
+ * - 批量恢复的编排归 `verbs/batch.ts`（ADR-0002）；本模块只实现 `announceRestored(ids)`（ADR-0019）。
+ * - 哪个键算归位由动词在 `tail.onUndone` 里读成事实再交进来，真值表住这里；
+ *   `run`/`undo` 之后补通告的形状由 {@link withPresenceTail} 拥有。
+ * - `evictLive`/`announce*` 按契约不抛，这里不再叠 catch。
  */
 import type { HostPresencePort } from '../ports/host-port.js';
+import type { PresenceCapability } from '../ports/presence-port.js';
 import type { Journal, JournalUndo } from './member-journal.js';
 /** 本模块实际用到的三条宿主能力。`Pick` 此刻覆盖 `HostPresencePort` 的三条方法，仍留着它当闸：
- *  将来端口多出第四条时，这里不会被动跟着变宽——这里是单成员协议，批量恢复由 `verbs/batch.ts`
- *  自己发起，不该因为共用同一颗 adapter 就在类型上声明依赖。 */
+ *  将来端口多出第四条时，这里不会被动跟着变宽——能力面只暴露这三条，批量通告的编排归 `verbs/batch.ts`。 */
 export type MemberPresenceHost = Pick<HostPresencePort, 'evictLive' | 'announceRemoved' | 'announceRestored'>;
-export interface MemberBackFacts {
-    /** 目录搬回原处了吗。 */
-    readonly diskBack: boolean;
-    /** 账本挂回去了吗（本来没有账目时算 true）。 */
-    readonly workspaceBack: boolean;
-}
-export interface MemberPresence {
-    /** 成员已经不在宿主可见列表：摘活体；三态不是 unknown 时发 removed。
-     *  `backInTrash: false` 表示目录没退回回收站（恢复回滚失败），此时什么都不做。 */
-    memberGone(sessionId: string, facts?: {
-        readonly backInTrash?: boolean;
-    }): Promise<void>;
-    /** 成员已经回到原来的可见状态：目录与账本两件写都回去才发 added。 */
-    memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
-}
-export declare function createMemberPresence(host: MemberPresenceHost): MemberPresence;
+/** 本仓的在场能力实现：端口形状住 `src/ports/presence-port.ts`，这里只做三态与真值表。
+ *  `announceRestored` 直接交宿主那一手：能力面与宿主面同名同签名，再包一层只会多一个转调。 */
+export declare function createMemberPresence(host: MemberPresenceHost): PresenceCapability;
 /** 一次 undo 之后要发哪一条通告：`leave` = 成员已不在可见面，`return` = 已回到原可见状态。 */
 export type PresenceAnnounce = {
     readonly kind: 'leave';
@@ -55,13 +36,9 @@ export interface PresenceTail {
     onUndone(undo: JournalUndo): PresenceAnnounce;
 }
 /**
- * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场、undo 之后按事实归位或离场。
- *
- * 为什么是个工厂：删除与恢复此前各手拼一个匿名 journal，形状逐字相同（`journal.run` 加上
- * `presence.memberGone`／`journal.undo` 加上 `presence.memberBack`），只差键 → 事实的映射。
- * 两处各写一遍，就是「补在哪一拍」这条顺序又有第二个家。
+ * 给一次成员移动的 journal 补上「在场那条尾巴」：run 完全成功之后离场，undo 之后按事实归位或离场。
  *
- * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表仍归 `createMemberPresence`；
- * 这里只把事实原样递过去，不替它判断。
+ * 边界：`memberGone` 的 `backInTrash:false` 早退与 `memberBack` 的两件齐备真值表归 `createMemberPresence`；
+ * 这里只把事实原样递过去。
  */
-export declare function withPresenceTail(presence: MemberPresence, journal: Journal, tail: PresenceTail): Journal;
+export declare function withPresenceTail(presence: PresenceCapability, journal: Journal, tail: PresenceTail): Journal;

package/lib/types/verbs/orphan-subagents.d.ts

@@ -1,7 +1,7 @@
 import { type SessionIdentity } from '../ports/host-port.js';
 import type { TrashEntry } from '../trash/entry.js';
 import type { OrphanCleanStatsWire, OrphanReportWire } from '../shared/wire.js';
-import type { CoreDeps } from '../deps.js';
+import type { CoreDeps, RemovalDeps } from '../deps.js';
 /** 组里一个人的盘上身份（字节是**扫描那一刻**量的，清理时按目录重量一次，不拿这份快照冒充准数）。 */
 export interface OrphanMember {
     readonly sessionId: string;
@@ -32,17 +32,17 @@ interface RawGroup {
  * 归堆与去重**两边都去 `session-` 前缀**：同一个父在两代宿主里写法不同（见 `bareSessionId` 的来历）。
  */
 export declare function orphanGroupsOf(corpus: readonly SessionIdentity[], trashSessionIds: readonly string[]): RawGroup[];
-/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。清册默认读
- *   `ledger.raw()`；写路径（`orphan-clean`）可以在调它之前先 `ledger.list()` 对账，并把交回的行递进来，
- *  免得同一份索引再读一遍——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成"父没了"
- *  直接删盘。
+/** **本函数是纯扫描，不对账、不写清册行**（`/orphans` 声明为 pure，一次扫描不能顺手写行）。
+ *  清册行由调用方选好再交进来：`/orphans` 交 `read.rows()`（raw 索引），`orphan-clean` 交
+ *  `ledger.list()`（对账后的行）——否则刚被人手工搬进 `session-trash/` 的父目录还没有行，会被当成
+ *  "父没了"直接删盘。扫描不再自己回落到 `ledger.raw()`：读面归属住路由记录（ADR-0004 / ADR-0012）。
  *
  *  `listSessions()` 回 `{ available: false }` 时**必须抛**：那是宿主的会话语料服务没挂，不是"这个家没有孤儿"。
  *  拿缺席当空语料 ⇒ 报告说"零条孤儿"、界面上一句"没有要清理的"，而盘上真有几百 MB——那是假话，
  *  所以这里按 `io` 响亮失败（AGENTS.md：`available: false` 意味着服务缺席，扫描方不许冒充读数）。 */
 export declare function loadOrphanGroups(deps: CoreDeps, 
-/** 调用方已对账过的清册行（`ledger.list()`）；缺席则读 `ledger.raw()`。 */
-trash?: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
+/** 调用方选好并交来的清册行：`/orphans` 交 `read.rows()`，`orphan-clean` 交 `ledger.list()`。 */
+trash: readonly TrashEntry[]): Promise<readonly OrphanGroup[]>;
 /** 把一组组收成那份报告：根清单 + 闭包总数/总字节 + 失踪父的**去重计数** + 按项目目录的分摊。
  *  `groups` 按字节从多到少排（界面上"哪家还剩得最多"要看第一行）。 */
 export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanReportWire;
@@ -58,6 +58,7 @@ export declare function reportOrphans(groups: readonly OrphanGroup[]): OrphanRep
  * - `unarchive` 对未归档的会话是官方幂等 no-op（`registry.unarchiveSession`），所以这里不需要那次
  *   `wasArchived` 读——这里没有"还原到删除前"的义务。
  * - 摘账本只在账本真记着它时做（`workspaceOf` 未命中 = 本来就是「未分组」，不是故障）。
+ * - 独占图片的剩余引用源由附件域自己扫：活动会话 + 全部 session-trash + storages/cache。
  */
-export declare function cleanOrphanGroup(deps: CoreDeps, group: OrphanGroup): Promise<OrphanCleanStatsWire>;
+export declare function cleanOrphanGroup(deps: RemovalDeps, group: OrphanGroup): Promise<OrphanCleanStatsWire>;
 export {};

package/lib/types/verbs/permanent-removal.d.ts

@@ -1,11 +1,12 @@
 /**
- * 永久删除的**测量、计划与执行**：一次永久删除（`/list` 的只读读数或 purge / orphan-clean 的删除计划）
- * 之前要记下的事实（目录、字节、账本归属），以及拿到计划之后按它动盘的那一步。计划函数**只读**——
- * 写不写由执行器决定，但活体准入在这里就做掉，调用方拿到计划才允许动盘。
+ * 永久删除的测量、计划与执行：先记录目录/字节/账本归属，再按计划动盘。
+ * 计划函数只读；活体准入在计划阶段、任何写之前完成。
  */
 import { type TrashEntry } from '../trash/entry.js';
 import type { TrashGroupView } from '../trash/groups.js';
-import type { CoreDeps } from '../deps.js';
+import { type ImageRemovalPlan } from '../trash/attachments.js';
+import type { CoreDeps, RemovalDeps } from '../deps.js';
+import { type AttachmentCleanupWire } from '../shared/wire.js';
 export interface MeasuredMemberDir {
     readonly dir: string;
     readonly bytes: number;
@@ -24,13 +25,6 @@ export declare function measureMemberDir(deps: CoreDeps, member: {
     readonly sessionId: string;
     readonly projectDir: string;
 }): Promise<MeasuredMemberDir | undefined>;
-/** 把一组成员折成"删之前要记下的计划"；目录不在的成员跳过（记录与盘不一致是那条成员自己的事）。
- *  `purge` 的盘上后代、`orphan-clean` 的整组与 `/list` 的盘上残留都走这一处，别再各写一遍
- *  measure + workspaceOf。 */
-export declare function planMemberRemovals(deps: CoreDeps, members: readonly {
-    readonly sessionId: string;
-    readonly projectDir: string;
-}[]): Promise<PlannedMemberRemoval[]>;
 /** 回收站里的一条要删的行：目录、在不在、实测字节（缺席 = 0）。purge 与 `/list` 都由它量。 */
 export interface PlannedTrashRow {
     readonly entry: TrashEntry;
@@ -66,6 +60,10 @@ export interface RemovalPlan {
     readonly unarchive: readonly string[];
     /** 计划量到的合计；成功回执的 freedBytes 只念它。 */
     readonly bytes: number;
+    /** 这一次要连带清掉的独占图片对象（`trash/attachments.ts` 的域判定；空计划 = 没有可删的、或
+     *  剩余引用源读不出而整体跳过——原因在 `skipped` 里）。附件字节**不进** `bytes`：那是会话目录的
+     *  释放量，附件读数单独走回执的 `attachments`。 */
+    readonly attachments: ImageRemovalPlan;
 }
 /**
  * purge 的删除计划：`targets` 由调用方按组语义（`trash/groups.ts`）选好，这里只量、只筛、只查活体。
@@ -75,6 +73,8 @@ export interface RemovalPlan {
  * - 盘上后代经 `selectStrandedMembers` 选出（一次问全部 targets、排除全部清册 id、bare id 全局只计划一次）。
  * - `members` 只收盘上还有目录的成员（目录缺席没有可删的字节）；`unarchive` = targets + 这些成员：
  *   只摘这一次真要碰的 id。
+ * - `attachments` 由被删目录（targets + 这些成员）里的图片引用与全部剩余引用源算独占；共享的保留、
+ *   剩余引用源读不出就整体跳过（判据住 `trash/attachments.ts`，这里只接线）。
  * - 活体准入在量目录与任何写之前逐个查 targets 与**全部枚举到的**盘上后代；任一在跑就整条拒绝、
  *   零副作用。没有跳过它的开关——计划就是执行前的闸（ADR-0006）。
  * - `sessionQuery` 缺席时端口回 `{ available: false }` ⇒ members 为空、不抛（盘上残留留给 `GET /orphans` 兜底）。
@@ -87,6 +87,8 @@ export declare function planTrashRemoval(deps: CoreDeps, rows: readonly TrashEnt
  * - `unarchive` 覆盖**全部传入成员**（含目录缺席）：orphan-clean 在删目录之前整批摘归档集，
  *   目录缺席的 id 也可能还挂在归档集里；重试时不会再长出一条幽灵 id。
  * - live 准入覆盖**全部传入成员**（含目录缺席）：它们都在这一组的可见面里，任一在跑就整组拒绝。
+ * - `attachments` 的剩余引用源由附件域自己扫（活动会话 + 全部 session-trash + storages/cache），
+ *   共享图片因此保留（判据住 `trash/attachments.ts`）。
  * - 回执由 `kind:'orphan'` 派生：删目录阶段失败时执行器要交回 `{removed, freedBytes, failedSessionId}`。
  */
 export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
@@ -97,18 +99,22 @@ export declare function planOrphanRemoval(deps: CoreDeps, members: readonly {
  * 按计划执行一次永久删除：只写、不再量、不再判活体（计划就是执行前的闸）。回执的字节念计划
  * （`plan.bytes`），执行期不再累加一遍。
  *
- * 顺序（与迁移前的 purge / orphan-clean 一致）：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
- * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）。目录删掉就没有
- * "退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
+ * 顺序：整批摘归档集 → 摘有账本的成员的账本 → 逐条回收站行
+ * （在才删目录 → 摘清册行 → 通告成员离场）→ 逐条盘上成员（删目录 → 通告成员离场）→ 逐条附件对象。
+ * 目录删掉就没有"退回去"这回事，中途失败**不回滚**；已经删掉的由下面的计数器如实交回。
+ *
+ * 附件清理排在**所有会话目录删完之后**：对象只在会话真的没了之后才动；单文件失败只进
+ * `attachments.failed`，不影响（也不回滚）会话删除的回执。
  *
- * 失败形状沿用调用方原来的措辞与结构：
+ * 失败形状：
  * - `kind:'orphan'`（orphan-clean）⇒ `io` + `{removed, freedBytes, failedSessionId}`，不伪装成整组没动；
- * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details。
- * - orphan-clean 的 unarchive / detach 在旧实现里不包装，这里原样抛出（不改变现有错误形状）。
+ * - `kind:'trash'`（purge）⇒ 同一个标签、不带 details；
+ * - orphan-clean 的 unarchive / detach 原样抛出。
  *
  * 通告只经 `member-presence`（摘活体三态 + `api-session/removed`），不在这里另写一份。
  */
-export declare function executeRemoval(deps: CoreDeps, plan: RemovalPlan): Promise<{
+export declare function executeRemoval(deps: RemovalDeps, plan: RemovalPlan): Promise<{
     removed: number;
     freedBytes: number;
+    attachments: AttachmentCleanupWire;
 }>;