dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/app/recycle-bin/recycle-bin-contract.d.ts

@@ -0,0 +1,247 @@
+/**
+ * 回收站服务的**契约**：依赖注入形状、目标/结果类型、索引状态。
+ *
+ * 从 `recycle-bin-service.ts` 抽出（审计 0076）。抽出的直接原因不是"文件太长"，而是
+ * 世界原语模块需要这些类型：留在 service 里会形成 `world → service`（type）与
+ * `service → world`（value）的环，架构测试会红。契约独立后方向单一。
+ *
+ * @module dsh-over-ssh/app/recycle-bin-contract
+ */
+import type { BackendEntry, BackendStat } from '../backend.ts';
+import { type RecycleBinEntry, type RecycleBinEntryId } from '../../domain/transfer/recycle-bin.ts';
+import { type RootRef } from '../../domain/roots/root.ts';
+export interface RecycleBinRemovalOptions {
+    /** Whether the target is a directory that must be removed with its content. */
+    readonly recursive: boolean;
+    /** Caller cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** The mutating primitives of one execution world, shaped like the remote group. */
+/**
+ * Serialize every read-modify-write of the bin index.
+ *
+ * ## Why this is a seam and not a mutex inside the service
+ *
+ * Two separate processes can drive the same bin: the plugin runs inside DSH, but the user may also have a
+ * second DSH (another port, a headless run) pointed at the same state directory. An in-process promise chain
+ * would serialize one process and still let the other interleave — that is exactly the hole
+ * `session-bin-lock.ts` was written to close for the **session** bin, and this bin has the same shape.
+ *
+ * The implementation is a cross-process file lock (see `createSessionBinLock`). Keeping it behind this seam
+ * means the domain service never imports `node:fs`, and tests can inject a no-op or a recording stub.
+ *
+ * @param key - the root being mutated; implementations may use it to pick a per-root lock file.
+ * @param operation - the critical section; must perform its own read **and** write inside it.
+ */
+export type WithIndexLock = <T>(key: string, operation: () => Promise<T>) => Promise<T>;
+export interface RecycleBinWorldIo {
+    /**
+     * Move (rename) a path.
+     *
+     * Contract: the implementation must create a missing destination parent directory (equivalent to
+     * `mkdir -p` + `rename`). A cross-device move that cannot be done by rename must **fail loudly**; silently
+     * degrading to copy-then-delete would break the "don't delete until it is in the bin" guarantee.
+     */
+    readonly move: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Physically delete a path. */
+    readonly remove: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List one directory. */
+    readonly list: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Read a text file (the index). */
+    readonly readText: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Write a text file as UTF-8 **without BOM** (the index). */
+    readonly writeText: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+}
+/** Everything {@link createRecycleBinService} needs; each field is injected so tests need no host. */
+export interface RecycleBinServiceDeps {
+    /** Bin root directory for one root; a deployment setting, never hardcoded here. */
+    readonly binRootFor: (root: RootRef) => string;
+    /** Find a root by its `rootKey()`; `undefined` means the root is no longer registered. */
+    readonly resolveRoot: (key: string) => RootRef | undefined;
+    /** `stat` in the local world. */
+    readonly statLocal: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** `stat` in the remote world. */
+    readonly statRemote: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** Move primitive of the remote world. */
+    readonly moveRemote: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Remove primitive of the remote world. */
+    readonly removeRemote: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List primitive of the remote world. */
+    readonly listRemote: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Index read primitive of the remote world. */
+    readonly readTextRemote: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Index write primitive of the remote world (UTF-8, no BOM). */
+    readonly writeTextRemote: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+    /** Clock, injected so a test can pin "now". */
+    readonly now: () => number;
+    /** Undo depth from configuration (a non-positive value keeps no history). */
+    readonly undoDepth: number;
+    /** Roots whose bins exist, so `sweep()` can walk them all. */
+    readonly knownRoots: () => readonly RootRef[];
+    /**
+     * Cross-process lock around every index read-modify-write.
+     *
+     * Optional so the domain service stays testable without touching the filesystem; when absent the service
+     * falls back to an in-process chain, which is **weaker** (it cannot see a second DSH process) and is
+     * therefore only acceptable in tests. Production wiring always injects the real lock.
+     */
+    readonly withIndexLock?: WithIndexLock;
+    /**
+     * Local-world mutators.
+     *
+     * Optional: a service built for remote work omits it, and touching a local target then fails with
+     * `REMOTE_UNSUPPORTED` instead of misapplying the remote primitives to a local path.
+     */
+    readonly localIo?: RecycleBinWorldIo;
+}
+/** One deletion target: a root plus a path inside it. */
+export interface RecycleBinTarget {
+    readonly root: RootRef;
+    /** Absolute path in the root's own spelling. */
+    readonly path: string;
+}
+/** A bin view scope: one root, optionally narrowed to targets deleted under one directory. */
+export interface RecycleBinScope {
+    readonly root: RootRef;
+    /** Optional directory prefix, matched per path segment. */
+    readonly path?: string;
+}
+/** How {@link RecycleBinService.discard} removes a target. */
+export type DiscardMode = 'permanent' | 'recycle';
+/** Options for {@link RecycleBinService.discard}. */
+export interface DiscardOptions {
+    readonly mode: DiscardMode;
+    readonly signal?: AbortSignal;
+}
+/** Result of a discard. */
+export interface DiscardResult {
+    readonly mode: DiscardMode;
+    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
+    readonly entry: RecycleBinEntry | undefined;
+    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
+    readonly recoverable: boolean;
+    /** Post-operation confirmation: the original path is gone. */
+    readonly verified: boolean;
+    /** Human-facing note, mandatory for an irreversible delete. */
+    readonly warning: string | undefined;
+}
+/** What a bin actually holds for one root. */
+export interface RecycleBinListing {
+    readonly entries: readonly RecycleBinEntry[];
+    /** Ids the index knows but the bin directory no longer contains. */
+    readonly missing: readonly RecycleBinEntryId[];
+    /** Directory names in the bin that no index record claims. */
+    readonly orphans: readonly string[];
+    /** Index records that were unusable and skipped. */
+    readonly skipped: number;
+}
+/** Result of a restore. */
+export interface RestoreResult {
+    readonly entry: RecycleBinEntry;
+    readonly restoredPath: string;
+    readonly verified: boolean;
+}
+/** Result of a physical delete from the bin. */
+export interface PurgeResult {
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    /** Always true when the call returns; a failed delete throws instead. */
+    readonly purged: boolean;
+    readonly warning: string;
+}
+/** Options for `list`, `restore`, `purge`, `undo` and `redo`. */
+export interface OperationOptions {
+    readonly signal?: AbortSignal;
+}
+/** Result of an undo or redo step. */
+export interface UndoResult {
+    /** The action that was executed. */
+    readonly action: 'discard' | 'restore';
+    readonly entry: RecycleBinEntry;
+    /** Human-facing description of what happened. */
+    readonly message: string;
+}
+/** Retention limits for one sweep; all optional. */
+export interface SweepOptions {
+    /** Keep at most this many entries per bin; non-positive/absent = unlimited. */
+    readonly maxEntries?: number;
+    /** Keep at most this many bytes per bin; non-positive/absent = unlimited. */
+    readonly maxBytes?: number;
+    /** Keep entries at most this old; non-positive/absent = unlimited. */
+    readonly maxAgeMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** One entry physically removed by a sweep. */
+export interface SweepPurge {
+    readonly rootKey: string;
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    readonly dimension: 'age' | 'count' | 'bytes';
+}
+/** One entry a sweep could not delete; the sweep continues with the rest. */
+export interface SweepFailure {
+    readonly rootKey: string;
+    readonly id?: RecycleBinEntryId;
+    readonly message: string;
+}
+/** Per-root summary of a sweep. */
+export interface SweepRootReport {
+    readonly rootKey: string;
+    readonly considered: number;
+    readonly purged: readonly RecycleBinEntryId[];
+    readonly kept: readonly RecycleBinEntryId[];
+    readonly reasons: readonly {
+        readonly id: RecycleBinEntryId;
+        readonly dimension: 'age' | 'count' | 'bytes';
+    }[];
+}
+/** Outcome of a sweep. */
+export interface SweepReport {
+    readonly purged: readonly SweepPurge[];
+    readonly roots: readonly SweepRootReport[];
+    readonly failures: readonly SweepFailure[];
+    /** `false` when no dimension was limited: no retention decision was made (an unconfigured 0 must not empty a bin). */
+    readonly policyApplied: boolean;
+    /**
+     * Empty entry directories removed because no index record claimed them.
+     *
+     * Reported separately from `purged` because these are garbage, not retention: they are pruned even when no
+     * limit is configured, and they were never recoverable (audit 0098).
+     */
+    readonly prunedOrphans: number;
+}
+/** Read-only undo state, for a UI that needs to enable or disable the buttons. */
+export interface RecycleBinHistory {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly undo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly redo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly dropped: number;
+    readonly undoDepth: number;
+}
+/** The service surface. */
+export interface RecycleBinService {
+    /** Delete a target permanently or into the recycle bin. */
+    discard(target: RecycleBinTarget, options: DiscardOptions): Promise<DiscardResult>;
+    /** List one bin, reconciled against the directory that actually exists. */
+    list(scope: RecycleBinScope, options?: OperationOptions): Promise<RecycleBinListing>;
+    /** Restore one entry to its original path. */
+    restore(id: RecycleBinEntryId, options?: OperationOptions): Promise<RestoreResult>;
+    /** Physically delete one entry from the bin. */
+    purge(id: RecycleBinEntryId, options?: OperationOptions): Promise<PurgeResult>;
+    /** Apply retention limits to every known bin. */
+    sweep(options: SweepOptions): Promise<SweepReport>;
+    /** Undo the newest operation. */
+    undo(options?: OperationOptions): Promise<UndoResult>;
+    /** Re-apply the newest undone operation. */
+    redo(options?: OperationOptions): Promise<UndoResult>;
+    /** Current undo/redo state. */
+    history(): RecycleBinHistory;
+}
+//# sourceMappingURL=recycle-bin-contract.d.ts.map

package/lib/types/src/host/app/recycle-bin/recycle-bin-move.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 回收站服务的**移动/恢复族**：把条目搬进 bin、搬回原处，含"移动后确认"与"索引写失败回滚"。
+ *
+ * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）。只依赖世界原语，不碰撤销栈。
+ *
+ * @module dsh-over-ssh/app/recycle-bin-move
+ */
+import { type RecycleBinEntry } from '../../domain/transfer/recycle-bin.ts';
+import { type RootRef } from '../../domain/roots/root.ts';
+import type { BinWorld } from './recycle-bin-world.ts';
+export declare function createBinMove(world: BinWorld): {
+    tryMove: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined) => Promise<boolean>;
+    moveOrReport: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined, reason: string) => Promise<void>;
+    confirmInBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+    moveIntoBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+    restoreEntry: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+};
+//# sourceMappingURL=recycle-bin-move.d.ts.map

