dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,337 @@
+/**
+ * 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;
+//# sourceMappingURL=recycle-bin.d.ts.map

package/lib/types/src/host/domain/transfer/transfer.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Pure transfer arithmetic: chunk plans, progress maths, root-confined remote targets and file-name
+ * validation.
+ *
+ * Kept in the domain layer on purpose (AGENTS.md 红线 2): no `@deepseek-ai/*` import, no process, no
+ * socket and no clock — every number it needs is a parameter. That is what lets the whole transfer
+ * policy (offsets, percentages, resume decisions, `..` folding rules) be tested offline in
+ * milliseconds, and it is why the seam in `integration/transfer-service.ts` only has to move bytes.
+ *
+ * Three behaviours are deliberately *deterministic* rather than "reasonable":
+ *
+ *  - **A zero-byte file has zero chunks** but still needs one empty write to create the target
+ *    (`needsEmptyWrite`), so "upload an empty file" is a real operation rather than a no-op.
+ *  - **A plan is bounded**: the chunk list is materialised, so `MAX_TRANSFER_CHUNKS` caps it and an
+ *    absurd `chunkBytes` fails loudly instead of exhausting memory.
+ *  - **`..` never escapes the root**: the spelling is folded the way `joinUnderRoot` folds it, and the
+ *    result is re-checked against the root, so a future change to the folder cannot silently open a
+ *    hole (see {@link assertInsideRoot}).
+ *
+ * @module dsh-over-ssh/domain/transfer
+ */
+import { formatBytes, formatDuration } from '../../../shared/format.ts';
+import { SshDevError, type SshDevErrorCode } from '../errors.ts';
+/**
+ * Upper bound on the number of chunks one plan may contain.
+ *
+ * This is **not** a deployment knob — the deployment knob is `chunkBytes`. It exists because
+ * {@link planTransfer} materialises the chunk list, so a tiny `chunkBytes` on a huge file would
+ * otherwise allocate until the process dies.
+ */
+export declare const MAX_TRANSFER_CHUNKS = 100000;
+/** One slice of a transfer: bytes `[offset, offset + length)` of the source. */
+export interface TransferChunk {
+    /** 0-based position of this chunk inside the plan it was produced by. */
+    readonly index: number;
+    /** Byte offset in the source. */
+    readonly offset: number;
+    /** Number of bytes to move; always ≥ 1. */
+    readonly length: number;
+}
+/** A complete, finite plan for moving `totalBytes`. */
+export interface TransferPlan {
+    readonly totalBytes: number;
+    readonly chunkBytes: number;
+    /** Chunks in increasing offset order; empty for a zero-byte source. */
+    readonly chunks: readonly TransferChunk[];
+    /** Whether the target still has to be created with one write of zero bytes. */
+    readonly needsEmptyWrite: boolean;
+}
+/** Why a transfer could not do something the caller asked for, or could not report a digest. */
+export interface TransferDegradation {
+    /** Stable code, so a caller can branch without reading the hint. */
+    readonly code: 'resume-unsupported' | 'resume-unusable' | 'resume-mismatch' | 'resume-unverified' | 'digest-unavailable';
+    /** Actionable explanation for the user. */
+    readonly hint: string;
+}
+/** What to do about a possibly-partial target before starting. */
+export interface ResumeDecision {
+    /** Byte offset the transfer starts at. */
+    readonly startOffset: number;
+    /** Whether bytes already present on the target are being kept. */
+    readonly resumed: boolean;
+    /** Reasons the transfer is not resuming; empty when it resumes or was never asked to. */
+    readonly degradations: readonly TransferDegradation[];
+}
+/**
+ * Cut `totalBytes` into contiguous chunks of at most `chunkBytes`.
+ *
+ * @param totalBytes - source length; 0 produces an empty plan plus `needsEmptyWrite`.
+ * @param chunkBytes - per-chunk cap; must be a safe integer ≥ 1.
+ * @returns the plan, with offsets starting at 0 and covering exactly `totalBytes`.
+ * @throws SshDevError `ROOT_INVALID` when either argument is not a usable integer, or when the plan
+ *   would exceed {@link MAX_TRANSFER_CHUNKS}.
+ */
+export declare function planTransfer(totalBytes: number, chunkBytes: number): TransferPlan;
+/**
+ * The chunks still to move when the target already holds `startOffset` bytes.
+ *
+ * The first returned chunk is trimmed to start exactly at `startOffset`, and indices are renumbered
+ * from 0 because the caller reports "how many writes did *this* transfer make".
+ *
+ * @param plan - the full plan.
+ * @param startOffset - bytes already present; ≤ 0 means "nothing", ≥ `totalBytes` means "nothing left".
+ * @returns the remaining chunks; the input plan is not mutated.
+ */
+export declare function remainingChunks(plan: TransferPlan, startOffset: number): readonly TransferChunk[];
+/**
+ * Decide where a transfer starts, given what the target already holds.
+ *
+ * Precedence (each rule is a test): no resume requested → 0; zero-byte source → 0; the injected
+ * implementation cannot resume → 0 with `resume-unsupported`; nothing usable on the target → 0;
+ * target is at least as long as the source → 0 with `resume-unusable` (a same-size target is **never**
+ * assumed complete, because nothing here can verify its content); otherwise the target's length.
+ *
+ * @param input - source length, target length (`undefined` when absent/unknown) and the two flags.
+ * @returns the decision, including why resume did not happen.
+ */
+export declare function decideStartOffset(input: {
+    readonly totalBytes: number;
+    readonly partialBytes: number | undefined;
+    readonly resumeRequested: boolean;
+    readonly resumeSupported: boolean;
+}): ResumeDecision;
+/** Progress of one transfer at one instant. */
+export interface TransferProgress {
+    readonly transferredBytes: number;
+    readonly totalBytes: number;
+    /** 0–100, rounded to one decimal; a zero-byte transfer is 100 (nothing left to do). */
+    readonly percent: number;
+    /** Average rate since the transfer started; 0 when no time has passed. */
+    readonly bytesPerSecond: number;
+    readonly elapsedMs: number;
+    /** Estimated time left; `null` when no rate is known yet, 0 when finished. */
+    readonly remainingMs: number | null;
+}
+/**
+ * Compute progress from the two byte counts and elapsed time.
+ *
+ * Pure and monotonic: for a fixed `totalBytes` and a non-decreasing `transferredBytes`, every field
+ * is non-decreasing.
+ *
+ * @param input - bytes moved, bytes expected and milliseconds since the start.
+ * @returns the progress snapshot.
+ */
+export declare function progressOf(input: {
+    readonly transferredBytes: number;
+    readonly totalBytes: number;
+    readonly elapsedMs: number;
+}): TransferProgress;
+/** Binary byte units, largest last. */
+/**
+ * One-line progress text for the UI or a CLI.
+ *
+ * @param progress - a snapshot from {@link progressOf}.
+ * @param options - `label` names the direction (`上传`/`下载`); defaults to `传输`.
+ * @returns e.g. `上传 40.0%（4 B/10 B，2 B/s，剩余约 3.0s）`, or `…，耗时 350ms）` once finished.
+ */
+export declare function formatProgress(progress: TransferProgress, options?: {
+    readonly label?: string;
+}): string;
+/** A remote target resolved inside one root. */
+export interface RemoteTarget {
+    /** Normalized root the target lives in. */
+    readonly root: string;
+    /** Root-absolute POSIX path of the target. */
+    readonly absolute: string;
+    /** The spelling requested, with `.`/`..` folded (may differ from `absolute`). */
+    readonly relative: string;
+    /** Final path segment. */
+    readonly name: string;
+}
+/**
+ * Fold `root + requested` into a root-absolute path that cannot leave the root.
+ *
+ * The folding rule is exactly `joinUnderRoot`'s (imported, not re-implemented): a leading `/` is
+ * treated as root-relative, `.` is dropped, and `..` pops within the *requested* part only — extra
+ * `..` at the top are ignored rather than climbing out of the root. The result is re-checked with
+ * {@link assertInsideRoot} so a future change to the folder cannot silently open a hole.
+ *
+ * @param root - absolute POSIX root directory.
+ * @param requested - remote spelling relative to the root (absolute spellings are root-relative too).
+ * @returns the resolved target.
+ * @throws SshDevError `ROOT_INVALID` for an unusable root/request, `ROOT_OUTSIDE` when the request
+ *   names the root itself, ends with `/` (a directory spelling) or somehow escapes the root.
+ */
+export declare function resolveRemoteTarget(root: string, requested: string): RemoteTarget;
+/**
+ * Check that a root-absolute path really is inside its root.
+ *
+ * @param root - absolute POSIX root directory.
+ * @param absolute - root-absolute candidate.
+ * @throws SshDevError `ROOT_OUTSIDE` when the candidate is not the root or below it.
+ */
+export declare function assertInsideRoot(root: string, absolute: string): void;
+/**
+ * Validate one remote file name (a single path segment).
+ *
+ * @param name - the segment to check.
+ * @returns the name, unchanged.
+ * @throws SshDevError `ROOT_INVALID` for an empty/blank name, one containing `/` or NUL;
+ *   `ROOT_OUTSIDE` for `.`/`..`, which name a directory rather than a file.
+ */
+export declare function validateRemoteFileName(name: string): string;
+/**
+ * Validate one local file name for the platform the download will land on.
+ *
+ * The platform is a parameter rather than `process.platform` so the Windows rules stay testable on
+ * any host (see [`run-tests.md`] on platform-dependent assertions).
+ *
+ * @param name - the segment to check (a base name, never a path).
+ * @param options - `platform` selects the rule set; defaults to the running platform.
+ * @returns the name, unchanged.
+ * @throws SshDevError `ROOT_INVALID` for an empty/blank name, a name containing a path separator or
+ *   (on win32) a forbidden character, a reserved device name or a trailing dot/space;
+ *   `ROOT_OUTSIDE` for `.`/`..`.
+ */
+export declare function validateLocalFileName(name: string, options?: {
+    readonly platform?: 'win32' | 'posix';
+}): string;
+/**
+ * The final segment of a local path, in either separator spelling.
+ *
+ * @param path - host path.
+ * @returns the base name; empty when the path has no segment.
+ */
+export declare function localFileBasename(path: string): string;
+/**
+ * What went wrong in a transfer, precisely.
+ *
+ * This is **not** an error code (the code table lives in `domain/errors.ts` and is unchanged by this
+ * module). It is the `details.kind` of the thrown {@link SshDevError}, the same shape
+ * `sshFailureToError` uses to keep "which precise cause" separate from "which stable code".
+ */
+export type TransferFailureKind = 
+/** Arguments or spelling are unusable (empty root, empty name, bad chunk cap). */
+'invalid-request'
+/** The target names a directory, the root itself, or leaves the root. */
+ | 'outside-root' | 'local-stat-failed' | 'local-read-failed' | 'local-write-failed' | 'remote-stat-failed' | 'remote-not-found' | 'remote-read-failed' | 'remote-short-read' | 'remote-write-failed'
+/** The source changed size while it was being read. */
+ | 'source-changed' | 'verify-failed' | 'cancelled';
+/** Every {@link TransferFailureKind}, for exhaustive checks and tests. */
+export declare const TRANSFER_FAILURE_KINDS: readonly ["invalid-request", "outside-root", "local-stat-failed", "local-read-failed", "local-write-failed", "remote-stat-failed", "remote-not-found", "remote-read-failed", "remote-short-read", "remote-write-failed", "source-changed", "verify-failed", "cancelled"];
+/**
+ * Map a precise transfer failure onto one of the **existing** plugin error codes.
+ *
+ * No code is invented here (see the audit): a local I/O failure has no dedicated code in
+ * `SSH_DEV_ERROR_CODES`, so it maps to `ROOT_INVALID` ("this path is unusable") and stays
+ * distinguishable through `details.kind`.
+ *
+ * @param kind - the precise failure.
+ * @returns the stable code a caller can branch on.
+ */
+export declare function failureCodeFor(kind: TransferFailureKind): SshDevErrorCode;
+/**
+ * Build the plugin failure for one transfer step.
+ *
+ * @param kind - precise failure kind, recorded as `details.kind`.
+ * @param message - actionable Chinese message (what failed and what to do).
+ * @param details - structured context; must not contain secrets.
+ * @returns an {@link SshDevError} carrying the mapped code.
+ */
+export declare function transferFailure(kind: TransferFailureKind, message: string, details?: Readonly<Record<string, unknown>>): SshDevError;
+/**
+ * Test whether a value is a transfer failure (optionally of one precise kind).
+ *
+ * @param error - candidate.
+ * @param kind - when given, also require `details.kind` to equal it.
+ * @returns whether the value is a plugin error produced by this module.
+ */
+export declare function isTransferFailure(error: unknown, kind?: TransferFailureKind): boolean;
+/**
+ * Compare two digests tolerantly (hex digests arrive with mixed case and stray whitespace).
+ *
+ * @param left - one digest, or `undefined`.
+ * @param right - the other digest, or `undefined`.
+ * @returns whether both are present and equal ignoring case and surrounding whitespace.
+ */
+export declare function digestsMatch(left: string | undefined, right: string | undefined): boolean;
+export { formatBytes, formatDuration };
+//# sourceMappingURL=transfer.d.ts.map