@xrn1997/dsh-session-delete 0.3.1 → 0.4.0

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

@@ -1,43 +1,46 @@
 import type { BusyGate } from './busy-gate.js';
-import { type OrphanReportWire, type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
-import type { WriteOutcome } from './write.js';
+import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
 import type { Translate } from './copy.js';
-import type { ApplyAction } from '../shared/wire.js';
-export type TrashQueryDeps = Pick<SessionDeleteRemote, 'list' | 'scanOrphans' | 'applyOutcomes' | 'emptyTrash'>;
-/** 一次清单读的结局：`stale` = 被后发的读顶掉（什么都没落地，调用方不许拿它当失败清场）。 */
-export type ReloadResult = 'ok' | 'failed' | 'stale';
+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;
-    /** 只重读清单（对账 + 读）。交回**这一次读的结局**：落地 / 读失败 / 被后发的读顶掉。
-     *  残留报告与提示的联动不在这里；组合清场归 `refreshAll` / `refreshAfterWrite`。 */
-    reloadRows(): Promise<ReloadResult>;
-    /** 只扫残留。调用方负责先让清单对过账（`refreshAll` / `refreshAfterWrite` 已经排好序）。 */
-    rescanOrphans(): Promise<void>;
-    /** 先读清单、成了再扫残留；挂载与显式「重试」用它。 */
+    readonly list: TrashListState;
+    /** 最近一次写动作（purge / 清空）的附件读数，已经拼成一句话：**最新的写赢**。
+     *  一次没有附件读数的 purge / 清空、或这一趟写失败（没拿到回执）都会把它清成 `null`，不让上一条的
+     *  读数冒充这一趟；删除与恢复不碰它。它是**过去那一趟的回执**、不是清单状态：清单重读读不出来。 */
+    readonly attachmentNotice: string | null;
+    /** 把一份附件读数摆上屏（`undefined` = 这一趟没有读数，旧提示收掉）；句子怎么拼归这里，调用方只管转交。 */
+    noteAttachmentCleanup(a: AttachmentCleanupWire | undefined): void;
+    /** 重读清单；挂载与显式「重试」用它。面板没有第二条扫描：孤儿检查是设置页维护卡的手动动作。 */
     refreshAll(): Promise<void>;
-    /** 写后/失效：只重读清单；是否顺带重扫残留由这次的 `outcome` 从 action / ids / 当前清单自行派生
-     *  （判据住 `needsOrphanRescan`）。失效通告不带 outcome：报告未知或非空才重扫。输给后发读时由赢家补扫；
-     *  清单读失败时清空报告与提示。 */
-    refreshAfterWrite(outcome?: WriteOutcome<ApplyAction>): Promise<void>;
-    /** 清理那批无主子会话（一段 `/apply` 的第五个动作），逐条结果落成"已不在了 / N 组未清理"。 */
-    cleanOrphans(): Promise<void>;
-    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把原文摆到清单那块。交回是否成功。 */
+    /** 写后/失效通告：与 `refreshAll` 同一条读。两个名字留着是因为调用点问的是两件事
+     *  （"用户要看现在的"与"别处动过了，跟上"），不是两条路径。清单读失败时旧行进 `unknown`。 */
+    refreshAfterWrite(): Promise<void>;
+    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把清单置为未知并摆上原文。交回是否成功。 */
     emptyTrash(): Promise<boolean>;
 }
 export declare function useTrashQuery({ deps, t, gate, }: {
     deps: TrashQueryDeps;
     t: Translate;
-    /** 面板的一枚全局闸：清空与无主子会话清理这两条写动作把整趟包在里面（面板的 `busy`）。 */
+    /** 面板的一枚全局闸：清空这条写动作把整趟包在里面（面板的 `busy`）。 */
     gate: BusyGate;
 }): TrashQuery;

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