package/lib/types/src/host/app/recycle-bin/recycle-bin-service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The recycle-bin service: the domain's pure decisions wired to injected I/O primitives.
+ *
+ * The seam is deliberate (AGENTS.md 红线 3): every path that touches a real filesystem or a real SSH
+ * connection arrives as a function, so this module is testable offline and a test can inject a move that fails.
+ *
+ * Two contracts matter more than the rest:
+ *
+ *  1. **Move first, then confirm.** In `recycle` mode a success is reported only after `stat` shows the entry
+ *     inside the bin **and** the original path gone. A move that throws is confirmed before anything is
+ *     claimed: if the move actually landed (a lost response) it counts as success, otherwise the call fails
+ *     and nothing is recorded — "deleted but not in the bin" must never be reported as success.
+ *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move
+ *     is rolled back and the failure is reported; a physical delete has no rollback, so that case is reported
+ *     with `purged: true, indexStale: true` instead of being hidden.
+ *
+ * Other decisions worth knowing:
+ *
+ *  - A `permanent` discard is irreversible by construction and says so in its result (`recoverable: false`),
+ *    and its undo record is refused as `irreversible`.
+ *  - Restoring onto an occupied original path is **refused** (`TRANSFER_CONFLICT`, with the informational
+ *    `suggestedPath` in `details`); this module never silently restores to a different name.
+ *  - `*Remote` primitives are the **remote world's** mutators. A local root additionally needs `localIo`; when it
+ *    is missing the call fails with `REMOTE_UNSUPPORTED` rather than reusing remote primitives on local paths.
+ *  - Every destructive call takes an `AbortSignal`, propagated to every injected primitive.
+ *  - Error codes are reused from the existing table (no new code is registered): `TRASH_NOT_FOUND` (missing
+ *    entry, unreadable index), `REMOTE_NOT_FOUND` (target gone), `TRANSFER_CONFLICT` (occupied restore path),
+ *    `ROOT_OUTSIDE` (symlink target refused), `ROOT_AMBIGUOUS` (one id in two bins), `REMOTE_UNSUPPORTED`
+ *    (local root without local primitives), `REMOTE_COMMAND_FAILED` (an operation that could not be confirmed),
+ *    `ROOT_INVALID` (unusable configuration/input), `CANCELLED` (aborted signal).
+ *
+ * @module dsh-over-ssh/integration/recycle-bin-service
+ */
+import type { RecycleBinServiceDeps, RecycleBinService } from './recycle-bin-contract.ts';
+export * from './recycle-bin-contract.ts';
+/** Removal options for one physical delete. */
+export * from './recycle-bin-contract.ts';
+/**
+ * Build the service.
+ *
+ * @param deps - injected I/O, clock, configuration and root lookup.
+ * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
+ */
+export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;
+//# sourceMappingURL=recycle-bin-service.d.ts.map

