dsh-over-ssh 0.0.0-stage → 0.1.1

package/lib/types/src/host/domain/session/session-admin.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Session administration: inventory, hierarchy classification, delete plans and restore plans — pure logic only.
+ *
+ * Requirement FR-3.3–3.10 asks for a *session* recycle bin, which is a different thing from the existing
+ * *file-level* recycle bin in [`recycle-bin.ts`](./recycle-bin.ts) (see ADR-0009): that one moves one path
+ * inside a root, this one moves a whole session directory out of the platform's session store.
+ *
+ * ## The two facts everything here is built on
+ *
+ *  1. **`projectKey` is lossy.** The platform folds separators and truncates at 251 chars, so a directory
+ *     name **cannot** be decoded back into a `cwd`. Every classification therefore reads the session
+ *     **header**, never the directory name. (The encoder is reproduced in {@link projectKey} and was checked
+ *     against the real store 6/6 — see ADR-0009.)
+ *  2. **A bin entry has two directory names.** `segment` is where it lives *inside the bin*; `originalSegment` A top-level session id carries a `session-` prefix while a
+ *     sub-session id is a bare uuid, but the requirement is explicit that this must **not** be used to infer
+ *     hierarchy: `origin`/`parentSession` from the header is the only authority.
+ *
+ * Everything in this module is a pure function over already-read data: no filesystem, no clock, no I/O.
+ *
+ * @module dsh-over-ssh/domain/session-admin
+ */
+/**
+ * Reproduce the platform's `projectKey(cwd)` (source: `dsh-session-persistence-jsonl` `projectKey`).
+ *
+ * Rules: runs of `/`, `\` and `:` collapse to one `-`; `[A-Za-z0-9._-]` (except `~`) stay; everything else
+ * becomes `~XXXX` (4 uppercase hex digits of the UTF-16 code unit); leading `-` are dropped; empty becomes
+ * `root`; the body is truncated to 251 chars; the result is wrapped in `--…--`.
+ *
+ * **Lossy on purpose** (the platform says so too): two different `cwd` values can share one key. This
+ * function exists so the plugin can *compute* the directory a session lives in, never to decode one.
+ *
+ * @param cwd - the session's project directory (an absolute path).
+ * @returns the project directory name.
+ * @throws SshDevError `ROOT_INVALID` for an empty path (the platform refuses it too).
+ */
+export declare function projectKey(cwd: string): string;
+/**
+ * Reproduce the platform's `encodeSegment(id)` (source: `dsh-session-persistence-jsonl`).
+ *
+ * Unlike {@link projectKey} this one is **injective**: `.` becomes `~002E` (so `.`/`..` cannot escape the
+ * directory), safe characters pass through, everything else becomes `~XXXX`. A `session-` prefix is
+ * therefore preserved verbatim — which is exactly why hierarchy must not be read from it.
+ *
+ * @param id - the session id.
+ * @returns the directory name.
+ */
+export declare function encodeSegment(id: string): string;
+/**
+ * The directory one session lives in, relative to the sessions root.
+ *
+ * `cwd === undefined` selects the platform's `_no-cwd` bucket (the platform's own convention).
+ *
+ * @param cwd - the session's project directory, or `undefined` for the no-cwd bucket.
+ * @param id - the session id.
+ * @returns the path segments, root-relative.
+ */
+export declare function sessionSegments(cwd: string | undefined, id: string): readonly string[];
+/**
+ * Classify one inventory record.
+ *
+ * The only authority is the header: `parentSessionId` present ⇒ sub-session. A record whose header could not
+ * be read is `unreadable`. The directory name is deliberately **not** consulted — `session-`-prefixed ids are
+ * top-level sessions, but the requirement forbids inferring hierarchy from that, and a future id scheme would
+ * silently break such an inference.
+ *
+ * @param record - a record without its `classification` field.
+ * @returns the class.
+ */
+export declare function classifySession(record: Omit<SessionRecord, 'classification'> & {
+    readonly readable?: boolean;
+}): SessionClass;
+/** How one session relates to the rest of the store. */
+export type SessionClass = 
+/** A normal, independently-visible session. */
+'normal'
+/** A sub-session: its lifecycle follows its parent, so it must not be deleted on its own. */
+ | 'subsession'
+/** A directory whose header could not be read (corrupt or unsupported format). */
+ | 'unreadable';
+/** One session as the inventory sees it. */
+export interface SessionRecord {
+    readonly id: string;
+    /** Project directory the log was found under, as spelled on disk. */
+    readonly projectDir: string;
+    /** Directory name (`encodeSegment(id)`) the log was found under. */
+    readonly segment: string;
+    /** `cwd` from the header; `undefined` for the no-cwd bucket. */
+    readonly cwd: string | undefined;
+    /** The session's own title (the platform's `title` projection), when one was ever generated. */
+    readonly title: string | undefined;
+    /**
+     * Display title of the workspace owning {@link cwd}, resolved from the platform's workspace registry.
+     *
+     * `undefined` when the caller supplied no resolver or no registered workspace owns the directory. The
+     * directory itself is still on the wire (`cwd`), so a reader falls back to its own leaf name.
+     */
+    readonly workspaceTitle: string | undefined;
+    /** Parent session id from the header, when this is a sub-session. */
+    readonly parentSessionId: string | undefined;
+    /** Total bytes of the log files in the session directory (0 when unknown). */
+    readonly bytes: number;
+    /** Modification time of the newest log file, in ms since the epoch. */
+    readonly updatedAtMs: number;
+    /**
+     * True when the host holds this session in its store — it was opened in this DSH process.
+     *
+     * Loaded is **not** running: the platform keeps an agent for every session opened since the process
+     * started, and an idle agent is doing nothing. The panel renders this as 已打开, and an idle loaded
+     * session stays deletable.
+     */
+    readonly live: boolean;
+    /**
+     * True when this session's agent is running a turn (`agents.get(id)?.status === 'running'`).
+     *
+     * This is the platform's own "运行中" signal — the one the session list uses for a row's status — and the
+     * only state that must refuse deletion (FR-3.6).
+     */
+    readonly running: boolean;
+    /** How this session relates to the store (see {@link classifySession}). */
+    readonly classification: SessionClass;
+}
+/** Why one session may not be deleted. */
+export type DeleteRefusal = 
+/** Its agent is running a turn: the platform has no public way to unload one (see FR-3.6). */
+'running'
+/** It is a sub-session: delete its parent instead. */
+ | 'subsession'
+/** Its log could not be read, so deleting it would be guesswork. */
+ | 'unreadable'
+/** The caller asked to keep a session that this operation would have removed. */
+ | 'protected';
+/** The pure decision for one deletion. */
+export interface DeleteDecision {
+    /** Ids to delete, **children before parents** (so a parent never outlives its children). */
+    readonly delete: readonly string[];
+    /** One refusal per skipped id, in the order the ids were considered. */
+    readonly refusals: readonly {
+        readonly id: string;
+        readonly reason: DeleteRefusal;
+    }[];
+    /** Total bytes the deletion will free, counting only the ids in `delete`. */
+    readonly bytes: number;
+}
+/**
+ * Decide what a deletion request would actually do, without touching anything.
+ *
+ * The rules, in order:
+ *
+ *  1. an id that is not in the inventory is refused as `unreadable` (it was never a session here);
+ *  2. a **running** session is refused (`running`) — FR-3.6 requires blocking rather than killing, because the
+ *     platform exposes no way to unload a live agent, and the requirement is explicit that
+ *     "stop and delete" is *not* offered this round. Loaded-but-idle is **not** refused: the host keeps an
+ *     agent for every session opened since it started, so refusing those would make nearly every session
+ *     undeletable, and a session that is doing nothing cannot be interrupted;
+ *  3. an `unreadable` record is refused (`unreadable`) — deleting a directory we could not identify is
+ *     exactly the kind of irreversible guess this feature must not make;
+ *  4. a sub-session is refused (`subsession`) when it is selected **on its own** (FR-3.3: 子会话随父会话管理，
+ *     默认不可被单独删除);
+ *  5. selecting a parent **always** takes its whole descendant subtree along, ordered **children first**.
+ *
+ * Rule 5 is unconditional on purpose. It used to be an opt-in `includeSubsessions` switch, and that was the
+ * wrong shape: leaving a parent's children behind orphans their logs — the parent is gone, so nothing
+ * navigates to them, and the platform's listing hides them by `parentId` nesting, so the bytes stay on disk
+ * and invisible forever. FR-3.3 asks for sub-sessions to be "随父会话管理" and the requirement's own §7
+ * recommendation is "删除父会话时提示将一并处理 N 个子会话": always together, with the count shown.
+ *
+ * A sub-session that was explicitly requested *and* pulled in by its parent is deleted and **not** reported
+ * as a refusal — otherwise the caller would see a row refused and deleted in the same answer.
+ *
+ * **A subtree is atomic.** If any descendant of a requested session is running or protected, the whole
+ * request for that session is refused instead of deleting the ancestor and orphaning the descendant: a
+ * running child whose parent is gone can never be reached again (the listing nests children under their
+ * parent), and a protected one was explicitly asked to be spared. Refusing the parent is the only outcome
+ * that keeps both promises (FR-3.6 never interrupts a running agent; `keep` is honoured).
+ *
+ * `keep` wins over everything: an id listed there is refused as `protected` even if it is an idle normal
+ * session. It exists so a UI can show a preview and let the user uncheck rows.
+ *
+ * @param records - the full inventory.
+ * @param request - ids to delete, plus the optional keep list.
+ * @returns the decision; `delete` is empty when everything was refused.
+ */
+export declare function planDelete(records: readonly SessionRecord[], request: {
+    readonly ids: readonly string[];
+    readonly keep?: readonly string[];
+}): DeleteDecision;
+/** Index file name inside the session bin root. */
+export declare const SESSION_TRASH_INDEX_FILE = "index.json";
+/** Version stamped into the session bin index; a different version is a hard parse failure. */
+export declare const SESSION_TRASH_INDEX_VERSION = 1;
+/** Opaque identity of one session-bin entry. */
+export type SessionTrashEntryId = string & {
+    readonly __sessionTrashEntryId: 'SessionTrashEntryId';
+};
+/** One entry in the session recycle bin: everything a restore needs. */
+export interface SessionTrashEntry {
+    readonly id: SessionTrashEntryId;
+    /** The deleted session's id. */
+    readonly sessionId: string;
+    /**
+     * The session's `cwd` as recorded in its header, or `undefined` for the no-cwd bucket.
+     *
+     * Kept **verbatim** rather than as a `projectKey`: the key is lossy, so restoring from it could land the
+     * session under a different project directory than it came from.
+     */
+    readonly cwd: string | undefined;
+    /** Project directory name the session was moved out of. */
+    readonly projectDir: string;
+    /**
+     * Directory name **inside the bin**; the session directory is moved here wholesale.
+     *
+     * Equals the entry id in practice, and is **not** the store-side name — see `originalSegment`. Keeping the
+     * two apart is what makes a restore land back where it came from: using one for both would make the
+     * restored session appear under the entry id.
+     */
+    readonly segment: string;
+    /**
+     * The session's directory name **in the store** (`encodeSegment(sessionId)`), captured before the move.
+     *
+     * Stored rather than recomputed: `encodeSegment` is injective so recomputing would work today, but recording
+     * what was actually observed means a restore never depends on the encoder staying byte-identical.
+     */
+    readonly originalSegment: string;
+    readonly title: string | undefined;
+    /** Total bytes of the moved log files, for the retention policy. */
+    readonly bytes: number;
+    readonly deletedAtMs: number;
+    /** How the bytes were moved. `copy` means the move crossed a filesystem boundary. */
+    readonly movedBy: 'rename' | 'copy';
+    /** Who confirmed the deletion, when the caller supplied it (FR-3.10 auditability). */
+    readonly confirmedBy: string | undefined;
+}
+/**
+ * Derive a stable, filesystem-safe entry id.
+ *
+ * Deterministic on `(sessionId, deletedAtMs)` so a retried deletion of the same session at the same instant
+ * lands on the same entry instead of leaving two copies; {@link allocateSessionTrashEntryId} breaks genuine
+ * collisions.
+ *
+ * @param input - identity inputs.
+ * @returns the entry id.
+ */
+export declare function makeSessionTrashEntryId(input: {
+    readonly sessionId: string;
+    readonly deletedAtMs: number;
+}): SessionTrashEntryId;
+/**
+ * Allocate an id that is not already taken, by appending a counter.
+ *
+ * @param existing - ids already in the bin.
+ * @param input - identity inputs.
+ * @returns a free id.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the counter space is exhausted (never returns a taken id).
+ */
+export declare function allocateSessionTrashEntryId(existing: Iterable<string>, input: {
+    readonly sessionId: string;
+    readonly deletedAtMs: number;
+}): SessionTrashEntryId;
+/** The persisted session-bin index document. */
+export interface SessionTrashIndex {
+    readonly version: number;
+    readonly entries: readonly SessionTrashEntry[];
+}
+/** One index record the parser refused. */
+export interface SkippedSessionTrashRecord {
+    readonly index: number;
+    readonly reason: string;
+}
+/** Result of {@link parseSessionTrashIndex}. */
+export interface ParsedSessionTrashIndex {
+    readonly entries: readonly SessionTrashEntry[];
+    readonly skipped: readonly SkippedSessionTrashRecord[];
+}
+/**
+ * Serialize the session-bin index.
+ *
+ * Entries are sorted by id so the same set is byte-identical every time (diffable, testable).
+ *
+ * @param entries - entries to persist.
+ * @returns JSON text.
+ */
+export declare function serializeSessionTrashIndex(entries: readonly SessionTrashEntry[]): string;
+/**
+ * Parse the session-bin index.
+ *
+ * A malformed document or unknown version is a **hard failure** (the bin cannot be trusted, and guessing
+ * could delete the wrong directory); a single unusable record is skipped and reported, so one corrupt entry
+ * never hides the rest.
+ *
+ * @param text - index file content.
+ * @returns usable entries plus skipped records.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the document cannot be read as an index.
+ */
+export declare function parseSessionTrashIndex(text: string): ParsedSessionTrashIndex;
+/** The pure decision for restoring one entry. */
+export type RestoreSessionPlan = {
+    readonly kind: 'restore';
+    readonly entryId: SessionTrashEntryId;
+    readonly sessionId: string;
+    readonly projectDir: string;
+    /** Where it goes back to in the store (the original directory name). */
+    readonly originalSegment: string;
+} | {
+    readonly kind: 'refuse';
+    readonly reason: 'occupied';
+    readonly entryId: SessionTrashEntryId;
+    readonly suggestedId: string;
+};
+/**
+ * Decide how to restore one entry.
+ *
+ * Restoring onto an occupied path is **refused** with a suggestion rather than silently restored under a
+ * different name: the platform keys a session by `(id, cwd)`, so a renamed directory would either be
+ * invisible or (worse) look like a second copy of a session that still exists.
+ *
+ * @param entry - the bin entry.
+ * @param options - whether the original path is currently occupied.
+ * @returns the plan.
+ */
+export declare function planRestoreSession(entry: SessionTrashEntry, options: {
+    readonly occupied: boolean;
+}): RestoreSessionPlan;
+/**
+ * Build one entry from a deletion that has already been performed.
+ *
+ * Pure: the caller has moved the bytes and passes the observed facts. Keeping this separate from the move
+ * means the recorded `bytes`/`movedBy` are what actually happened, not what was planned.
+ *
+ * @param input - observed facts.
+ * @returns the entry.
+ */
+export declare function makeSessionTrashEntry(input: {
+    readonly id: SessionTrashEntryId;
+    readonly sessionId: string;
+    readonly cwd: string | undefined;
+    readonly projectDir: string;
+    readonly segment: string;
+    readonly originalSegment: string;
+    readonly title: string | undefined;
+    readonly bytes: number;
+    readonly deletedAtMs: number;
+    readonly movedBy: 'rename' | 'copy';
+    readonly confirmedBy?: string | undefined;
+}): SessionTrashEntry;