@@ -1,12 +1,12 @@
 /**
- * 逐条 `/apply` 的**写入座位**：一次写入发生在哪个界面位置，就在哪个函数里把呈现材质、闸与重读通道绑好。
+ * 逐条 `/apply` 的写入座位：一次写入发生在哪个界面位置，就在哪个函数里绑定呈现材质、闸与重读通道。
  *
- * 为什么要有它：六个调用点此前各自拼 `runWrite({ presentation: {…} })`，并各自决定要不要外包一层闸。
- * 收尾顺序（`write-settlement.ts`，ADR-0013）与重读策略（`use-trash-query.ts`，ADR-0016）不动；
+ * 收尾顺序住 `write-settlement.ts`（ADR-0013），面板的重读策略住 `use-trash-query.ts`；
  * 座位只拥有「这次是谁在写、交哪些材质、闸在哪」。
  *
- * 边界：不判回执（`receipt.ts`）、不决定收尾顺序、不拥有各面的本地状态（`pending` / 详情缓存 / 行失败）。
- * 面板座位的闸由面板传入：`busy` 是它的 UI 状态，座位不另造第二枚。
+ * 边界：不判回执、不决定收尾顺序、不拥有各面的本地状态；面板座位的闸由面板传入，不另造第二枚。
+ * 无主子会话清理**不是**座位：它只在插件设置页的维护卡里手动触发（ADR-0021），
+ * 读数、闸与重查都归 `use-maintenance.ts`。
  */
 import type { BusyGate } from './busy-gate.js';
 import type { OneShotDeps, TrashEntryLike } from './remote.js';