package/lib/types/src/host/app/recycle-bin/recycle-bin-world.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 回收站服务的**世界原语**：索引读写、按根取 IO、stat、根查找。
+ *
+ * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）：只依赖 deps，不碰撤销栈与业务判断。
+ *
+ * @module dsh-over-ssh/app/recycle-bin-world
+ */
+import type { BackendStat } from '../backend.ts';
+import { type RecycleBinEntry, type RecycleBinEntryId } from '../../domain/transfer/recycle-bin.ts';
+import { type RootRef } from '../../domain/roots/root.ts';
+import type { RecycleBinServiceDeps, RecycleBinWorldIo, RecycleBinRemovalOptions } from './recycle-bin-contract.ts';
+export type IndexState = {
+    readonly path: string;
+    readonly entries: readonly RecycleBinEntry[];
+    readonly skipped: number;
+};
+export declare function createBinWorld(deps: RecycleBinServiceDeps): {
+    describe: (error: unknown) => string;
+    abortIfRequested: (signal: AbortSignal | undefined) => void;
+    ioFor: (root: RootRef) => RecycleBinWorldIo;
+    statFor: (root: RootRef, path: string, signal: AbortSignal | undefined) => Promise<BackendStat>;
+    binRootOf: (root: RootRef) => string;
+    readIndex: (root: RootRef, signal: AbortSignal | undefined) => Promise<IndexState>;
+    writeIndex: (root: RootRef, path: string, entries: readonly RecycleBinEntry[], signal: AbortSignal | undefined) => Promise<void>;
+    withIndexLock: <T>(key: string, operation: () => Promise<T>) => Promise<T>;
+    removalOptions: (recursive: boolean, signal: AbortSignal | undefined) => RecycleBinRemovalOptions;
+    knownRoots: () => readonly RootRef[];
+    resolveRootOf: (key: string) => RootRef;
+    findEntry: (id: RecycleBinEntryId, signal: AbortSignal | undefined) => Promise<{
+        readonly root: RootRef;
+        readonly entry: RecycleBinEntry;
+    } | undefined>;
+    contains: (root: RootRef, base: string, candidate: string) => boolean;
+    entryDirOf: (entry: RecycleBinEntry) => string;
+    pruneEntryDir: (root: RootRef, dir: string, signal: AbortSignal | undefined) => Promise<boolean>;
+};
+export type BinWorld = ReturnType<typeof createBinWorld>;
+//# sourceMappingURL=recycle-bin-world.d.ts.map