package/lib/types/src/host/domain/transfer/recycle-bin.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Recycle bin: entry model, on-disk layout, retention policy and the undo stack — pure logic only.
+ *
+ * Why the domain layer (AGENTS.md 红线 2): entry ids, the bin path layout, the retention decision and the
+ * undo state machine are all decisions that can be verified offline in milliseconds. Every real filesystem
+ * or SSH interaction stays behind the injected seam of
+ * [`integration/recycle-bin-service.ts`](../integration/recycle-bin-service.ts).
+ *
+ * Contract notes:
+ *
+ *  - **Deterministic ids.** The same inputs (root key, original path, deletion instant, delete ordinal for
+ *    that path) always yield the same id. Two deletes of the same path at the same millisecond are told
+ *    apart by `sequence`, and {@link allocateRecycleBinId} breaks genuine hash collisions deterministically.
+ *  - **Layout.** `<binRoot>/<id>/<original basename>`. The id is unique, so same-named files never collide;
+ *    keeping the original basename in the bin means a restore does not rename anything. Everything else a
+ *    restore needs (root key, original absolute path) lives on the entry, which the service persists in an
+ *    index file next to the bins.
+ *  - **Restore conflicts.** When the original path is occupied, {@link planRestore} reports `blocked` plus an
+ *    informational suffix candidate; the caller must **refuse**, never silently write to a different name.
+ *  - **Retention.** `maxEntries` / `maxBytes` / `maxAgeMs` are applied per dimension: a **non-positive value
+ *    means "no limit"** for that dimension (0 and negatives never wipe anything — deliberate, because a
+ *    misconfigured 0 must not empty the bin). Oversized bins shed **oldest first**, with the id as a stable
+ *    tie-break, so the same input always produces the same decision.
+ *  - **Undo.** A stack. The inverse of `discard` is `restore` (and vice versa, which is what makes the undo
+ *    redoable); `purge` is a physical delete and is therefore **explicitly irreversible**.
+ *
+ * @module dsh-over-ssh/domain/recycle-bin
+ */
+/**
+ * Opaque identity of one recycle-bin entry.
+ *
+ * Branded on purpose: an id is the directory name inside the bin and a handle the UI holds across calls, so
+ * it must not be confused with a path or a session id.
+ */
+export type RecycleBinEntryId = string & {
+    readonly __recycleBinEntryId: 'RecycleBinEntryId';
+};
+/** Which world a target lives in; same vocabulary as `RootRef.location`. */
+export type RecycleBinLocation = 'local' | 'remote';
+/** Name of the index file inside a bin root. */
+export declare const RECYCLE_BIN_INDEX_FILE = "index.json";
+/** Version stamped into the index file; a different version is a hard parse failure. */
+export declare const RECYCLE_BIN_INDEX_VERSION = 1;
+/** Inputs that determine an entry id. */
+export interface RecycleBinIdInput {
+    /** Stable root key (`rootKey()`); scopes ids to one root. */
+    readonly rootKey: string;
+    /** Absolute path of the deleted target, in this repository's normalized spelling. */
+    readonly originalPath: string;
+    /** Deletion instant in milliseconds since the epoch. */
+    readonly deletedAtMs: number;
+    /** Which delete of that same path this is, 1-based. */
+    readonly sequence: number;
+}
+/** One recycle-bin entry: everything a restore needs, plus the facts the bin view shows. */
+export interface RecycleBinEntry {
+    readonly id: RecycleBinEntryId;
+    /** Root key (`rootKey()`) the target was deleted from. */
+    readonly rootKey: string;
+    readonly location: RecycleBinLocation;
+    /** Original absolute path, normalized (local: `/` separators; remote: POSIX). */
+    readonly originalPath: string;
+    /** Final segment of {@link originalPath}; the bin keeps this name. */
+    readonly originalName: string;
+    /** Bin root directory (`binRootFor(root)`). */
+    readonly binRoot: string;
+    /** Actual location inside the bin: `<binRoot>/<id>/<originalName>`. */
+    readonly binPath: string;
+    readonly deletedAtMs: number;
+    /** Bytes reported by the pre-delete `stat`; for directories this is the directory entry, not a sum. */
+    readonly sizeBytes: number;
+    readonly isDirectory: boolean;
+    /** 1-based ordinal of this delete among deletes of the same path. */
+    readonly sequence: number;
+}
+/** Input for {@link makeRecycleBinEntry}; {@link RecycleBinIdInput} plus the id and the observed facts. */
+export interface MakeRecycleBinEntryInput extends RecycleBinIdInput {
+    readonly id: RecycleBinEntryId;
+    readonly location: RecycleBinLocation;
+    readonly binRoot: string;
+    readonly sizeBytes: number;
+    readonly isDirectory: boolean;
+}
+/**
+ * Normalize a deletion target into the spelling the rest of the repository uses.
+ *
+ * Local targets go through `normalizeLocalPath` (separators to `/`, case preserved), remote targets through
+ * `normalizeRemotePath` (POSIX, absolute). A filesystem root is rejected because it can never be a target.
+ *
+ * @param path - target path in either separator spelling.
+ * @param location - which world the path belongs to.
+ * @returns the normalized absolute path.
+ * @throws SshDevError `ROOT_INVALID` when the path is empty, relative, or a filesystem root.
+ */
+export declare function normalizeRecycleTarget(path: string, location: RecycleBinLocation): string;
+/**
+ * The deterministic id for one {@link RecycleBinIdInput}.
+ *
+ * Same input → same id (a test can therefore pin ids). Different inputs collide only if FNV-1a collides,
+ * which {@link allocateRecycleBinId} handles.
+ *
+ * @param input - root key, original path, deletion instant and delete ordinal.
+ * @returns a filesystem-safe id of the form `rb-<8 hex>`.
+ */
+export declare function makeRecycleBinEntryId(input: RecycleBinIdInput): RecycleBinEntryId;
+/**
+ * Allocate an id that is not already taken by `existing`.
+ *
+ * The first candidate is {@link makeRecycleBinEntryId}; on collision the suffix `-2`, `-3`, … is appended.
+ * The loop is bounded by the number of live entries, because every candidate it rejects is one of them.
+ *
+ * @param existing - ids already present in the bin index.
+ * @param input - id material.
+ * @returns an id not present in `existing`.
+ */
+export declare function allocateRecycleBinId(existing: Iterable<string>, input: RecycleBinIdInput): RecycleBinEntryId;
+/**
+ * Build one entry, validating its inputs and computing the bin layout.
+ *
+ * @param input - id, root, worlds, observed `stat` facts.
+ * @returns the entry, with `binPath` = `<binRoot>/<id>/<originalName>`.
+ * @throws SshDevError `ROOT_INVALID` when a path, the bin root, or a numeric field is unusable.
+ */
+export declare function makeRecycleBinEntry(input: MakeRecycleBinEntryInput): RecycleBinEntry;
+/**
+ * Join segments under an absolute base with `/`.
+ *
+ * Both worlds use this spelling (`local` roots are stored normalized by `normalizeLocalPath`, remote ones are
+ * POSIX), so the bin layout is spelled the same way everywhere. A drive-rooted base (`D:`) keeps its slash.
+ *
+ * @param base - absolute base directory.
+ * @param segments - segments to append.
+ * @returns the joined path.
+ */
+export declare function joinUnderPath(base: string, ...segments: readonly string[]): string;
+/** A restore decision: either the move is ready, or the original path is occupied and must not be reused. */
+export type RestorePlan = {
+    readonly kind: 'ready';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'blocked';
+    readonly to: string;
+    readonly reason: 'occupied';
+    readonly suggestedPath: string;
+};
+/**
+ * Decide how to restore one entry.
+ *
+ * Policy: **an occupied original path is refused, never renamed silently.** `suggestedPath` is returned so a
+ * UI can *offer* an alternative, but no code path in this module moves a target to it.
+ *
+ * @param entry - entry to restore.
+ * @param options - `occupied` is the caller's `stat` of `entry.originalPath`.
+ * @returns the plan.
+ */
+export declare function planRestore(entry: RecycleBinEntry, options: {
+    readonly occupied: boolean;
+}): RestorePlan;
+/** Retention policy. A non-positive value means "no limit" for that dimension. */
+export interface RecycleBinPolicy {
+    /** Keep at most this many entries; non-positive = unlimited. */
+    readonly maxEntries: number;
+    /** Keep at most this many bytes (sum of entry sizes); non-positive = unlimited. */
+    readonly maxBytes: number;
+    /** Keep entries at most this old, in milliseconds; non-positive = unlimited. */
+    readonly maxAgeMs: number;
+}
+/** Neutral element: no dimension is limited, therefore nothing is ever swept with it. */
+export declare const NO_RECYCLE_BIN_LIMITS: RecycleBinPolicy;
+/** Which dimension caused one entry to be swept. */
+export type SweepDimension = 'age' | 'count' | 'bytes';
+/** Why one entry is scheduled for physical deletion. */
+export interface SweepReason {
+    readonly id: RecycleBinEntryId;
+    readonly dimension: SweepDimension;
+    readonly detail: string;
+}
+/** The pure retention decision for one bin. */
+export interface SweepDecision {
+    /** Ids to delete physically, oldest first. */
+    readonly purge: readonly RecycleBinEntryId[];
+    /** Ids to keep, oldest first. */
+    readonly keep: readonly RecycleBinEntryId[];
+    /** One reason per purged id, in the same order. */
+    readonly reasons: readonly SweepReason[];
+    /** Entries and bytes left after applying the decision. */
+    readonly remainingEntries: number;
+    readonly remainingBytes: number;
+}
+/**
+ * Apply a retention policy to one bin.
+ *
+ * Rules, in this order (all of them deterministic: entries are ordered oldest first with the id as tie-break):
+ *
+ *  1. `maxAgeMs > 0`: purge everything older than the limit. An entry exactly **at** the limit is kept, and a
+ *     negative age (clock skew, future timestamp) is never purged.
+ *  2. `maxBytes > 0`: walk the survivors oldest first and purge until the remaining sum is within the limit.
+ *     A single entry larger than the whole budget is purged too — otherwise the budget would be meaningless.
+ *  3. `maxEntries > 0`: purge the oldest survivors until the count is within the limit.
+ *
+ * @param entries - entries of one bin.
+ * @param policy - limits; non-positive values are ignored.
+ * @param nowMs - current instant in milliseconds since the epoch.
+ * @returns the decision.
+ */
+export declare function decideSweep(entries: readonly RecycleBinEntry[], policy: RecycleBinPolicy, nowMs: number): SweepDecision;
+/** What one committed operation did; the unit of the undo stack. */
+export type OperationKind = 'discard' | 'restore' | 'purge';
+/** One committed operation. */
+export interface RecycleBinOperation {
+    readonly kind: OperationKind;
+    /** Entry the operation acted on; `undefined` for a permanent delete, which has no bin entry. */
+    readonly entry: RecycleBinEntry | undefined;
+    /** Entry id, or a synthesized id for a permanent delete. */
+    readonly id: RecycleBinEntryId;
+    readonly atMs: number;
+}
+/** Stack-shaped undo state: `undo` is the history, `redo` what was undone and can be re-applied. */
+export interface UndoStack {
+    readonly undo: readonly RecycleBinOperation[];
+    readonly redo: readonly RecycleBinOperation[];
+    /** Operations dropped for exceeding the depth limit; explains "too old to undo". */
+    readonly dropped: number;
+}
+/** Fresh state with no history. */
+export declare const EMPTY_UNDO_STACK: UndoStack;
+/** Why an undo/redo step was refused. */
+export type UndoRejectionReason = 'nothing-to-undo' | 'nothing-to-redo' | 'entry-missing' | 'irreversible';
+/** The world state an undo decision is validated against. */
+export interface UndoContext {
+    /**
+     * Ids **currently present in the recycle bin**.
+     *
+     * One rule covers both directions: a `restore` action needs the bin copy (the id must be listed), and a
+     * `discard` action needs the file to be back at its original path (the id must not be listed).
+     */
+    readonly liveIds: readonly RecycleBinEntryId[];
+}
+/** A step to execute: move the entry out of the bin, or back into it. */
+export interface UndoAction {
+    readonly kind: 'restore' | 'discard';
+    readonly operation: RecycleBinOperation;
+    readonly entry: RecycleBinEntry;
+}
+/** Why a step is not executable. */
+export interface UndoRejection {
+    readonly reason: UndoRejectionReason;
+    readonly message: string;
+    readonly operation: RecycleBinOperation | undefined;
+}
+/** Outcome of one undo/redo step: either an action to run, or a rejection. */
+export interface UndoOutcome {
+    /** State after the step; a rejected record is dropped from the stack (it can never succeed). */
+    readonly stack: UndoStack;
+    readonly action: UndoAction | undefined;
+    readonly rejection: UndoRejection | undefined;
+}
+/**
+ * Record one committed operation.
+ *
+ * The redo half is cleared (a new operation starts a new branch of history), the record goes on top of the
+ * undo half, and anything beyond `undoDepth` is dropped. A non-positive `undoDepth` keeps no history at all.
+ *
+ * @param stack - current state.
+ * @param operation - the operation that just succeeded.
+ * @param options - `undoDepth` from configuration.
+ * @returns the new state.
+ */
+export declare function recordOperation(stack: UndoStack, operation: RecycleBinOperation, options: {
+    readonly undoDepth: number;
+}): UndoStack;
+/** The operation {@link takeUndo} would consume, or `undefined` for an empty history. */
+export declare function nextUndo(stack: UndoStack): RecycleBinOperation | undefined;
+/** The operation that can be re-applied, or `undefined` when nothing was undone. */
+export declare function nextRedo(stack: UndoStack): RecycleBinOperation | undefined;
+/**
+ * Consume the newest operation as an **inverse** step.
+ *
+ * `discard` reverses to `restore`; `restore` reverses to `discard`; `purge` is refused as `irreversible`
+ * (a physical delete cannot be undone, and the record is dropped instead of being offered again).
+ *
+ * @param stack - current state.
+ * @param context - which ids are actually in the bin right now.
+ * @returns the action to run plus the new state, or a rejection plus the state with the dead record dropped.
+ */
+export declare function takeUndo(stack: UndoStack, context: UndoContext): UndoOutcome;
+/**
+ * Re-apply the newest undone operation.
+ *
+ * This is the exact inverse of {@link takeUndo}: it consumes the redo half and pushes the same operation back
+ * onto the undo half.
+ *
+ * @param stack - current state.
+ * @param context - which ids are actually in the bin right now.
+ * @returns the action to run plus the new state, or a rejection.
+ */
+export declare function takeRedo(stack: UndoStack, context: UndoContext): UndoOutcome;
+/** The persisted index document. */
+export interface RecycleBinIndex {
+    readonly version: number;
+    readonly entries: readonly RecycleBinEntry[];
+}
+/** One record the parser refused, with the reason (a corrupt index must never silently lose data). */
+export interface SkippedIndexRecord {
+    readonly index: number;
+    readonly reason: string;
+}
+/** Result of {@link parseRecycleBinIndex}. */
+export interface ParsedRecycleBinIndex {
+    readonly entries: readonly RecycleBinEntry[];
+    readonly skipped: readonly SkippedIndexRecord[];
+}
+/**
+ * Serialize the index.
+ *
+ * Entries are sorted by id so the same set always produces byte-identical text (easy to diff, easy to test).
+ * The result is a plain JavaScript string: written as UTF-8 it carries **no BOM**, and {@link parseRecycleBinIndex}
+ * tolerates one anyway because remote tooling and editors add them.
+ *
+ * @param entries - entries to persist.
+ * @returns JSON text.
+ */
+export declare function serializeRecycleBinIndex(entries: readonly RecycleBinEntry[]): string;
+/**
+ * Parse the index.
+ *
+ * A malformed document or an unknown version is a hard failure (the bin contents cannot be trusted); a single
+ * unusable record is skipped and reported. Stored `binPath` values are taken as authoritative and not recomputed,
+ * so changing the `binRootFor` configuration later does not invalidate existing entries.
+ *
+ * @param text - index file content.
+ * @returns the usable entries plus the skipped records.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the document cannot be read as an index.
+ */
+export declare function parseRecycleBinIndex(text: string): ParsedRecycleBinIndex;