@@ -41,12 +41,4 @@ interface PanelRestoreInput extends PanelWriteInput<'restore'> {
 export declare function restoreFromPanel(input: PanelRestoreInput): Promise<WriteOutcome<'restore'>>;
 /** 面板彻底删除座位：永久删除也让指向这些条目的撤销横幅熄灭（settlement 的 purge 支负责）。 */
 export declare function purgeFromPanel(input: PanelWriteInput<'purge'>): Promise<WriteOutcome<'purge'>>;
-interface OrphanCleanSeatInput {
-    deps: OneShotDeps;
-    ids: readonly string[];
-    gate: BusyGate;
-    refreshAfterWrite(outcome: WriteOutcome<'orphan-clean'>): Promise<void>;
-}
-/** 无主子会话清理座位：不碰回收站失效与撤销，回执判读仍归 `use-trash-query.ts`。 */
-export declare function cleanOrphansFromPanel(input: OrphanCleanSeatInput): Promise<WriteOutcome<'orphan-clean'>>;
 export {};

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

@@ -12,29 +12,25 @@
  * - **面板恢复用 `panelSeat: true` 明说**（「缺席」不再承载语义）：外部恢复（撤销横幅）由 settlement
  *   调 `afterRestore` 重开；面板恢复自带「回来」的结算，只 `forgetMainView`、不重开、不抢焦点。
  *   判据住 `src/client/main-view.ts` 的 `forgetMainView`。
- * - **撤销名单由 settlement 算、座位发布**：delete 支把 `landedEntryIds` 与 `successIds.length` 算成
- *   `{ entryIds, n }` 交给座位，座位只决定发布哪一形（单条带标题、批量带条数）——那句文案与它的键
- *   住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
+ * - **撤销名单由摘要给、座位发布**：delete 支从 `summary.landedIds`（域是条目 id）取名单、用
+ *   `summary.successIds.length` 作条数，组成 `{ entryIds, n }` 交给座位，座位只决定发布哪一形
+ *   （单条带标题、批量带条数）——那句文案与它的键住 `undo-toast.tsx` 与 `copy.ts`；purge 支在
  *   `anySuccess` 时熄灭指向这些条目的横幅——留着就是一条注定失败的「撤销」。
- * - **`count` 不结算**；`orphan-clean` 没有跨槽位收尾（清完由 query 自己的写后刷新收尾）。
+ * - **`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 Receipt } from './receipt.js';
-/** 一次写入里与渲染无关的那部分：动作、请求 id、回执、成功名单与“至少一条落地”。 */
+import type { ReceiptSummary } from './receipt.js';
+/** 一次写入里与渲染无关的那部分：动作、请求 id、以及唯一的那份回执摘要。 */
 export interface SettledFacts<A extends ApplyAction> {
     readonly action: A;
     readonly ids: readonly string[];
-    readonly receipt: Receipt<A>;
-    /** 成功支（`ok` / `already-gone`）的请求 id，按请求顺序。 */
-    readonly successIds: readonly string[];
-    /** 至少一条真的落地（`ok` / `already-gone`；N=1 的协议空值不算）。 */
-    readonly anySuccess: boolean;
+    readonly summary: ReceiptSummary;
 }
 /**
  * 按 action 切开的一族呈现材质：每个座位只能拿到自己动作那几手，形状对不上的钩子在类型面就不存在。
- * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 算好的落地名单。
+ * - `delete` 的 `publishUndo` 存在即「这个座位要发撤销横幅」；它拿到的是 settlement 从摘要取出并组好的落地名单。
  * - `restore` 的 `panelSeat: true` 才是「面板已替这条完成『回来』的结算」，不再靠缺席某个钩子暗示。
  * - `count` / `orphan-clean` 没有呈现材质（用 `noPresentation`）。
  * 钩子都是同步的：settlement 在 `refresh` 前一次跑完，不 await。
@@ -43,8 +39,8 @@ export type WritePresentationByAction = {
     delete: {
         /** 外部写入座位：让回收站面板重读。面板写不传（自己的 `refreshAfterWrite` 就是重读）。 */
         invalidate?(): void;
-        /** 撤销发布：settlement 把落地的条目 id 与请求名单算好后交来；名单**非空**——全被同批前一条带走时
-         *  没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
+        /** 撤销发布：settlement 从回执摘要取出落地条目 id 与请求名单、组好形之后交来；名单**非空**——
+         *  全被同批前一条带走时没有落点，settlement 不发布没有可撤销动作的横幅。座位只决定发布哪一形与那一形带的标题。 */
         publishUndo?(landed: {
             readonly entryIds: readonly [string, ...string[]];
             readonly n: number;
@@ -56,8 +52,6 @@ export type WritePresentationByAction = {
         panelSeat?: true;
         dismissUndo?(entryIds: readonly string[]): void;
         clearDetailCache?(entryIds: readonly string[]): void;
-        /** already-gone 的回执不带行，它的 sessionId 只能由调用方从当前清单里查。 */
-        sessionIdOfEntry?(entryId: string): string | undefined;
     };
     purge: {
         dismissUndo?(entryIds: readonly string[]): void;

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

@@ -1,5 +1,5 @@
 /**
- * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → settlement → refresh。
+ * 一次逐条 `/apply` 写入的**唯一生命周期**：apply → 解信封 → `readReceipt` → 回执摘要 → settlement → refresh。
  *
  * 收尾顺序与 `anySuccess` 门住 `src/client/write-settlement.ts`（为什么按 action 收见 ADR-0013）；
  * 这里只管时机、信封判读、整趟的闸与 `refresh` 的交法。清空回收站是聚合回执（`/empty`），收尾仍住
@@ -8,8 +8,8 @@
  * 五条判据：
  * - `ok` 只说**信封**成不成；逐条成败在 `failures` 里，调用方自己决定怎么上屏。
  * - 顶层失败把同一句原文铺到每个 id，不结算；`refresh` 照样交（成败都在 outcome 里）。
- * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 由这里算好，
- *   按 action 的呈现材质由 settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
+ * - **信封成功就结算**（逐条全失败也跑：批量写入的失效通告不能漏）；`anySuccess` 与落地名单由
+ *   `receipt.ts` 的回执摘要算好，settlement 按它上闸。调用方只交呈现材质，再按 `outcome` 决定是否真的重读。
  *   结算在 `refresh` 之前：列表重读看得到收尾后的现场。
  * - `single: true` 时把 N=1 模式交给 `receipt.ts` 的读法；单条 null 在那一处折成 failed，
  *   这里不再重复守卫。
@@ -22,7 +22,8 @@ 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。 */
+    /** 逐条失败原文（failed / neutral / missing），按 id。这是失败表的**唯一落点**：
+     *  摘要只带聚合与落地 id，不再复制一份逐条原文。 */
     readonly failures: ReadonlyMap<string, string>;
 };
 export interface WriteFailure<A extends ApplyAction> {
@@ -40,7 +41,9 @@ export interface WriteInput<A extends ApplyAction> {
     readonly ids: readonly string[];
     /** 单条写入面：把 N=1 模式交给 receipt 读法（null 折成协议错）。 */
     readonly single?: boolean;
-    /** 信封成功时交给 settlement 的呈现材质（`successIds` 可能为空）；按 action 的收尾顺序住 `write-settlement.ts`。 */
+    /** 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;

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 { 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。 */
+/** Node 半的基础依赖面：组合根只装配这一颗；动词之间不互相 import 依赖面 interface。
+ *  `fs` 不含 `removeDir` / `removeFile`，`host` 不含在场三件——两条危险能力各走 {@link RemovalDeps} 与
+ *  {@link CoreDeps.presence}。 */
 export interface CoreDeps {
-    fs: FsPort;
-    host: HostPort;
+    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,16 +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` 原文读实，不是猜的。
  *
+ * `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: {

package/lib/types/ports/connection-port.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 宿主 `connection` 服务（`dsh-client-connection` 的 `HostConnectionService`，`super(ctx, "connection")`）
+ * 的窄镜像：`requestRejection(request)` 一次做宿主 `/api` 的那两道——Host/Origin 栅栏与「已认证 live peer」。
+ *
+ * **每次请求惰性解析服务**，不在激活时取一次：插件与 `client-connection` 的激活顺序没有承诺，取早了
+ * 会让远程支永远缺席（LAN 上全 403 且难排查）。`ctx.get` 是同步查表，代价可以忽略。
+ *
+ * **状态码在这里翻成裁决**（401 = 归属对、缺身份；403 = 归属不对；其余按归属不对处理），
+ * 调用方拿到的就是自己的词表，不需要知道宿主用哪个码表达哪件事。成员名与返回值按 asar
+ * `dsh-client-connection/lib/index.js` 原文读实。
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+export type ConnectionVerdict = {
+    readonly kind: 'allowed';
+}
+/** 组成里没有这个服务（无 web 组成 / 老代次）——调用方 fail-closed。 */
+ | {
+    readonly kind: 'absent';
+}
+/** 宿主认可归属，但这条请求没带已认证身份。 */
+ | {
+    readonly kind: 'unauthenticated';
+}
+/** 宿主不认可归属（Host/Origin 栅栏不过，或它给出的其余状态码）。 */
+ | {
+    readonly kind: 'untrusted';
+};
+export interface ConnectionPort {
+    verdictFor(req: IncomingMessage): ConnectionVerdict;
+}
+/** 成员抛错按「归属不对」拒绝（fail-closed）。 */
+export declare function createConnectionPort(ctx: Context): ConnectionPort;

package/lib/types/ports/fs-port.d.ts

@@ -2,15 +2,27 @@ export interface FsPort {
     exists(p: string): Promise<boolean>;
     /** 建目录（含中间层）。首删时 `~/.dsh/session-trash/` 还不存在，而 `rename` 不建父目录。 */
     ensureDir(p: string): Promise<void>;
+    /** 搬目录：**目标已存在一律失败**，跨卷（EXDEV）也失败并说清楚——不替换、也不偷偷改成复制。
+     *  Linux 的 `rename` 会静默替代空目录而 Windows 不会，这个差别不能交给操作系统决定。 */
     rename(from: string, to: string): Promise<void>;
     removeDir(p: string): Promise<void>;
     sizeOfDir(p: string): Promise<number>;
     /** 目录下的条目名（**不递归**）。回收站详情要用它在那条目录里挑 `*.jsonl.zstd`。 */
     listFiles(p: string): Promise<string[]>;
-    /** 目录下的**子目录**名（不递归）。回收站对账用它找出"清单里还没有行"的条目目录——
+    /** 目录下的**子目录**名（不递归；**跟随软链**）。回收站对账用它找出"清单里还没有行"的条目目录——
      *  与 `listFiles` 分开是为了让"拒收文件"发生在挑选阶段（回收站根里落进来的杂散文件当外人）。 */
     listDirs(p: string): Promise<string[]>;
+    /** 解析符号链接后的真实路径。递归走目录时防环用：跟随软链之后，目录图不再是树。 */
+    realpath(p: string): Promise<string>;
     /** 整个文件读进内存。实测本机回收站里最大单文件 4.66 MB；**内存口径由逐帧解压把住**（见 `src/log/session-log.ts`），不在这里。 */
     readFile(p: string): Promise<Buffer>;
+    /** 只读的单文件读数：附件渲染与独占计划都用它（不递归、不跟随目录）。 */
+    statFile(p: string): Promise<{
+        size: number;
+    }>;
+    /** 删单个文件（不是目录）。危险能力，只挂到 `RemovalDeps` 上。 */
+    removeFile(p: string): Promise<void>;
 }
+/** 动词的基础面：读与搬移都有，**不拿删除**。删目录与删单文件只挂在 `RemovalDeps` 上（ADR-0006）。 */
+export type CoreFsPort = Omit<FsPort, 'removeDir' | 'removeFile'>;
 export declare function createFsPort(): FsPort;

package/lib/types/ports/host-port.d.ts

@@ -1,23 +1,12 @@
 /** 摘内存的三种落地（见 {@link HostPort.evictLive}）：`not-live` / `evicted` 都意味着**宿主列表已经不含它**；
  *  `unknown` 意味着读不到或摘不掉，**不能**据此通告客户端（发了就是假话，重连后那一行会自己长回来）。 */
 export type EvictionOutcome = 'evicted' | 'not-live' | 'unknown';
-/**
- * 角色一：**身份与归属**——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
- *
- * 为什么拆成角色：宿主能力的端口按角色切成三块，而不是一个什么都有的接口。调用方要的是
- * "一句话能说清的那一组能力"，而一个什么都有的端口让每条用例都得凑齐不相干的成员。
- * 这里只切**类型**，adapter 仍是同一颗对象。
- */
+/** 角色一：身份与归属——会话是谁、落在哪个项目/工作区、活不活/归档没有，以及账本与归档的写面。
+ *  只切类型，adapter 仍是同一颗对象。 */
 export interface HostIdentityPort {
     workspaceOf(sessionId: string): Promise<string | undefined>;
-    /** 账本里还有这个工作区吗。**只读的判别**（`registry.get(id) !== undefined`），不抛。
-     *
-     *  **为什么恢复需要它**：宿主的「删除工作区」只删**注册**、保留目录与每一份会话日志
-     *  （asar `WorkspaceRegistry.delete` 的 JSDoc 原文 "Delete one workspace registration while
-     *  retaining its directory and every session log"），那些会话之后显示在「未分组」下。回收站里
-     *  **删在工作区之前**的条目记着那个已被删掉的 `workspaceId`，恢复时若照旧 `attach` 就会
-     *  `workspace not found` 整条失败（会话留在回收站里，用户看起来就是"恢复报错"）。所以恢复
-     *  先问这一句：不在 ⇒ 不挂账本，照常回盘、归入「未分组」（与宿主自己处理这类会话一致）。 */
+    /** 账本里还有这个工作区吗：只读判别，不抛。
+     *  宿主的「删除工作区」只删注册、保留目录与日志；恢复这类会话时跳过 attach，归入「未分组」。 */
     workspaceExists(workspaceId: string): Promise<boolean>;
     /** 会话落盘的**项目目录名**（`<sessions>/<projectKey(cwd)>`）；账本里没有这个会话 ⇒ `undefined`。
      *  与 `workspaceOf` 同一口径：**未命中是正常的 no-op，不是故障**（存储真故障照抛）。 */
@@ -69,7 +58,7 @@ export type CorpusRead<T> = {
  * 角色三：**会话语料**——整表身份与子会话闭包。
  *
  * 两个读面都把"这一趟看不见语料"写成显式的 {@link CorpusRead}：`{ available: false }` 与
- * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `CONTEXT.md` 的「语料缺席」**。
+ * "看见了、里面是空的"是两件事。**缺席之后怎么办归调用方，清单见 `docs/architecture.md` §2 的「语料缺席」**。
  */
 export interface HostCorpusPort {
     /** 整个会话语料（live ∪ persisted）的只读身份表。**服务缺席是显式的**：`sessionQuery` 没挂，或它的
@@ -84,6 +73,9 @@ export interface HostCorpusPort {
 }
 /** 复合别名：adapter（`createHostPort`）与调用方把这 15 个方法当一个端口用；三个角色是它的切面。 */
 export type HostPort = HostIdentityPort & HostPresencePort & HostCorpusPort;
+/** 动词的宿主面：身份与语料两片；不含在场三件。摘活体与通告只经 `CoreDeps.presence`（`PresenceCapability`）。
+ *  用交集而不是 `Omit` 黑名单：`HostPresencePort` 将来长出新方法时，不会自动漏进每个动词的 `host`。 */
+export type HostCorePort = HostIdentityPort & HostCorpusPort;
 export interface SessionIdentity {
     readonly sessionId: string;
     readonly parentSessionId?: string;
@@ -94,40 +86,20 @@ export interface SubagentMember {
     readonly sessionId: string;
     readonly projectDir: string;
 }
-/** 无 cwd 的会话落在 `<sessions>/_no-cwd/`（asar `dsh-session-persistence-jsonl/lib/index.js`
- *  的 `projectDir(root, cwd)`：`if (cwd === void 0) return join(root, "_no-cwd");`）。
- *  `projectDirOf` 与回收站对账（`src/trash/reconcile.ts` 重建条目）共用这一个字面量。 */
+/** 无 cwd 的会话落在 `_no-cwd/`；`projectDirOf` 与回收站对账共用这个字面量。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectDir`（`if (cwd === void 0) return join(root, "_no-cwd");`）。 */
 export declare const NO_CWD_PROJECT_DIR = "_no-cwd";
-/**
- * 宿主的**项目目录名**算法（`projectKey`）逐字镜像。
- *
- * 为什么是镜像而不是 import：它在 `@deepseek-ai/dsh-session-persistence-jsonl` 里面，是**宿主包**，
- * 跨插件值 import 是生态红线，它也不在本插件依赖里；宿主没有把这个名字暴露成任何服务
- * （`stat()`/`list()` 的返回只有 `{header, revision, sizeBytes}`，`locate()` 的 `{kind:'jsonl', path}` 只挂在错误上）。
- *
- * 原文（asar `dsh/node_modules/@deepseek-ai/dsh-session-persistence-jsonl/lib/index.js`）：
- * `function projectKey(cwd) { … if (ch === "/" || ch === "\\" || ch === ":") { if (!separatorRun) readable += "-"; separatorRun = true; }
- *  else if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) { readable += ch; separatorRun = false; }
- *  else { readable += "~" + code.toString(16).toUpperCase().padStart(4, "0"); separatorRun = false; }
- *  return \`--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--\`; }`
- * 调用链：`locate(meta)` → `logPath(root, meta.cwd, meta.id, …)` → `projectDir(root, cwd)` → `projectKey(cwd)`。
- * 本机实测对得上：`D:/develop/GitHub/dsh-session-delete` → `--D-develop-GitHub-dsh-session-delete--`
- * （`~/.dsh/sessions` 下真有这个目录名；`D:/document/deepseek-harness/default-workspace` 同理）。
- *
- * **两个调用方共用这一份**：`projectDirOf`（删除时定位会话目录）与回收站对账的重建路径
- * （手工放进回收站的目录，从日志 header 的 `cwd` 反推它原本属于哪个项目目录）——算法只有这一处家。
- */
+/** 宿主 `projectKey(cwd)` 的逐字镜像：跨插件不能 import，宿主也没把它暴露成服务。
+ *  出处：asar `dsh-session-persistence-jsonl/lib/index.js` 的 `projectKey`；调用链
+ *  `locate` → `logPath` → `projectDir` → `projectKey`。本机实测 `D:/develop/GitHub/dsh-session-delete`
+ *  → `--D-develop-GitHub-dsh-session-delete--`。`projectDirOf` 与回收站对账重建共用这一份；
+ *  宿主换代先复核算法。 */
 export declare function projectKey(cwd: string): string;
 /** 会话 id 去掉 `session-` 前缀后的形状（同一个父在两代里写法不同，见 {@link HostCorpusPort.subagentMembersOf}）。 */
 export declare function bareSessionId(id: string): string;
 /** 这次失败是不是"账本里没那个工作区"（而不是另有故障）。恢复侧靠它把两种失败分开：
  *  前者按「未分组」收，后者照旧回滚报 `io`——不给真故障静默改归属的机会。 */
 export declare function isWorkspaceMissingError(error: unknown): boolean;
-/**
- * 宿主服务层的**真实绑定**：各方法把动词层的问题翻成宿主官方服务的调用。
- *
- * 每个方法的依据（服务 / 方法 / 入参）与原文切片见各自的实现处注释。
- * 出错一律**原样抛**（不在这里裹动词码）：动词层把原始错误挂在 `cause` 上，
- * `toRemoteFailure` 再按 `name` 把它映射回 `sessiondelete/<码>`（src/remote/map-error.ts 的两行映射）。
- */
+/** 宿主服务的真实绑定；出错原样抛，由 `toRemoteFailure` 按 name 映射。
+ *  各方法调用的服务与方法见上方成员注释；错误映射表住 `src/remote/map-error.ts`。 */
 export declare function createHostPort(ctx: unknown): HostPort;

package/lib/types/ports/presence-port.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 在场能力：动词只拿到「成员离场 / 归位 / 一批归位」三条，不再拿到宿主的 `evictLive` / `announce*`。
+ *
+ * 生产实现住 `src/verbs/member-presence.ts`；组合根装配一次，挂在 `CoreDeps.presence`。这样
+ * “谁可以摘活体、谁可以发通告”由依赖面回答，而不是靠源码扫描维持。
+ */
+export interface MemberBackFacts {
+    readonly diskBack: boolean;
+    readonly workspaceBack: boolean;
+}
+export interface PresenceCapability {
+    /** 成员已经不在宿主可见列表：摘活体；三态不是 unknown 时发 removed。
+     *  `backInTrash: false` 表示目录没退回回收站（恢复回滚失败），此时什么都不做；`facts` 缺席按
+     *  「正常退回」处理（`createMemberPresence` 的缺省），不再留第三种含义。 */
+    memberGone(sessionId: string, facts?: {
+        readonly backInTrash: boolean;
+    }): Promise<void>;
+    /** 成员已经回到原来的可见状态：目录与账本两件写都回去才发 added。 */
+    memberBack(sessionId: string, facts: MemberBackFacts): Promise<void>;
+    /** 批量恢复的「回来了」通告；单条就是长度为 1 的批。 */
+    announceRestored(ids: readonly string[]): Promise<void>;
+}