package/lib/types/src/host/app/recycle-bin-contract.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 回收站服务的**契约**：依赖注入形状、目标/结果类型、索引状态。
+ *
+ * 从 `recycle-bin-service.ts` 抽出（审计 0076）。抽出的直接原因不是"文件太长"，而是
+ * 世界原语模块需要这些类型：留在 service 里会形成 `world → service`（type）与
+ * `service → world`（value）的环，架构测试会红。契约独立后方向单一。
+ *
+ * @module dsh-remote-workspace/app/recycle-bin-contract
+ */
+import type { BackendEntry, BackendStat } from './backend.ts';
+import { type RecycleBinEntry, type RecycleBinEntryId } from '../domain/recycle-bin.ts';
+import { type RootRef } from '../domain/root.ts';
+export interface RecycleBinRemovalOptions {
+    /** Whether the target is a directory that must be removed with its content. */
+    readonly recursive: boolean;
+    /** Caller cancellation. */
+    readonly signal?: AbortSignal;
+}
+/** The mutating primitives of one execution world, shaped like the remote group. */
+export interface RecycleBinWorldIo {
+    /**
+     * Move (rename) a path.
+     *
+     * Contract: the implementation must create a missing destination parent directory (equivalent to
+     * `mkdir -p` + `rename`). A cross-device move that cannot be done by rename must **fail loudly**; silently
+     * degrading to copy-then-delete would break the "don't delete until it is in the bin" guarantee.
+     */
+    readonly move: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Physically delete a path. */
+    readonly remove: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List one directory. */
+    readonly list: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Read a text file (the index). */
+    readonly readText: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Write a text file as UTF-8 **without BOM** (the index). */
+    readonly writeText: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+}
+/** Everything {@link createRecycleBinService} needs; each field is injected so tests need no host. */
+export interface RecycleBinServiceDeps {
+    /** Bin root directory for one root; a deployment setting, never hardcoded here. */
+    readonly binRootFor: (root: RootRef) => string;
+    /** Find a root by its `rootKey()`; `undefined` means the root is no longer registered. */
+    readonly resolveRoot: (key: string) => RootRef | undefined;
+    /** `stat` in the local world. */
+    readonly statLocal: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** `stat` in the remote world. */
+    readonly statRemote: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
+    /** Move primitive of the remote world. */
+    readonly moveRemote: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
+    /** Remove primitive of the remote world. */
+    readonly removeRemote: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
+    /** List primitive of the remote world. */
+    readonly listRemote: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
+    /** Index read primitive of the remote world. */
+    readonly readTextRemote: (path: string, signal?: AbortSignal) => Promise<string>;
+    /** Index write primitive of the remote world (UTF-8, no BOM). */
+    readonly writeTextRemote: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
+    /** Clock, injected so a test can pin "now". */
+    readonly now: () => number;
+    /** Undo depth from configuration (a non-positive value keeps no history). */
+    readonly undoDepth: number;
+    /** Roots whose bins exist, so `sweep()` can walk them all. */
+    readonly knownRoots: () => readonly RootRef[];
+    /**
+     * Local-world mutators.
+     *
+     * Optional: a service built for remote work omits it, and touching a local target then fails with
+     * `REMOTE_UNSUPPORTED` instead of misapplying the remote primitives to a local path.
+     */
+    readonly localIo?: RecycleBinWorldIo;
+}
+/** One deletion target: a root plus a path inside it. */
+export interface RecycleBinTarget {
+    readonly root: RootRef;
+    /** Absolute path in the root's own spelling. */
+    readonly path: string;
+}
+/** A bin view scope: one root, optionally narrowed to targets deleted under one directory. */
+export interface RecycleBinScope {
+    readonly root: RootRef;
+    /** Optional directory prefix, matched per path segment. */
+    readonly path?: string;
+}
+/** How {@link RecycleBinService.discard} removes a target. */
+export type DiscardMode = 'permanent' | 'recycle';
+/** Options for {@link RecycleBinService.discard}. */
+export interface DiscardOptions {
+    readonly mode: DiscardMode;
+    readonly signal?: AbortSignal;
+}
+/** Result of a discard. */
+export interface DiscardResult {
+    readonly mode: DiscardMode;
+    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
+    readonly entry: RecycleBinEntry | undefined;
+    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
+    readonly recoverable: boolean;
+    /** Post-operation confirmation: the original path is gone. */
+    readonly verified: boolean;
+    /** Human-facing note, mandatory for an irreversible delete. */
+    readonly warning: string | undefined;
+}
+/** What a bin actually holds for one root. */
+export interface RecycleBinListing {
+    readonly entries: readonly RecycleBinEntry[];
+    /** Ids the index knows but the bin directory no longer contains. */
+    readonly missing: readonly RecycleBinEntryId[];
+    /** Directory names in the bin that no index record claims. */
+    readonly orphans: readonly string[];
+    /** Index records that were unusable and skipped. */
+    readonly skipped: number;
+}
+/** Result of a restore. */
+export interface RestoreResult {
+    readonly entry: RecycleBinEntry;
+    readonly restoredPath: string;
+    readonly verified: boolean;
+}
+/** Result of a physical delete from the bin. */
+export interface PurgeResult {
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    /** Always true when the call returns; a failed delete throws instead. */
+    readonly purged: boolean;
+    readonly warning: string;
+}
+/** Options for `list`, `restore`, `purge`, `undo` and `redo`. */
+export interface OperationOptions {
+    readonly signal?: AbortSignal;
+}
+/** Result of an undo or redo step. */
+export interface UndoResult {
+    /** The action that was executed. */
+    readonly action: 'discard' | 'restore';
+    readonly entry: RecycleBinEntry;
+    /** Human-facing description of what happened. */
+    readonly message: string;
+}
+/** Retention limits for one sweep; all optional. */
+export interface SweepOptions {
+    /** Keep at most this many entries per bin; non-positive/absent = unlimited. */
+    readonly maxEntries?: number;
+    /** Keep at most this many bytes per bin; non-positive/absent = unlimited. */
+    readonly maxBytes?: number;
+    /** Keep entries at most this old; non-positive/absent = unlimited. */
+    readonly maxAgeMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** One entry physically removed by a sweep. */
+export interface SweepPurge {
+    readonly rootKey: string;
+    readonly id: RecycleBinEntryId;
+    readonly sizeBytes: number;
+    readonly dimension: 'age' | 'count' | 'bytes';
+}
+/** One entry a sweep could not delete; the sweep continues with the rest. */
+export interface SweepFailure {
+    readonly rootKey: string;
+    readonly id?: RecycleBinEntryId;
+    readonly message: string;
+}
+/** Per-root summary of a sweep. */
+export interface SweepRootReport {
+    readonly rootKey: string;
+    readonly considered: number;
+    readonly purged: readonly RecycleBinEntryId[];
+    readonly kept: readonly RecycleBinEntryId[];
+    readonly reasons: readonly {
+        readonly id: RecycleBinEntryId;
+        readonly dimension: 'age' | 'count' | 'bytes';
+    }[];
+}
+/** Outcome of a sweep. */
+export interface SweepReport {
+    readonly purged: readonly SweepPurge[];
+    readonly roots: readonly SweepRootReport[];
+    readonly failures: readonly SweepFailure[];
+    /** `false` when no dimension was limited: nothing was touched (an unconfigured 0 must not empty a bin). */
+    readonly policyApplied: boolean;
+}
+/** Read-only undo state, for a UI that needs to enable or disable the buttons. */
+export interface RecycleBinHistory {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly undo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly redo: readonly {
+        readonly kind: string;
+        readonly id: string;
+    }[];
+    readonly dropped: number;
+    readonly undoDepth: number;
+}
+/** The service surface. */
+export interface RecycleBinService {
+    /** Delete a target permanently or into the recycle bin. */
+    discard(target: RecycleBinTarget, options: DiscardOptions): Promise<DiscardResult>;
+    /** List one bin, reconciled against the directory that actually exists. */
+    list(scope: RecycleBinScope, options?: OperationOptions): Promise<RecycleBinListing>;
+    /** Restore one entry to its original path. */
+    restore(id: RecycleBinEntryId, options?: OperationOptions): Promise<RestoreResult>;
+    /** Physically delete one entry from the bin. */
+    purge(id: RecycleBinEntryId, options?: OperationOptions): Promise<PurgeResult>;
+    /** Apply retention limits to every known bin. */
+    sweep(options: SweepOptions): Promise<SweepReport>;
+    /** Undo the newest operation. */
+    undo(options?: OperationOptions): Promise<UndoResult>;
+    /** Re-apply the newest undone operation. */
+    redo(options?: OperationOptions): Promise<UndoResult>;
+    /** Current undo/redo state. */
+    history(): RecycleBinHistory;
+}
+//# sourceMappingURL=recycle-bin-contract.d.ts.map

package/lib/types/src/host/app/recycle-bin-move.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 回收站服务的**移动/恢复族**：把条目搬进 bin、搬回原处，含"移动后确认"与"索引写失败回滚"。
+ *
+ * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）。只依赖世界原语，不碰撤销栈。
+ *
+ * @module dsh-remote-workspace/app/recycle-bin-move
+ */
+import { type RecycleBinEntry } from '../domain/recycle-bin.ts';
+import { type RootRef } from '../domain/root.ts';
+import type { BinWorld } from './recycle-bin-world.ts';
+export declare function createBinMove(world: BinWorld): {
+    tryMove: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined) => Promise<boolean>;
+    moveOrReport: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined, reason: string) => Promise<void>;
+    confirmInBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+    moveIntoBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+    restoreEntry: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
+};
+//# sourceMappingURL=recycle-bin-move.d.ts.map

