dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,337 +0,0 @@
-/**
- * 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-remote-workspace/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/root.d.ts

@@ -1,74 +0,0 @@
-/**
- * Root references: one project root is either a local directory or a remote directory on
- * one connection. Remote roots additionally carry a local *anchor* directory, because DSH
- * requires a workspace path that exists on the host filesystem.
- *
- * @module dsh-remote-workspace/domain/root
- */
-/** Where a root lives. */
-export type RootLocation = 'local' | 'remote';
-/** One project root. */
-export interface RootRef {
-    /** Local or remote. */
-    readonly location: RootLocation;
-    /** Connection id; present exactly for remote roots. */
-    readonly connectionId?: string;
-    /** Absolute local path, or absolute POSIX path for a remote root. */
-    readonly path: string;
-    /** Whether the sandbox fence admits writes under this root. */
-    readonly writable: boolean;
-    /** Local anchor directory for a remote root (empty directory, never mirrored content). */
-    readonly anchorPath?: string;
-    /** Display label; defaults to the final path segment. */
-    readonly label?: string;
-}
-/** Options shared by both root kinds. */
-export interface RootOptions {
-    /** Whether writes under this root are allowed; defaults to true. */
-    readonly writable?: boolean;
-    /** Display label override. */
-    readonly label?: string;
-}
-/** Create a remote root, validating the connection id and remote path. */
-export declare function makeRemoteRoot(connectionId: string, remotePath: string, options?: RootOptions & {
-    readonly anchorPath?: string;
-}): RootRef;
-/**
- * Create a local root from an absolute host path.
- *
- * The stored path **preserves the caller's case** (only separators, `.`/`..` and the drive letter
- * are canonicalised). Case folding belongs to comparison and keying — `rootKey` folds, and
- * `localPathContains` folds on request — because the root's path is also what the UI shows and what
- * a child process receives via `processPath`.
- */
-export declare function makeLocalRoot(path: string, options?: RootOptions): RootRef;
-/** Whether a host path is absolute in either the Windows or the POSIX spelling. */
-export declare function isAbsoluteLocalPath(path: string): boolean;
-/**
- * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing
- * separators dropped, and (optionally) the drive letter and case folded.
- *
- * @param path - host path in either separator spelling.
- * @param options - `caseInsensitive` folds case for comparison keys.
- * @returns the normalized path.
- */
-export declare function normalizeLocalPath(path: string, options?: {
-    readonly caseInsensitive?: boolean;
-}): string;
-/** Whether a host path is `root` itself or a descendant of it. */
-export declare function localPathContains(root: string, candidate: string, options?: {
-    readonly caseInsensitive?: boolean;
-}): boolean;
-/** Stable identity of a root, used as a cache/route key. */
-export declare function rootKey(root: RootRef): string;
-/** The model-facing and UI-facing spelling of a root's directory. */
-export declare function rootDisplay(root: RootRef): string;
-/** The display label of a root: explicit label, else the final path segment. */
-export declare function rootLabel(root: RootRef): string;
-/** Whether two roots of the same location overlap (one contains the other). */
-export declare function rootsOverlap(left: RootRef, right: RootRef): boolean;
-/** Validate a root reference produced outside this module. */
-export declare function validateRoot(root: RootRef): void;
-/** FNV-1a (32-bit) over UTF-16 code units, rendered as 8 lowercase hex characters. */
-export declare function fnv1aHex(input: string): string;
-//# sourceMappingURL=root.d.ts.map

package/lib/types/src/host/domain/roots/bin-location.d.ts

