@xrn1997/dsh-session-delete 0.3.0 → 0.4.0

package/lib/types/client/undo-toast.d.ts

@@ -1,63 +1,17 @@
 /**
  * 撤销提示（docs/ui-spec.md 状态 ③）：删除成功后一条可撤销的横幅。
  *
- * 为什么是**独立组件 + 模块级通知台**，而不是死在菜单行里：宿主的菜单行随菜单**一起卸载**
- * （真产物 Menu 的注释原文 "the rows unmount with the list"），而提示要在菜单关掉之后还活着。
- * 宿主的官方配方同形——会话行的动作把请求写进一个模块级 store，`shell.overlay` 里的
- * `workspace.row-toast` 读它（asar 原文：`inject("shell.overlay", … id: "workspace.row-toast" …
- * inject: rowToastInjected … }, RowActionToast)`，而
- * `rowToastInjected = () => ({ hooks: { toast: rowToast }, dismissToast, undoArchive: unarchiveSession })`）。
- * 本文件就是那份 store + 那个常驻组件。
- *
- * 状态源走 `store.ts` 的 `createStore`（内部用 React 自带的 `useSyncExternalStore`）——
- * 不引 `@deepseek-ai/dsh-client-store`（它在平台表内，但这里用不着；React 就够，少一条平台依赖）。
+ * 现场与发布住在 `undo-notices.ts`；本文件只做组件，并把通知台与外部恢复座位组合起来。
+ * 为什么组件要独立：宿主的菜单行随菜单**一起卸载**（真产物 Menu 的注释原文
+ * "the rows unmount with the list"），而提示要在菜单关掉之后还活着。宿主的官方配方同形——
+ * 会话行的动作把请求写进一个模块级 store，`shell.overlay` 里的 `workspace.row-toast` 读它。
  */
 import { type Translate } from './copy.js';
-import { type OneShotDeps } from './remote.js';
+import type { OneShotDeps } from './remote.js';
 export type UndoToastDeps = OneShotDeps;