package/lib/types/src/host/app/recycle-bin-service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The recycle-bin service: the domain's pure decisions wired to injected I/O primitives.
+ *
+ * The seam is deliberate (AGENTS.md 红线 3): every path that touches a real filesystem or a real SSH
+ * connection arrives as a function, so this module is testable offline and a test can inject a move that fails.
+ *
+ * Two contracts matter more than the rest:
+ *
+ *  1. **Move first, then confirm.** In `recycle` mode a success is reported only after `stat` shows the entry
+ *     inside the bin **and** the original path gone. A move that throws is confirmed before anything is
+ *     claimed: if the move actually landed (a lost response) it counts as success, otherwise the call fails
+ *     and nothing is recorded — "deleted but not in the bin" must never be reported as success.
+ *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move
+ *     is rolled back and the failure is reported; a physical delete has no rollback, so that case is reported
+ *     with `purged: true, indexStale: true` instead of being hidden.
+ *
+ * Other decisions worth knowing:
+ *
+ *  - A `permanent` discard is irreversible by construction and says so in its result (`recoverable: false`),
+ *    and its undo record is refused as `irreversible`.
+ *  - Restoring onto an occupied original path is **refused** (`TRANSFER_CONFLICT`, with the informational
+ *    `suggestedPath` in `details`); this module never silently restores to a different name.
+ *  - `*Remote` primitives are the **remote world's** mutators. A local root additionally needs `localIo`; when it
+ *    is missing the call fails with `REMOTE_UNSUPPORTED` rather than reusing remote primitives on local paths.
+ *  - Every destructive call takes an `AbortSignal`, propagated to every injected primitive.
+ *  - Error codes are reused from the existing table (no new code is registered): `TRASH_NOT_FOUND` (missing
+ *    entry, unreadable index), `REMOTE_NOT_FOUND` (target gone), `TRANSFER_CONFLICT` (occupied restore path),
+ *    `ROOT_OUTSIDE` (symlink target refused), `ROOT_AMBIGUOUS` (one id in two bins), `REMOTE_UNSUPPORTED`
+ *    (local root without local primitives), `REMOTE_COMMAND_FAILED` (an operation that could not be confirmed),
+ *    `ROOT_INVALID` (unusable configuration/input), `CANCELLED` (aborted signal).
+ *
+ * @module dsh-remote-workspace/integration/recycle-bin-service
+ */
+import type { RecycleBinServiceDeps, RecycleBinService } from './recycle-bin-contract.ts';
+export * from './recycle-bin-contract.ts';
+/** Removal options for one physical delete. */
+export * from './recycle-bin-contract.ts';
+/**
+ * Build the service.
+ *
+ * @param deps - injected I/O, clock, configuration and root lookup.
+ * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
+ */
+export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;
+//# sourceMappingURL=recycle-bin-service.d.ts.map