@@ -1,91 +0,0 @@
-/**
- * Where a root's **file-level recycle bin** lives, and how to tell whether that place is usable.
- *
- * The bin used to sit at `<root>/.dsh-remote-workspace/trash` — inside the caller's own repository, so every
- * `git status` and `git add .` saw the bytes someone had just "safely deleted". Moving it out is not a matter
- * of changing a default (audit 0064 §3): the router refuses any path that is not inside a registered root, so
- * the new location has to be *registered* as a root of its own — one that is deliberately **not** listed
- * anywhere the user looks. The placement rules live here, as pure functions, because they are the part that
- * must be identical for every root and every world.
- *
- * Two constraints decide the location, and both are hard:
- *
- *  1. **Same device as the root.** The bin's whole guarantee is "move first, then confirm", and a cross-device
- *     `rename` is refused outright rather than degraded to a copy (`fs-commands.ts`), because a copy can fail
- *     half way and leave the bytes neither here nor there. The file-level bin has no copy fallback. So the bin
- *     must be on the root's own filesystem.
- *  2. **Outside the repository, but not somewhere unguessable.** `$HOME` looks tidy and is the wrong answer:
- *     on the site this plugin was built against the login home is `/home1/<user>` while projects live under
- *     `/srv` or `/mnt`, which are usually separate mounts (NFS/automount) — so a home-based bin would make
- *     **every** delete fail with `cross-device`. The root's own **parent** is the closest directory that is
- *     almost always on the same filesystem.
- *
- * @module dsh-over-ssh/domain/bin-location
- */
-import { type RootRef } from './root.ts';
-/** The bin directory name used when the caller configures none (`binDir`). */
-export declare const DEFAULT_BIN_DIR = ".dsh-over-ssh/trash";
-/**
- * Bin directory names this plugin used before it was renamed to `dsh-over-ssh`.
- *
- * Kept as **read sources**, never as write targets: the bin index is the only record of what is recoverable
- * and each entry names its bytes by absolute path, so a rename without a migration would leave every already
- * deleted file on disk but unreachable. The resolver moves an old bin into {@link DEFAULT_BIN_DIR} the first
- * time it sees one (see `bin-root-resolver.ts`).
- *
- * Both spellings are listed because the bin lived in two places over its lifetime: inside the root, and
- * beside it under the root's parent.
- */
-export declare const LEGACY_BIN_DIRS: readonly [".dsh-remote-workspace/trash"];
-/**
- * The root's own directory, in the spelling that world uses.
- *
- * Remote paths are always POSIX and are normalised as such; a local path is normalised by the host's rules
- * (which is what makes `D:\work\a` and `D:/work/a` the same directory on Windows).
- *
- * @param root - the root whose directory is wanted.
- * @returns a `/`-separated path.
- */
-export declare function rootDirectory(root: RootRef): string;
-/**
- * The bin directory **inside** the root — the historical location, kept as the documented fallback.
- *
- * @param root - the root being served.
- * @param binDir - configured directory name, relative to the root.
- * @returns the absolute bin directory.
- */
-export declare function binRootInsideRoot(root: RootRef, binDir?: string): string;
-/**
- * A stable, filesystem-safe directory name for one root's bin.
- *
- * Two roots can share a parent (and even a basename, across connections), so the name carries a hash of the
- * root's identity rather than only its last segment. Stable across runs: the bin directory must be findable
- * again after a restart, and an unstable name would silently orphan every deleted byte.
- *
- * @param root - the root being served.
- * @returns a name such as `work-1f3a9c02`.
- */
-export declare function binRootSlug(root: RootRef): string;
-/**
- * The bin directory **beside** the root, under its parent.
- *
- * The parent is used rather than `$HOME` because it is almost always the root's own filesystem, which is the
- * one property the bin cannot do without. `binDir` keeps its configured name so the plugin's footprint reads
- * the same as before; the per-root slug keeps two roots in one parent apart.
- *
- * @param root - the root being served.
- * @param binDir - configured directory name, relative to the parent.
- * @returns the absolute bin directory, or `undefined` when the root has no usable parent (it *is* `/`).
- */
-export declare function binRootBesideRoot(root: RootRef, binDir?: string): string | undefined;
-/**
- * The directory a same-device check must compare the bin directory against.
- *
- * The bin is created by the plugin, so on the first delete it may not exist yet; the parent is what has to be
- * on the same filesystem, and it always exists (it contains the root).
- *
- * @param root - the root being served.
- * @returns the absolute parent directory, or `undefined` for a root with no parent.
- */
-export declare function binParentDirectory(root: RootRef): string | undefined;
-//# sourceMappingURL=bin-location.d.ts.map

package/lib/types/src/host/domain/roots/route-table.d.ts