-/**
- * 一次待撤销的事。两形（2026-10-17 起）：单条删除（主语是会话名）／批量删除（主语是条数）。
- * 同一个 Toast 宿主、同一停留时长；撤销动作按形走——单条 `restore`，批量**一次** `applyOutcomes`。
- */
-export type UndoNotice = {
-    /** 每次发布递增：Toast 靠它重挂载，同一段文案连续出现两次也能重新计一次停留。 */
-    seq: number;
-    /** 撤销失败时把原因顶上来：这时不再有「撤销」动作，只剩原文。 */
-    failure?: string;
-} & ({
-    kind: 'one';
-    /** 回收站条目 id——撤销就是拿它去 `restore`。 */
-    entryId: string;
-    /** 删除那一刻的会话名（菜单槽投影的 `displayTitle`；取不到时是空串）。 */
-    title: string;
-} | {
-    kind: 'batch';
-    /** 撤销名单：只收成功支里非 null 的条目 id（「被同批带走」的成员跟着组走，不单列）。 */
-    entryIds: readonly string[];
-    /** 横幅那句的条数 = 那一次成功支的条数（含幂等带走的）——与撤销名单是两个数，各说各的。 */
-    n: number;
-});
-/** 删除成功后发布一条撤销提示（单条）。 */
-export declare function publishUndoNotice(input: {
-    entryId: string;
-    title: string;
-}): void;
-/** 批量删除成功后发布一条撤销提示（2026-10-17）：覆盖上一条，只报这一次移走的条数。 */
-export declare function publishUndoBatchNotice(input: {
-    entryIds: readonly string[];
-    n: number;
-}): void;
-/** 撤销成功后把提示收掉（用户点「撤销」、或横幅自己走完停留时间）。 */
-export declare function clearUndoNotice(): void;
-/** 供组件订阅。 */
-export declare function useUndoNotice(): UndoNotice | null;
-/** 测试专用：现场与 seq 归零，用例之间互不串味。 */
-export declare function resetUndoNotice(): void;
-/** 提示停留时长。**6 秒** 定死在本行（比 Toast 默认的 3 秒长）——`docs/ui-spec.md` §2 状态 ③ 只指到这里，不抄这个数。 */
-export declare const UNDO_HOLD_MS = 6000;
 /**
  * 常驻的撤销提示宿主。挂 `shell.overlay`（框架级浮层；槽位说明原文 "a toast stack or a status
- * pill all belong here"，见 asar 里 `shell.overlay` 的声明）：没有待撤销的事时什么都不渲染。
+ * pill all belong here"）：没有待撤销的事时什么都不渲染。
  */
 export declare function UndoToast({ deps, t }: {
     deps: UndoToastDeps;

package/lib/types/client/use-column-resize.d.ts

@@ -1,26 +1,15 @@
 /**
- * 清单列与详情列之间那根**可拖的宽度把手**（2026-10-15 加，`docs/ui-spec.md` 的「面板与清单」）。
+ * 清单列与详情列之间那根可拖的宽度把手（docs/ui-spec.md 的「面板与清单」）。
  *
- * 三件事住在这里，因为它们互相咬合、分开测各自都不成立：
- * ① **宽度夹在两个界之间**。下限由调用方给（回收站那条的来历写在 `trash-panel.tsx`：真 Chromium
- *    上扫出来的，约束不是"两颗按钮放得下"——它们 `flex:none`，再窄也是文字列缩；而是「删除于 … ·
- *    大小」那一行不再被省略号截断），上限 = 面板宽 − `reserve`。**`reserve` 的数值与来历都住在调用方**
- *    （`DETAIL_RESERVE`，那三件东西怎么加出来的见 `trash-panel.tsx` 该常量的注释与几何用例）：
- *    这一层不复制那份算式——上一版在这里钉过一个"480 ⇒ 900 那档正好回 420"，调用方改到 489 之后
- *    它就成了假数，而 900 那档的真实读数是**清单被夹到 411**（比默认窄 9px，还能往里拖）。
- * ② **夹在"读"的时候也做一次**。窗口变窄不触发任何写入，若只在写入时夹，之前拖出来的超宽
- *    清单会一直留到下次交互 ⇒ `listWidth` 每次渲染都按当前 `panelWidth` 重算。
- * ③ **按下才算在拖**。指针捕获挂在把手元素上（`setPointerCapture`），move 只可能来自这一根把手；
- *    `origin === null` 时 move 直接返回——鼠标扫过不该改布局。抬起不用显式 release：规范里
- *    pointerup/pointercancel 会隐式释放捕获，多写那一行只会引入"指针已不活跃"的抛错面。
- *    **但"结束"不能只挂在把手上**：拖动途中把手会被卸载（面板窄过断点、或清单被读空 ⇒ `split`
- *    翻了），而卸载后的节点收不到任何事件 ⇒ `resizing` 永远挂着：面板根留着 `.sd-resizing`
- *    （关文字选中），下次变宽时把手还带着 `data-dragging` 长回来。所以拖住期间另在 window 上兜
- *    一层 `pointerup`/`pointercancel`（复用同一个 `stop`）。move 仍然只认把手，捕获那套一点没动。
+ * 三件事住在这里：
+ * ① 宽度夹在两个界之间：下限由调用方给，上限 = 面板宽 − reserve。
+ *    reserve 的数值与来历住在调用方（DETAIL_RESERVE），这一层不复制算式。
+ * ② 夹在“读”的时候也做一次：窗口变窄不触发写入，listWidth 每次渲染按当前 panelWidth 重算。
+ * ③ 按下才算在拖：指针捕获挂在把手元素上；拖动途中把手可能卸载，所以 window 上另兜一层
+ *    pointerup/pointercancel 复用 stop；move 仍只认把手。
  *
- * 键盘那条不是装饰：`role="separator"` 可聚焦、←→ 各一格、Home 回默认、End 到上限。
- * 这一代的 `--dsw-focus-ring-color` 是 transparent（宿主自己那份焦点环靠别的属性撑），
- * 所以焦点态的可见性由 `ui.css` 里 `.sd-width-handle:focus-visible::after` 那一条负责。
+ * 键盘：role=separator、←→ 各一格、Home 回默认、End 到上限；焦点态可见性由 ui.css 的
+ * .sd-width-handle:focus-visible::after 负责。
  */
 import { type KeyboardEvent, type PointerEvent } from 'react';
 export interface ColumnResizeArgs {

package/lib/types/client/use-maintenance.d.ts

@@ -0,0 +1,45 @@
+import type { Translate } from './copy.js';
+import { type AttachmentOrphanReportWire, type OrphanReportWire, type SessionDeleteRemote } from './remote.js';
+/** 维护卡只需要这四段：两份报告 + 孤儿会话的批量写 + 孤儿附件的聚合写。 */
+export type MaintenanceDeps = Pick<SessionDeleteRemote, 'scanOrphans' | 'applyOutcomes' | 'scanAttachmentOrphans' | 'cleanAttachmentOrphans'>;
+/** 一段在飞的动作：检查只读，清理会写。状态行靠它分开说「检查中…」与「清理中…」；`null` = 空闲。 */
+export type MaintenancePhase = 'scanning' | 'cleaning';
+export interface Maintenance {
+    readonly orphanReport: OrphanReportWire | null;
+    readonly orphanFailure: string | null;
+    /** 「这一组已经不在」不是失败：单独一条中性提示。 */
+    readonly orphanNotice: string | null;
+    /** 上一趟孤儿会话清理顺带清掉的附件读数（`.dsh` 内独占图片副本）。重查读不出来，和
+     *  `orphanNotice` 一样是过去那一趟的回执；下一次检查 / 清理会被收掉。 */
+    readonly orphanAttachmentNotice: string | null;
+    readonly orphanConfirm: boolean;
+    readonly orphanBusy: boolean;
+    /** 在飞的是检查还是清理；`null` = 空闲。写动作在飞时状态行据此说「清理中…」。 */
+    readonly orphanPhase: MaintenancePhase | null;
+    /** 手动检查（`GET /orphans`）。失败回 `null` + 原文，不折成零条。 */
+    scanOrphans(): Promise<void>;
+    /** 「查看并清理」：先收掉旧提示再开确认框。 */
+    openOrphanPreview(): void;
+    /** `/apply` 的 `orphan-clean`：清完必重查；中性 / 失败 / 部分计数按回执说。 */
+    cleanOrphans(): Promise<void>;
+    setOrphanConfirm(open: boolean): void;
+    readonly attachmentReport: AttachmentOrphanReportWire | null;
+    readonly attachmentFailure: string | null;
+    /** 上一趟清理的回执（已清 / 跳过 / 逐文件失败），重查读不出来。 */
+    readonly attachmentNotice: string | null;
+    readonly attachmentConfirm: boolean;
+    readonly attachmentBusy: boolean;
+    /** 在飞的是检查还是清理；`null` = 空闲。 */
+    readonly attachmentPhase: MaintenancePhase | null;
+    /** 手动检查（`GET /attachment-orphans`）。 */
+    scanAttachmentOrphans(): Promise<void>;
+    /** 「查看并清理」：先收掉旧提示再开确认框。 */
+    openAttachmentPreview(): void;
+    /** `POST /attachment-clean`：清完必重查；`removed` / `failed` / `skipped` 按回执说。 */
+    cleanAttachmentOrphans(): Promise<void>;
+    setAttachmentConfirm(open: boolean): void;
+}
+export declare function useMaintenance({ deps, t }: {
+    deps: MaintenanceDeps;
+    t: Translate;
+}): Maintenance;

package/lib/types/client/use-panel-width.d.ts

@@ -6,7 +6,7 @@
  *
  * 量的是**盒子的 border-box 宽**（`getBoundingClientRect().width`），不是 `contentRect.width`：
  * 后者已经扣掉内边距，而"多宽才分两栏"那个阈值说的是整块盒子——拿扣过内边垫的数去比就是**扣两次**，
- * 结果明明够宽却退化成下钻（2026-10-15 真机反馈后定的判据）。
+ * 结果明明够宽却退化成下钻（真机反馈后定的判据）。
  *
  * 首帧读一次当前宽度，之后跟着 RO 走；读到 0 就是窄档 ⇒ **窄档是默认、宽档要被证明**。
  * RO 缺席（不可能的宿主）时停在窄档：功能一条不少，只是同屏两栏变成下钻。

package/lib/types/client/use-trash-panel-controller.d.ts

@@ -1,33 +1,33 @@
+import type { BusyGate } from './busy-gate.js';
 import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
-import type { PendingAction } from './trash-confirm.js';
 import type { TrashDetailState } from './trash-detail.js';
-import type { TrashQuery } from './use-trash-query.js';
-/** 面板的一枚全局闸：写动作在飞时 `busy` 为真，`around` 把一次任务整个包在"这一趟还算忙"里。 */
-export interface TrashPanelGate {
-    readonly busy: boolean;
-    around<T>(task: () => Promise<T>): Promise<T>;
-}
-/**
- * 闸本体（从 `trash-panel.tsx` 的函数体原样收进来）：任务落地或抛错都把 `busy` 放回 false。
- * 不做引用计数：面板同一时刻只允许一趟写动作（按钮在 `busy` 期间全被按住），多一层计数只会
- * 把"这一趟什么时候算完"变成第二个判据。
- *
- * 返回值经 `useMemo` 稳定：`gate` 进 `restore` / `confirmApply` 的 `useCallback` 依赖，每次渲染
- * 换个新对象会让那两个回调跟着失效，进而把引用它们的 effect 也带着重跑。
- */
-export declare function useTrashPanelGate(): TrashPanelGate;
+import { type TrashQuery } from './use-trash-query.js';
+/** 待确认的动作：一条记录、整个回收站、或多选挑出来的一批（`ids` 已按清单顺序排好）。
+ *  类型归状态机，视图只 import 它来渲染。 */
+export type PendingAction = {
+    kind: 'entry';
+    entry: TrashEntryLike;
+} | {
+    kind: 'all';
+} | {
+    kind: 'entries';
+    ids: readonly string[];
+} | {
+    kind: 'restore';
+    ids: readonly string[];
+};
 /**
- * 控制器要的面。`query` 只取三样：清单（选中从它里面找）、重读（失效通告与写动作之后用）、
- * 清空（面板的写动作那一半）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
+ * 控制器要的面。`query` 取五样：清单（选中从它里面找）、`refreshAll`（挂载与显式重试）、
+ * `refreshAfterWrite`（失效与写后）、清空（面板的写动作那一半）、`noteAttachmentCleanup`（purge 回执里
+ * 附件那半句交给查询侧拼句子上屏）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
  * 由面板算好传进来——布局常量不搬进控制器。
  */
 export interface TrashPanelControllerInput {
     deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
-    gate: TrashPanelGate;
-    query: Pick<TrashQuery, 'entries' | 'refresh' | 'emptyTrash'>;
+    gate: BusyGate;
+    query: Pick<TrashQuery, 'list' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash' | 'noteAttachmentCleanup'>;
     ordered: readonly TrashEntryLike[];
     canAutoSelect: boolean;
-    focusRow(entryId: string): void;
 }
 export interface TrashPanelController {
     readonly busy: boolean;
@@ -37,6 +37,8 @@ export interface TrashPanelController {
     readonly detail: TrashDetailState;
     /** 待确认的那一批（确认框的开合）；确认落地后由控制器收起。 */
     readonly pending: PendingAction | null;
+    /** 恢复确认框要摆的这一批（按勾选顺序；清单里已找不到的 id 滤掉）。 */
+    readonly pendingEntries: readonly TrashEntryLike[];
     /** 恢复/彻底删除/批量 的失败原文，按条目 id 存：切走再回来还在。 */
     readonly actionFailure: Readonly<Record<string, string>>;
     select(entry: TrashEntryLike, options?: {
@@ -44,8 +46,10 @@ export interface TrashPanelController {
     }): Promise<void>;
     retry(): void;
     back(): void;
-    setPending(pending: PendingAction | null): void;
-    /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存并重读清单，失败原文落回这一行。 */
+    /** 构造待确认动作（唯一入口：新增一种确认只改 `PendingAction` 与确认框，不再加一串转调）。 */
+    request(action: PendingAction): void;
+    cancelPending(): void;
+    /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存，写完无论成败都重读清单，失败原文落回这一行。 */
     restore(entry: TrashEntryLike): Promise<void>;
     /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */
     confirmPurge(): Promise<void>;

package/lib/types/client/use-trash-query.d.ts

@@ -1,32 +1,46 @@
-import { type OrphanReportWire, type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
+import type { BusyGate } from './busy-gate.js';
+import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
 import type { Translate } from './copy.js';
-export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'scanOrphans' | 'applyOutcomes' | 'emptyTrash'>;
+import type { AttachmentCleanupWire } from '../shared/wire.js';
+export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'emptyTrash'>;
+/** 清单的唯一状态：加载中 / 有行 / 未知。`unknown` 不向下游交出任何行——旧行不许继续可操作。 */
+export type TrashListState = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'ready';
+    readonly rows: readonly TrashEntryLike[];
+} | {
+    readonly status: 'unknown';
+    readonly failure: string;
+};
+/** 清单状态对视图的**唯一解读**：行、失败原文、加载中与空态一次交出。
+ *  面板与控制器不再各自从 `status` 反推——"未知"不是"空"，也不许把失败折成空态。 */
+export interface TrashListView {
+    readonly rows: readonly TrashEntryLike[] | null;
+    readonly failure: string | null;
+    readonly loading: boolean;
+    readonly empty: boolean;
+}
+export declare function listView(list: TrashListState): TrashListView;
 export interface TrashQuery {
-    /** `null` = 还没读到（第一次读或读失败）；与"空的"是两件事。 */
-    readonly entries: readonly TrashEntryLike[] | null;
-    readonly listFailure: string | null;
-    /** `null` = 还没扫到；失败时也置回 `null`（不拿空报告冒充干净）。 */
-    readonly orphanReport: OrphanReportWire | null;
-    readonly orphanFailure: string | null;
-    /** 「这一组已经不在」不是失败：单独一条中性提示。 */
-    readonly orphanNotice: string | null;
-    readonly orphanConfirm: boolean;
-    setOrphanConfirm(open: boolean): void;
-    /** 「查看并清理」：把上一条失败/中性提示清掉再开预览框（旧提示不该跟新一次预览并排出现）。 */
-    openOrphanPreview(): void;
-    /** 交回**这一次读数是否真的落地**：孤儿扫描吃的是对账后的清册，清单没读成就不能扫。 */
-    reload(): Promise<boolean>;
-    scanOrphans(): Promise<void>;
-    /** "重读一遍" = 先对账并读清单，再扫残留；清单没读成就不扫。 */
-    refresh(): Promise<void>;
-    /** 清理那批无主子会话（一段 `/apply` 的第五个动作），逐条结果落成"已不在了 / N 组未清理"。 */
-    cleanOrphans(): Promise<void>;
-    /** 清空回收站（聚合回执）：成功就重读，失败就把原文摆到清单那块。交回是否成功。 */
+    readonly list: TrashListState;
+    /** 最近一次写动作（purge / 清空）的附件读数，已经拼成一句话：**最新的写赢**。
+     *  一次没有附件读数的 purge / 清空、或这一趟写失败（没拿到回执）都会把它清成 `null`，不让上一条的
+     *  读数冒充这一趟；删除与恢复不碰它。它是**过去那一趟的回执**、不是清单状态：清单重读读不出来。 */
+    readonly attachmentNotice: string | null;
+    /** 把一份附件读数摆上屏（`undefined` = 这一趟没有读数，旧提示收掉）；句子怎么拼归这里，调用方只管转交。 */
+    noteAttachmentCleanup(a: AttachmentCleanupWire | undefined): void;
+    /** 重读清单；挂载与显式「重试」用它。面板没有第二条扫描：孤儿检查是设置页维护卡的手动动作。 */
+    refreshAll(): Promise<void>;
+    /** 写后/失效通告：与 `refreshAll` 同一条读。两个名字留着是因为调用点问的是两件事
+     *  （"用户要看现在的"与"别处动过了，跟上"），不是两条路径。清单读失败时旧行进 `unknown`。 */
+    refreshAfterWrite(): Promise<void>;
+    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把清单置为未知并摆上原文。交回是否成功。 */
     emptyTrash(): Promise<boolean>;
 }
-export declare function useTrashQuery({ deps, t, around, }: {
+export declare function useTrashQuery({ deps, t, gate, }: {
     deps: TrashQueryDeps;
     t: Translate;
-    /** 把"这一趟还算忙"的一枚全局闸套在一次动作外（面板的 `busy`）。 */
-    around: <T>(task: () => Promise<T>) => Promise<T>;
+    /** 面板的一枚全局闸：清空这条写动作把整趟包在里面（面板的 `busy`）。 */
+    gate: BusyGate;
 }): TrashQuery;

package/lib/types/client/write-seats.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 逐条 `/apply` 的写入座位：一次写入发生在哪个界面位置，就在哪个函数里绑定呈现材质、闸与重读通道。
+ *
+ * 收尾顺序住 `write-settlement.ts`（ADR-0013），面板的重读策略住 `use-trash-query.ts`；
+ * 座位只拥有「这次是谁在写、交哪些材质、闸在哪」。
+ *
+ * 边界：不判回执、不决定收尾顺序、不拥有各面的本地状态；面板座位的闸由面板传入，不另造第二枚。
+ * 无主子会话清理**不是**座位：它只在插件设置页的维护卡里手动触发（ADR-0021），
+ * 读数、闸与重查都归 `use-maintenance.ts`。
+ */
+import type { BusyGate } from './busy-gate.js';
+import type { OneShotDeps, TrashEntryLike } from './remote.js';
+import { type WriteOutcome } from './write.js';
+/** 会话行菜单的单删座位：一条会话、`single` 读法、成功发单条撤销横幅。交回这条会话的失败原文。 */
+export declare function deleteSessionFromMenu(deps: OneShotDeps, input: {
+    sessionId: string;
+    title: string;
+}, gate: BusyGate): Promise<string | null>;
+/** 批量删除座位（宿主会话列表的多选 → 批量确认框）：一次 `/apply`，撤销名单只收 ok 支的条目 id（跟着组走的幂等条不单列）。
+ *  只收 id：标题是浮条的呈现，不参与这一次写入。 */
+export declare function deleteSessionsFromBatch(deps: OneShotDeps, ids: readonly string[], gate: BusyGate): Promise<ReadonlyMap<string, string>>;
+/** 外部恢复座位（撤销横幅）：没有 busy 面，不传闸；主视图重开归 settlement，这里只让清单失效。 */
+export declare function restoreFromUndo(deps: OneShotDeps, input: {
+    ids: readonly string[];
+    single: boolean;
+}): Promise<WriteOutcome<'restore'>>;
+/** 面板两个 `/apply` 座位共用的那一半：依赖、条目 id、闸、重读与缓存失效。 */
+interface PanelWriteInput<A extends 'restore' | 'purge'> {
+    deps: OneShotDeps;
+    ids: readonly string[];
+    gate: BusyGate;
+    refreshAfterWrite(outcome: WriteOutcome<A>): Promise<void>;
+    clearDetailCache(ids: readonly string[]): void;
+}
+/** 面板恢复另要两样：单条读法，以及 already-gone 回执缺行时反查 sessionId 的当前清单。 */
+interface PanelRestoreInput extends PanelWriteInput<'restore'> {
+    single?: boolean;
+    entries: readonly TrashEntryLike[] | null;
+}
+/** 面板恢复座位：面板已替这条完成「回来」的结算 ⇒ `panelSeat`；撤销横幅与详情缓存都按落地条目收。 */
+export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'>>;
+/** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。 */
+export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'>>;
+export {};

package/lib/types/client/write-settlement.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 一次逐条 `/apply` 写入成功后的**收尾顺序**，按 action 各一条固定序列。
+ *
+ * 调用方只交呈现材质（`WritePresentation`），顺序与 `anySuccess` 门只住这里；`runWrite` 在拿到
+ * `WriteSuccess` 后、`refresh` 前调一次。为什么按 action 收成一处见 ADR-0013。
+ *
+ * 四条判据：
+ * - **跨槽位在信封成功时就跑**：`afterDelete` / `afterRestore` 与 `invalidate` 不管逐条成败都跑
+ *   （回滚失败可能留下半套，回收站清单不能继续摆旧行）；呈现钩子（发布/熄灭撤销、遗忘主视图、
+ *   清详情缓存）只在至少一条落地（`anySuccess`）时跑——没有落点的撤销是假动作。delete 的撤销
+ *   另要求落地名单非空：全部被同批前一条带走时没有可撤销的条目。
+ * - **面板恢复用 `panelSeat: true` 明说**（「缺席」不再承载语义）：外部恢复（撤销横幅）由 settlement
+ *   调 `afterRestore` 重开；面板恢复自带「回来」的结算，只 `forgetMainView`、不重开、不抢焦点。
+ *   判据住 `src/client/main-view.ts` 的 `forgetMainView`。
+ * - **撤销名单由摘要给、座位发布**：delete 支从 `summary.landedIds`（域是条目 id）取名单、用
+ *   `summary.successIds.length` 作条数，组成 `{ entryIds, n }` 交给座位，座位只决定发布哪一形
+ *   （单条带标题、批量带条数）——那句文案与它的键住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
+ *   `anySuccess` 时熄灭指向这些条目的横幅——留着就是一条注定失败的「撤销」。
+ * - **`count` 不结算**；`orphan-clean` 没有跨槽位收尾（维护卡的 `use-maintenance.ts` 清完自己重查）。
+ *   不直接读 DOM、不问宿主：主视图收尾只经 `main-view.ts` 的 `afterDelete` / `afterRestore`
+ *   （服务缺席或抛错都静默退回）；重读仍归各调用方的 `refresh`（面板那侧的最新票在 `use-trash-query.ts`）。
+ */
+import type { ApplyAction } from '../shared/wire.js';
+import type { ReceiptSummary } from './receipt.js';
+/** 一次写入里与渲染无关的那部分：动作、请求 id、以及唯一的那份回执摘要。 */
+export interface SettledFacts<A extends ApplyAction> {
+    readonly action: A;
+    readonly ids: readonly string[];
+    readonly summary: ReceiptSummary;
+}
+/**
+ * 按 action 切开的一族呈现材质：每个座位只能拿到自己动作那几手，形状对不上的钩子在类型面就不存在。
+ * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 从摘要取出并组好的落地名单。
+ * - `restore` 的 `panelSeat: true` 才是「面板已替这条完成『回来』的结算」，不再靠缺席某个钩子暗示。
+ * - `count` / `orphan-clean` 没有呈现材质（用 `noPresentation`）。
+ * 钩子都是同步的：settlement 在 `refresh` 前一次跑完，不 await。
+ */
+export type WritePresentationByAction = {
+    delete: {
+        /** 外部写入座位：让回收站面板重读。面板写不传（自己的 `refreshAfterWrite` 就是重读）。 */
+        invalidate?(): void;
+        /** 撤销发布：settlement 从回执摘要取出落地条目 id 与请求名单、组好形之后交来；名单**非空**——
+         *  全被同批前一条带走时没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
+        publishUndo?(landed: {
+            readonly entryIds: readonly [string, ...string[]];
+            readonly n: number;
+        }): void;
+    };
+    restore: {
+        invalidate?(): void;
+        /** 面板恢复座位：true = 面板已替这条完成「回来」的结算，只遗忘、不重开、不抢焦点。 */
+        panelSeat?: true;
+        dismissUndo?(entryIds: readonly string[]): void;
+        clearDetailCache?(entryIds: readonly string[]): void;
+    };
+    purge: {
+        dismissUndo?(entryIds: readonly string[]): void;
+        clearDetailCache?(entryIds: readonly string[]): void;
+    };
+    count: Record<string, never>;
+    'orphan-clean': Record<string, never>;
+};
+export type WritePresentation<A extends ApplyAction> = WritePresentationByAction[A];
+/** 没有呈现材质的座位用它：抛掉按 action 的联合，调用点不用各自造一个空对象字面量。 */
+export declare function noPresentation<A extends ApplyAction>(action: A): WritePresentation<A>;
+export declare function settleWrite<A extends ApplyAction>(success: SettledFacts<A>, presentation: WritePresentation<A>): void;

package/lib/types/client/write.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → 回执摘要 → settlement → refresh。
+ *
+ * 收尾顺序与 `anySuccess` 门住 `src/client/write-settlement.ts`（为什么按 action 收见 ADR-0013）；
+ * 这里只管时机、信封判读、整趟的闸与 `refresh` 的交法。清空回收站是聚合回执（`/empty`），收尾仍住
+ * `use-trash-query.ts` 的 `emptyTrash`。
+ *
+ * 五条判据：
+ * - `ok` 只说**信封**成不成；逐条成败在 `failures` 里，调用方自己决定怎么上屏。
+ * - 顶层失败把同一句原文铺到每个 id，不结算；`refresh` 照样交（成败都在 outcome 里）。
+ * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 与落地名单由
+ *   `receipt.ts` 的回执摘要算好，settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
+ *   结算在 `refresh` 之前：列表重读看得到收尾后的现场。
+ * - `single: true` 时把 N=1 模式交给 `receipt.ts` 的读法；单条 null 在那一处折成 failed，
+ *   这里不再重复守卫。
+ * - **闸包住整趟**：给了 `gate` 就把 apply → settle → refresh 一起包进去——refresh 落在闸外时，
+ *   旧清单还在屏上，同一个动作能被再点一次；调用方不再自己 `around`。
+ */
+import type { BusyGate } from './busy-gate.js';
+import { type OneShotDeps } from './remote.js';
+import { type SettledFacts, type WritePresentation } from './write-settlement.js';
+import type { ApplyAction, RemoteFailure } from '../shared/wire.js';
+export type WriteSuccess<A extends ApplyAction> = SettledFacts<A> & {
+    readonly ok: true;
+    /** 逐条失败原文（failed / neutral / missing），按 id。这是失败表的**唯一落点**：
+     *  摘要只带聚合与落地 id，不再复制一份逐条原文。 */
+    readonly failures: ReadonlyMap<string, string>;
+};
+export interface WriteFailure<A extends ApplyAction> {
+    readonly ok: false;
+    readonly action: A;
+    readonly ids: readonly string[];
+    readonly failure: RemoteFailure;
+    /** 顶层失败时同一句原文铺到每个请求 id。 */
+    readonly failures: ReadonlyMap<string, string>;
+}
+export type WriteOutcome<A extends ApplyAction> = WriteSuccess<A> | WriteFailure<A>;
+export interface WriteInput<A extends ApplyAction> {
+    readonly deps: OneShotDeps;
+    readonly action: A;
+    readonly ids: readonly string[];
+    /** 单条写入面：把 N=1 模式交给 receipt 读法（null 折成协议错）。 */
+    readonly single?: boolean;
+    /** restore 的 already-gone 回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
+    readonly sessionIdOfEntry?: (entryId: string) => string | undefined;
+    /** 信封成功时交给 settlement 的呈现材质（摘要里的成功名单可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
+    readonly presentation?: WritePresentation<A>;
+    /** 这一趟的闸：给了就把 apply → settle → refresh 整趟包进 busy。refresh 不许落在闸外。 */
+    readonly gate?: BusyGate;
+    /** 写完（顶层失败或信封成功，无论逐条成败）后的重读策略；成败与 `anySuccess` 都在 outcome 里，
+     *  是否真的重读由调用方决定。 */
+    readonly refresh?: (outcome: WriteOutcome<A>) => void | Promise<void>;
+}
+export declare function runWrite<A extends ApplyAction>(input: WriteInput<A>): Promise<WriteOutcome<A>>;

package/lib/types/deps.d.ts

@@ -1,14 +1,25 @@
-import type { FsPort } from './ports/fs-port.js';
-import type { HostPort } from './ports/host-port.js';
-import type { ManifestPort } from './trash/manifest.js';
-/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。 */
+import type { CoreFsPort, FsPort } from './ports/fs-port.js';
+import type { HostCorePort } from './ports/host-port.js';
+import type { PresenceCapability } from './ports/presence-port.js';
+import type { TrashLedger } from './trash/ledger.js';
+/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。
+ *  `fs` 不含 `removeDir` / `removeFile`，`host` 不含在场三件——两条危险能力各走 {@link RemovalDeps} 与
+ *  {@link CoreDeps.presence}。 */
 export interface CoreDeps {
-    fs: FsPort;
-    host: HostPort;
-    manifest: ManifestPort;
+    fs: CoreFsPort;
+    host: HostCorePort;
+    ledger: TrashLedger;
     home: string;
+    presence: PresenceCapability;
 }
-/** 只有删除读时钟；其余读 / 计划 / 恢复 / 永久删除只用 CoreDeps。 */
-export type DeleteDeps = CoreDeps & {
+/** 会话删除动词的依赖面：只多读时钟；它不删目录（回滚只把搬走的搬回）。 */
+export type DeleteSessionDeps = CoreDeps & {
     now(): number;
 };
+/** 永久删除的执行面：执行器及其分发拿得到 `removeDir` 与 `removeFile`；计划函数仍只收 `CoreDeps`（它们不写）。 */
+export type RemovalDeps = CoreDeps & {
+    fs: CoreFsPort & Pick<FsPort, 'removeDir' | 'removeFile'>;
+};
+/** 组合根装出的全量面：`/apply` 的分发同时够到删除的时钟与永久删除的 `removeDir` / `removeFile`
+ *  （后者也供孤儿附件清理段使用）。 */
+export type DeleteDeps = DeleteSessionDeps & RemovalDeps;

package/lib/types/index.d.ts

@@ -15,15 +15,20 @@ export declare const name = "@xrn1997/dsh-session-delete";
  *   它同样可能晚于本插件激活，写进插件 inject 只会让整个插件 pending。
  *
  * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
- * 前缀路由，浏览器半同源 fetch 那六个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+ * 前缀路由，浏览器半同源 fetch 那九个段名。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
  * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
  * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
  *
- * 清单（storage domain 绑定）与数据根各有一个家：`src/trash/storage-manifest.ts`、`src/ports/home.ts`。
+ * `connection` 只喂请求栅栏的远程支（`src/api/request-trust.ts` ②），按 `ctx.get` 可选读：
+ * 服务缺席时插件照常激活，远程客户端 fail-closed。它不进 `inject`——写进去会让没有 web 组成的
+ * profile 整个停在 pending。
+ *
+ * 清册的三层各有各的家：raw 绑定 `src/trash/storage-manifest.ts`、读面（对账 + 读）`src/trash/ledger.ts`、
+ * 数据根 `src/ports/home.ts`。这里只把它们接起来，任何一层都不在组合根里长判据。
  */
 export declare const inject: string[];
 /**
- * 装配顺序：**清单 → 端口 → 动词依赖 → 前缀路由**（`DeleteDeps` 就是前两者的合一）。
+ * 装配顺序：**清单 → 端口 → 在场能力 → 动词依赖 → 前缀路由**（`DeleteDeps` 把这些依赖面合成一颗）。
  *
  * 路由用 `ctx.effect` 挂、disposer 归装载它的那根 fiber：插件卸载即摘路由（`register` 返回的
  * disposer 是官方契约）。**同一进程里只注册一次**这件事由宿主把住：重复的 `(kind, path)`

package/lib/types/log/session-log.d.ts

@@ -16,10 +16,11 @@ export interface SessionLogStats {
     /** 整条日志最后一个换行之后的字节数（>0 说明尾巴被切了一刀）。 */
     truncatedTailBytes: number;
 }
+/** 这个名字是不是规范日志（任意一代）。附件引用扫描用它区分"老一代日志"与"读不懂的旁文件"。 */
+export declare function isCanonicalSessionLogName(name: string): boolean;
 /**
- * 同一个会话目录里**可以并存多代日志**（宿主换代时把老代留在原地当历史语料，本机实测 7 个目录如此），
- * 而新代是老代的**迁移后超集**（实测：`firstTs` 与开头那条提问完全相同、记录更多、末尾更晚）
- * ⇒ 要读的是版本号最大的那一代，读旧代 = 读到一份截了尾巴的快照；把几代拼起来 = 重复计数。
+ * 同一个会话目录里可以并存多代日志；只读版本号最大的那代，因为新代包含旧代的记录且末尾更晚
+ * ⇒ 读旧代 = 一份截了尾巴的快照；把几代拼起来 = 重复计数。
  *
  * 明文（无 `.zstd`）不在此列：本插件的读法逐帧解 zstd，明文得走另一条解码路。
  */

package/lib/types/log/zstd-frames.d.ts

@@ -1,5 +1,5 @@
 /**
- * 多帧 zstd 流的**帧边界**（2026-10-15 实测）。
+ * 多帧 zstd 流的帧边界。
  *
  * 为什么要有这个文件：会话日志是一次次 append 出来的**帧序列**，而 Node 的 `zstdDecompressSync`
  * **与** `createZstdDecompress()` 流式**都只给第一帧**（实测：本机一个 3.8 MB 的文件，两个 API 都只回
@@ -8,15 +8,21 @@
  * 帧 = `magic(4) + Frame_Header_Descriptor(1) + [Window 1B 若 !single] + [DID 0/1/2/4] + [FCS]
  *       + 若干块（3B 块头 + 块体）+ [4B 尾巴]`。
  *
- * **真实产物的形态是量出来的**（本机 125 个文件 / 36 904 帧）：descriptor **恒 `0x04`**（单段 ⇒ 无
- * Window，FCS 1 字节，无字典，校验位没置位），块类型只有 `Compressed`(36 630) 与 `Raw`(620)，
- * 每帧 **1～120 块**（多数 1 块）——所以多块循环与 Raw 两条路都在生产上跑着，不是纸面分支。
+ * **真实产物的形态是量出来的**（本机 125 个文件 / 36 904 帧）：descriptor **恒 `0x04`**，按 RFC 8878
+ * 表 3 读作「非单段（带 1 字节 Window）+ 无 FCS + 无字典 + **校验位置位**」⇒ 帧头 6 字节，帧尾那 4 字节
+ * 就是声明好的 XXH32 Content_Checksum（实测：动它一个位，对面解不通过）。块类型只有
+ * `Compressed`(36 630) 与 `Raw`(620)，每帧 **1～120 块**（多数 1 块）——所以多块循环与 Raw 两条路都在
+ * 生产上跑着，不是纸面分支。
  * 类型 3 是规范的 Reserved 位（不是"未压缩块"）：产物里没出现过，Node 也当场拒解 ⇒ 遇到就抛。
  *
- * **尾巴那 4 字节按实测处理，不按 descriptor 的 bit5**：校验位从未置位，却每帧都带 4 字节；
- * 判"读不读这 4 字节"用的是「跳过去必须正好撞上下一帧的 magic 或到 EOF」——猜错不会静默切歪：
- * 末尾的自证与块界护栏会抛（护栏是必需的：块头越界时 `|` 读回 0，而 0 的 `Last_Block` 位没置位，
- * 少了它块循环每圈只 +3 字节却永不 break，整个进程卡死——2026-10-15 写用例时真卡死过一次）。
+ * **位段必须照表 3 取**（1-0 字典 / 2 校验 / 5 单段 / 7-6 FCS 尺寸）：Descriptor 的 64 个合法取值里，
+ * 取错位段会算错头长的有 48 个，剩下 16 个凑对纯属巧合——在产的 `0x04` 就在其中。换个宿主、换个写帧
+ * 的 zstd 版本（明文一大、FCS 上到 4 字节的 `0xa0` 就会算错），帧就切歪，会话日志直接读不出来。
+ *
+ * **尾巴那 4 字节按实测判据收，不按 descriptor 的 bit2**：规则是「跳过去必须正好撞上下一帧的 magic
+ * 或到 EOF」——猜错不会静默切歪：末尾的自证与块界护栏会抛（护栏是必需的：块头越界时 `|` 读回 0，
+ * 而 0 的 `Last_Block` 位没置位，少了它块循环每圈只 +3 字节却永不 break，整个进程会卡死；
+ * 用例覆盖这一条）。
  */
 export interface FrameRange {
     start: number;

package/lib/types/ports/agent-handles.d.ts

@@ -1,5 +1,5 @@
 /** 捕获所需的 ctx 窄面：可选服务读法（`get`）与按依赖注入的子上下文（`inject`，晚挂载的 `agents` 靠它补装）。
- *  旧 ctx / 假件可以没有 `inject`——那就只在 apply 时 `get` 一次。 */
+ *  有些 ctx / 假件没有 `inject`——那就只在 apply 时 `get` 一次。 */
 export interface AgentCtxLike {
     get(name: string): unknown;
     inject?(names: readonly string[], callback: (child: {