package/lib/types/src/host/app/recycle-bin-world.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 回收站服务的**世界原语**：索引读写、按根取 IO、stat、根查找。
+ *
+ * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）：只依赖 deps，不碰撤销栈与业务判断。
+ *
+ * @module dsh-remote-workspace/app/recycle-bin-world
+ */
+import type { BackendStat } from './backend.ts';
+import { type RecycleBinEntry, type RecycleBinEntryId } from '../domain/recycle-bin.ts';
+import { type RootRef } from '../domain/root.ts';
+import type { RecycleBinServiceDeps, RecycleBinWorldIo, RecycleBinRemovalOptions } from './recycle-bin-contract.ts';
+export type IndexState = {
+    readonly path: string;
+    readonly entries: readonly RecycleBinEntry[];
+    readonly skipped: number;
+};
+export declare function createBinWorld(deps: RecycleBinServiceDeps): {
+    describe: (error: unknown) => string;
+    abortIfRequested: (signal: AbortSignal | undefined) => void;
+    ioFor: (root: RootRef) => RecycleBinWorldIo;
+    statFor: (root: RootRef, path: string, signal: AbortSignal | undefined) => Promise<BackendStat>;
+    binRootOf: (root: RootRef) => string;
+    readIndex: (root: RootRef, signal: AbortSignal | undefined) => Promise<IndexState>;
+    writeIndex: (root: RootRef, path: string, entries: readonly RecycleBinEntry[], signal: AbortSignal | undefined) => Promise<void>;
+    removalOptions: (recursive: boolean, signal: AbortSignal | undefined) => RecycleBinRemovalOptions;
+    knownRoots: () => readonly RootRef[];
+    resolveRootOf: (key: string) => RootRef;
+    findEntry: (id: RecycleBinEntryId, signal: AbortSignal | undefined) => Promise<{
+        readonly root: RootRef;
+        readonly entry: RecycleBinEntry;
+    } | undefined>;
+    contains: (root: RootRef, base: string, candidate: string) => boolean;
+};
+export type BinWorld = ReturnType<typeof createBinWorld>;
+//# sourceMappingURL=recycle-bin-world.d.ts.map