@@ -1,102 +0,0 @@
-/**
- * The route table: turns a model-facing path into one backend plus a root-relative path.
- *
- * This is the heart of "one workspace, several roots". Resolution order is deliberate, and
- * every branch is a documented rule rather than a heuristic:
- *
- *  1. `ssh://<connection>/abs` — the explicit remote grammar always wins.
- *  2. Anchor match — a path (or the session cwd) under a remote root's local anchor resolves
- *     to that remote root. The anchor is what makes a remote root a legal DSH workspace.
- *  3. Local root containment — absolute host paths, and `cwd`-relative spellings.
- *  4. Bare POSIX absolute path matching remote roots — needed because a prompt lists remote
- *     roots in POSIX spelling; two equally specific remote roots on different connections
- *     are reported as ambiguous instead of being guessed.
- *
- * @module dsh-over-ssh/domain/route-table
- */
-import { SshDevError } from '../errors.ts';
-import { type RootRef } from './root.ts';
-import { type SessionIdentity } from './session-roots.ts';
-/** One resolved route. */
-export interface RouteTarget {
-    /** The root the path belongs to. */
-    readonly root: RootRef;
-    /** Root-relative spelling with `/` separators; an empty string means the root itself. */
-    readonly relativePath: string;
-    /** Stable backend key; one backend serves all paths of one root. */
-    readonly backendKey: string;
-}
-/** Per-call resolution options. */
-export interface RouteOptions {
-    /** Session working directory used for relative spellings. */
-    readonly cwd?: string;
-    /**
-     * Who is asking, when the caller knows more than its cwd (ADR-0013).
-     *
-     * The route table never invents this: the fs provider reads it from the session scope the tool dispatcher
-     * carries down (`integration/session-scope.ts`) and hands it over. `undefined` means "no session identity" —
-     * the workspace-level rule then stands, which is exactly the behaviour before ADR-0013.
-     */
-    readonly session?: SessionIdentity;
-    /**
-     * The asking session's own working directory, when the caller did not supply a `cwd`.
-     *
-     * Used **only** by the implicit session root (a session's own directory is always readable to it) — never by
-     * the gate below, which must keep seeing exactly what the platform passed. Synthesising a `cwd` for the gate
-     * would apply the workspace rule to calls that legitimately carry none, which is the failure ADR-0012 §4
-     * boundary 2 records (a whole turn lost before the model was called).
-     */
-    readonly sessionCwd?: string;
-    /** Override host-path case folding (defaults to the platform). */
-    readonly caseInsensitive?: boolean;
-}
-/** A path resolved to a root, or a diagnostic reason why it could not be. */
-export type RouteOutcome = {
-    readonly ok: true;
-    readonly target: RouteTarget;
-} | {
-    readonly ok: false;
-    readonly error: SshDevError;
-};
-/** Resolution table over an ordered set of roots. */
-export declare class RouteTable {
-    #private;
-    constructor(roots?: readonly RootRef[], options?: {
-        readonly caseInsensitive?: boolean;
-    });
-    /** Roots in registration order. */
-    get roots(): readonly RootRef[];
-    /**
-     * Register a root.
-     *
-     * @param root - root to add.
-     * @throws SshDevError `ROOT_INVALID` when the root is malformed or already registered.
-     */
-    add(root: RootRef): void;
-    /** Remove a root by its key; returns whether it was present. */
-    remove(key: string): boolean;
-    /** Replace every root; throws like {@link add} when any root is invalid. */
-    reset(roots: readonly RootRef[]): void;
-    /**
-     * Resolve a path, then apply the **session gate**.
-     *
-     * Two failures wear the same code on purpose: "no root covers this path" and "the root that covers it belongs
-     * to another session" are both `ROOT_OUTSIDE`, because from the caller's side they are the same fact — this
-     * session cannot use that path. The message and the `root` detail say which one it was.
-     *
-     * @param input - model-facing, host or remote spelling.
-     * @param options - session cwd (also the session identity, see {@link rootVisibleToSession}) and case folding.
-     * @returns the resolved route, or a failure carrying `ROOT_OUTSIDE` / `ROOT_AMBIGUOUS`.
-     */
-    tryResolve(input: string, options?: RouteOptions): RouteOutcome;
-    /**
-     * Resolve a path or throw.
-     *
-     * @param input - path to resolve.
-     * @param options - session cwd and case-folding override.
-     * @returns the resolved route.
-     * @throws SshDevError `ROOT_OUTSIDE` or `ROOT_AMBIGUOUS`.
-     */
-    resolve(input: string, options?: RouteOptions): RouteTarget;
-}
-//# sourceMappingURL=route-table.d.ts.map