dsh-over-ssh 0.2.3 → 0.2.4

package/lib/types/src/host/infra/backend/poll-watch.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Tier 1 的**轮询式** watch：没有代理原生 watcher 时，用"定时快照 + 对比"回答"这个路径变了"。
+ *
+ * 为什么需要它：`Backend.watch` 是可选方法，Tier 2（Go 代理有 inotify/kqueue）实现了，Tier 1（纯 POSIX
+ * ssh）没有。后果不是崩溃，而是**能力缺口**：纯 POSIX 路径上目录变了没人知道，文件面板不会刷新，只能靠
+ * 重新读。诚实拒绝（`REMOTE_UNSUPPORTED`）比假装订阅好，但"能轮询"比"完全不能"好——只要轮询的代价被
+ * 明确限住。
+ *
+ * 三条设计约束，都是"不要拖垮连接"：
+ *
+ *  1. **只轮询被 watch 的那一层**（`maxDepth = 1`，见 `remote-listing.ts` 的 `buildListScript`）。递归
+ *     轮询一个 `~` 目录会把远端打爆：一次快照就是一次 `find`，深度每加一层，条目数与 I/O 都成倍增长。
+ *     需要子树通知的调用方应当分别 watch 子目录，而不是让一个订阅替它扫全树。
+ *  2. **条目数有上限**（默认 {@link DEFAULT_POLL_MAX_ENTRIES}）。超过上限不是"慢慢比"，而是**诚实失败**：
+ *     每 2.5 s 传回并比较两万行，比不提供监听更糟。失败通过 `changed(error)` 上报，订阅方据此退回
+ *     "重新读"的旧行为。
+ *  3. **连续失败要退避，且到阈值就报死**。每 2.5 s 打一次 ssh 的重试是"看起来活着其实早死了"：连接
+ *     断了以后订阅方永远等不到通知，却以为自己在被监听。默认 3 次连续失败后 `changed(error)` 并停止。
+ *
+ * 本模块**不碰 transport**：快照函数由调用方注入（`RemoteBackend` 用一条 shell 命令实现），所以这里
+ * 可以完全用假快照 + 假时钟单测，不需要 ssh、不需要 sleep 真实时间。
+ *
+ * @module dsh-over-ssh/infra/backend/poll-watch
+ */
+import type { BackendEntry } from '../../app/backend.ts';
+/** 默认轮询间隔：2.5 s。 */
+export declare const DEFAULT_POLL_INTERVAL_MS = 2500;
+/** 默认连续失败阈值：3 次。到阈值就 `changed(error)` 并停止，不无限静默重试。 */
+export declare const DEFAULT_POLL_FAILURE_THRESHOLD = 3;
+/** 默认退避上限：30 s。连续失败时按 `interval × 2^(n-1)` 退避，但不超过这个值。 */
+export declare const DEFAULT_POLL_MAX_BACKOFF_MS = 30000;
+/**
+ * 默认单次快照的条目上限：2 000。
+ *
+ * 与目录列举的 `REMOTE_LIST_MAX_ENTRIES` 同量级：一个需要监听的目录通常远小于它，而超过它的目录每
+ * 2.5 s 传回并比较一次，成本已经超过"不提供监听"。超过时诚实失败，见模块注释。
+ */
+export declare const DEFAULT_POLL_MAX_ENTRIES = 2000;
+/** 一次快照：一个**可比较的签名**，加上条目数（用于上限判断）。 */
+export interface PollSnapshot {
+    /**
+     * 稳定签名：两次快照签名相同即"没变"。
+     *
+     * 由调用方决定包含什么（目录用 `(name, type, size, mtime)` 列表，单文件用 `(type, size, mtime)`），
+     * 本模块只做字符串比较——这样"什么算变化"的策略留在知道目标类型的那一侧。
+     */
+    readonly signature: string;
+    /** 这次快照观察到的条目数；单文件快照是 0。 */
+    readonly entries: number;
+}
+/** 轮询参数；全部可注入，测试用小间隔 + 假 sleep 即可，不依赖真实时间。 */
+export interface PollWatchOptions {
+    /** 轮询间隔，默认 {@link DEFAULT_POLL_INTERVAL_MS}。 */
+    readonly intervalMs?: number;
+    /** 连续失败阈值，默认 {@link DEFAULT_POLL_FAILURE_THRESHOLD}。 */
+    readonly failureThreshold?: number;
+    /** 退避上限，默认 {@link DEFAULT_POLL_MAX_BACKOFF_MS}。 */
+    readonly maxBackoffMs?: number;
+    /** 单次快照条目上限，默认 {@link DEFAULT_POLL_MAX_ENTRIES}。 */
+    readonly maxEntries?: number;
+    /**
+     * 可注入的等待函数（毫秒 + 取消信号）。
+     *
+     * 默认实现用 `setTimeout` 并在 abort 时立刻 resolve；测试注入一个"手动推进"的版本，就能在不 sleep
+     * 真实时间的前提下精确控制轮询节奏。
+     */
+    readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * 哪些错误应当**立刻**上报而不是计入"连续失败"。
+     *
+     * 用于"这个路径根本不该轮询"的确定性失败（例如目录条目数超过上限）：重试三次只会多打三次 ssh，
+     * 而结论不会变。默认没有致命错误。
+     */
+    readonly isFatal?: (error: unknown) => boolean;
+}
+/** {@link startPollWatch} 的依赖。 */
+export interface PollWatchDeps {
+    /** 取一次快照；抛错表示这次轮询失败（连接问题、命令失败等）。 */
+    readonly snapshot: (signal: AbortSignal) => Promise<PollSnapshot>;
+    /**
+     * 建立订阅时已经取到的基线快照。
+     *
+     * 有它时循环不再立刻多打一次 ssh：建立订阅的那一次快照既是"确认目标可读"，也是比较的起点。
+     * 没有它时第一次轮询只建立基线、不通知（订阅方刚拿到当前状态，没有"变化"可言）。
+     */
+    readonly initial?: PollSnapshot;
+    /** 平台回调：无参 = 重新 stat；带 error = 订阅已死。 */
+    readonly changed: (error?: Error) => void;
+    /** 调用方的取消信号；abort 后循环立刻停止。 */
+    readonly signal: AbortSignal;
+    /** 轮询参数。 */
+    readonly options?: PollWatchOptions;
+}
+/**
+ * 把一次目录列举压成可比较的签名。
+ *
+ * 四列都参与：**新增/删除**改变条目集合，**改大小**改变 size，**改 mtime** 改变时间戳。只比名字会漏掉
+ * "内容变了但名字没变"——那正是文件面板最需要刷新的情况。
+ *
+ * 名字里可能含制表符（POSIX 允许），所以用 `\u0000` 分隔而不是 `\t`；条目按名字排序，保证同一目录的
+ * 两次快照顺序一致（`parseListing` 已经排过，这里再排一次是为了让本函数对任意输入都稳定）。
+ *
+ * @param entries - 一次目录列举的结果。
+ * @returns 稳定签名。
+ */
+export declare function listingSignature(entries: readonly BackendEntry[]): string;
+/**
+ * 启动一个轮询循环。
+ *
+ * 第一次快照只建立基线，**不**通知（订阅方刚拿到当前状态，没有"变化"可言）。之后每次签名不同就调用一次
+ * `changed()`；两次轮询之间的多次变化合并成一次通知（契约本来就是"重新 stat 一下"，不是精确 diff）。
+ *
+ * 停止条件只有四个：调用方 abort、调用方调用返回的 stop、连续失败到阈值、快照报出致命错误。每个停止
+ * 路径都保证循环不再持有定时器。
+ *
+ * @param deps - 快照、回调、取消信号与参数。
+ * @returns 幂等的停止函数。
+ */
+export declare function startPollWatch(deps: PollWatchDeps): () => Promise<void>;

package/lib/types/src/host/infra/backend/remote-backend.d.ts

@@ -0,0 +1,297 @@
+/**
+ * The remote backend: one remote directory served over a {@link Transport}.
+ *
+ * This is the Tier 1 shape — no agent on the remote host, only POSIX tools the server already has
+ * (`sh`, `wc`, `stat`, `base64`). Directory listing is therefore one bounded shell script rather
+ * than a protocol method, and the script is built from a fixed template with a single quoted path,
+ * so there is no injection surface.
+ *
+ * Version tokens are whatever **one** transport reports for the same file state, and this backend never
+ * mixes two sources. On Tier 1 that is the shell `size:mtimeSeconds` shape (comparable with the ssh2
+ * transport); on Tier 2 it is the agent's `size:mtimeNs`, obtained from {@link Transport.statPath} so that a
+ * token read by `readText` and a token compared by `writeText` come from the same producer. Deriving one
+ * from the other is what made every read→write guard fail on Tier 2 (audit 0055).
+ *
+ * @module dsh-over-ssh/infra/backend/remote-backend
+ */
+import type { Backend, BackendEntry, BackendRead, BackendSandboxMode, BackendStat, BackendText, BackendWrite } from '../../app/backend.ts';
+import type { RemoteCapabilities } from '../../domain/capability.ts';
+import { type VersionedCacheStats } from '../cache/versioned.ts';
+import type { CacheBudget } from '../cache/budget.ts';
+import { type PollWatchOptions } from './poll-watch.ts';
+import type { Transport } from '../transport/transport.ts';
+/** Options for {@link RemoteBackend}. */
+export interface RemoteBackendOptions {
+    /** Backend id; the router namespaces target keys with it (equals the root key). */
+    readonly id: string;
+    /** A ready transport. Mutually exclusive with {@link getTransport}. */
+    readonly transport?: Transport;
+    /**
+     * Lazy transport resolver, called once on first use.
+     *
+     * The root registry's backend factory is synchronous while acquiring a transport is not, so the
+     * connection is established when the first operation needs it and reused afterwards.
+     */
+    readonly getTransport?: () => Promise<Transport>;
+    /**
+     * Transport used **only** for `watch.*` subscriptions, when the caller wants them on a separate
+     * (stateful) lane. Omitted means "same transport as everything else" (the pre-lane behaviour).
+     */
+    readonly watchTransport?: () => Promise<Transport>;
+    /**
+     * Transport used **only** for `repo.summary`, when the caller wants it on a separate (compute) lane.
+     *
+     * Omitted means "same transport as everything else", which is the pre-lane behaviour. Every other operation
+     * keeps using {@link getTransport}: reads/writes/listing/watch must stay on the interactive lane.
+     */
+    readonly repoSummaryTransport?: () => Promise<Transport>;
+    /** Read cap applied by the backend itself; the router passes a smaller one when it wants to. */
+    readonly maxReadBytes?: number;
+    /**
+     * Freshness cache policy for the read path (FR-2.7). Omitted means {@link DEFAULT_CACHE}.
+     *
+     * This is the switch that makes "re-opening the same file within the TTL costs **zero** round trips"
+     * true. Before it existed, `VersionedCache` was written, benchmarked and then never constructed by
+     * any production code: every read went to the host, and the numbers in `baseline.md` measured a
+     * component nobody called (audit 0044).
+     */
+    readonly cache?: RemoteBackendCacheOptions;
+    /**
+     * Budget shared by **every** remote root's caches.
+     *
+     * The per-root limits in {@link cache} cannot bound the process: there is one read cache and one listing cache
+     * per root, and roots come and go. Supplying a budget adds that missing total bound, and `dispose()` leaves it
+     * so a retired root stops counting (audit 0112 P3-12).
+     */
+    readonly cacheBudget?: CacheBudget;
+    /**
+     * Tier 1 轮询监听的参数（间隔、退避、条目上限、可注入的 sleep）。
+     *
+     * 只在**没有** native watcher 时生效：Tier 2 的 `watch.start/poll/stop` 永远优先，轮询是能力缺口上的
+     * 兜底，不是替代品。省略时用 `poll-watch.ts` 的默认值（2.5 s / 3 次失败 / 2000 条目）。
+     */
+    readonly pollWatch?: PollWatchOptions;
+    /**
+     * 可注入时钟：轮询快照共享窗口的 TTL 用。
+     *
+     * 必须与 `pollWatch.sleep` 走同一个时钟。测试里 sleep 是假的，若 TTL 读真实 `Date.now()`，假时钟推进后
+     * 仍会命中缓存，"目录变了"的用例会全部失败——这不是测试的问题，是两个时间源不一致。
+     */
+    readonly now?: () => number;
+}
+/** Cache policy for one remote backend. */
+export interface RemoteBackendCacheOptions {
+    /** Freshness window; the FR-2.7 budget is 5 s. `0` disables retention (every read goes remote). */
+    readonly ttlMs?: number;
+    /** Bound on retained entries. */
+    readonly maxEntries?: number;
+    /** Bound on retained payload bytes. */
+    readonly maxBytes?: number;
+    /** Injectable clock, so a TTL can be tested without sleeping. */
+    readonly now?: () => number;
+}
+/** Filesystem access for one remote root over a transport. */
+export declare class RemoteBackend implements Backend {
+    #private;
+    readonly id: string;
+    readonly sandboxMode: BackendSandboxMode | undefined;
+    /**
+     * Whether this root has a **native** watcher: the transport is one that speaks `watch.*` *and* its handshake
+     * advertised `watch === "native"`. It reads `false` until the transport is known — the capability is a fact
+     * about the connected agent, and claiming it early would advertise a watcher for a Tier 1 host that can
+     * never serve one.
+     */
+    get watches(): boolean;
+    constructor(options: RemoteBackendOptions);
+    /**
+     * Read-path cache counters, for diagnostics and the performance baseline.
+     *
+     * Reported rather than inferred: the FR-2.7 claims ("0 round trips inside the TTL", "≈5× on
+     * revalidation") are only checkable if the counters behind them are reachable from outside.
+     */
+    get cacheStats(): {
+        readonly reads: VersionedCacheStats;
+        readonly listings: VersionedCacheStats;
+    };
+    /** Remote capabilities discovered so far (probe results live on the transport). */
+    capabilities(): Promise<RemoteCapabilities>;
+    /**
+     * Stat a path, preferring the transport's **own** token source when it has one.
+     *
+     * This is where the two tiers are reconciled, and it is the *only* place that decides. A transport that
+     * exposes {@link Transport.statPath} (Tier 2: the agent's `fs.stat`) reports the very same token its
+     * `readFile` reports (`size:mtimeNs`), so a version read by one and compared by the other is comparing
+     * like with like. Tier 1 has no native stat, so the shell script below runs exactly as it always has and
+     * its long-standing `size:mtimeSeconds` tokens are untouched.
+     *
+     * Before this, `stat` always ran the shell script: on Tier 2 it produced seconds while every read produced
+     * nanoseconds, so the `remote_read` → `remote_write`/`remote_edit` version guard could never pass and the
+     * FR-2.7 stale-revalidation branch never matched either.
+     */
+    stat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
+    list(absolute: string, signal?: AbortSignal): Promise<readonly BackendEntry[]>;
+    /**
+     * Read a file, going through the FR-2.7 freshness cache.
+     *
+     * The three states the budget is written in terms of:
+     *  - **fresh** (inside the TTL): returned from memory, **zero** round trips;
+     *  - **stale**: one cheap `stat` decides. If the version still matches, the retained body is reused and
+     *    only the timestamp is refreshed — this is the ≈5× revalidation path;
+     *  - **gone or changed**: re-read and replace.
+     *
+     * A read with a different cap is a different cache entry (see the field notes), so a capped probe can
+     * never satisfy a full read.
+     */
+    readBytes(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendRead>;
+    /**
+     * Atomic in-place edit through the agent's `fs.edit` (审计 0030).
+     *
+     * The caller passes the version it just read; the agent re-checks it, so a concurrent modification
+     * between our read and this call is refused rather than clobbered. Throws `REMOTE_UNSUPPORTED` when the
+     * agent predates the method, which is what makes `ctx.fs` fall back to read → replace → write.
+     */
+    editText(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly replaced: number;
+    }>;
+    /**
+     * Apply a unified diff server-side: every hunk in one round trip, all-or-nothing.
+     *
+     * No client-side fallback on purpose. Reading the file, patching it here and writing it back would cost
+     * three round trips for two hunks — more than the `remote_edit` calls it is meant to replace — and would
+     * need a second implementation of the hunk-matching rules.
+     */
+    patchText(absolute: string, diff: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
+        readonly hunks: number;
+    }>;
+    repoSummary(root: string, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    patchMany(edits: readonly {
+        readonly path: string;
+        readonly expectedVersion?: string;
+        readonly find?: string;
+        readonly replace?: string;
+        readonly all?: boolean;
+        readonly create?: boolean;
+        readonly patch?: string;
+    }[], atomic: boolean, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    readText(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendText>;
+    /**
+     * Cache-aware wrapper around {@link readManyUncached}, so a batch sweep leaves the cache warm.
+     *
+     * Satisfying the whole batch from cache is deliberately **not** attempted: the batch exists to collapse
+     * N round trips into one, and splitting it into cached and uncached halves would give back the round trips
+     * it was built to save. Cached entries are therefore refreshed from the batch's answer, and files already
+     * fresh are still fetched (one shared round trip) rather than removed from the batch.
+     */
+    readMany(absolutePaths: readonly string[], options: {
+        readonly maxBytesEach: number;
+        readonly totalBytesCap?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly chunks: readonly (BackendText | undefined)[];
+        readonly missing: readonly string[];
+    }>;
+    /**
+     * Write text remotely.
+     *
+     * **The version guard is tier-aware, and that is the point.** The token a caller passes back is one this
+     * backend just handed out, so the guard must be verified by the *same* token source:
+     *
+     *  - a transport with a native version token (Tier 2) verifies the token itself through
+     *    {@link WriteFileRequest.expectedVersion}, which is what its own `fs.write` guard compares — no digest
+     *    is involved and none could be, because the agent advertises no sha256 tool;
+     *  - a Tier 1 transport verifies a content digest, so the current content is hashed and handed over as
+     *    `expectedSha256`. That path is unchanged.
+     *
+     * A plain write is one round trip plus one `stat` for the new version.
+     */
+    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
+    /**
+     * Watch one remote path (directory, or one file) through the agent's native watcher.
+     *
+     * The agent watches **directories**: `watch.start` registers recursively from the given roots, and each
+     * reported event carries the path of the changed entry. A file target therefore watches its parent directory
+     * and filters events by exact path — the same shape the platform's own local watcher uses, and the only way
+     * inotify can report changes to one file.
+     *
+     * Degradation is **not** silent:
+     *  - `watch.start` reporting `truncated` (maxWatches / `max_user_watches` cut registration short) means the
+     *    tree is only partially covered; the watcher is stopped and this call fails rather than promising
+     *    notifications it cannot deliver;
+     *  - a poll whose cumulative `dropped` grew means events were lost (queue limit / kernel overflow); the
+     *    owner is told through `changed(error)` and the watcher stops, so the caller rescans instead of trusting
+     *    an incomplete stream.
+     *
+     * `changed()` also covers "nothing to re-stat but something happened" — the platform's contract is
+     * "re-stat this path", so events are coalesced per poll.
+     *
+     * **Tier 1 没有 native watcher 时走轮询**（`poll-watch.ts`）：定时取一次"这一层"的快照并比较签名。
+     * 这是能力缺口上的兜底，不是替代品——native 可用时永远优先 native。轮询的代价被明确限住：只列被 watch
+     * 的那一层（`maxDepth = 1`）、条目数有上限、连续失败到阈值就 `changed(error)` 报死而不是静默重试。
+     *
+     * @param absolute - root-absolute remote path (directory or file).
+     * @param changed - platform callback: no argument = re-stat; an error = the subscription is dead.
+     * @param signal - cancels the subscription; stopping is immediate and idempotent.
+     * @returns the disposer (stops the watcher; idempotent).
+     * @throws SshDevError `REMOTE_NOT_FOUND` when a file target's parent directory does not exist,
+     *   `CANCELLED` when aborted during setup.
+     */
+    watch(absolute: string, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
+    /**
+     * Stop every watcher this backend started.
+     *
+     * Not part of {@link Backend}: the wiring owns backend teardown and is outside this change's scope. It is
+     * public so whoever retires the backend can end the poll loops, and so tests can prove they stop.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Create a directory (FR-2.2.2).
+     *
+     * Prefers the agent's `fs.mkdir` (Tier 2) and falls back to one bounded shell script. The shell path is not
+     * dead weight: Tier 1 has no agent, and an older agent answers `E_METHOD`, which
+     * {@link Transport.makeDir} reports as `REMOTE_UNSUPPORTED`.
+     *
+     * **Why the protocol path is worth preferring**: the shell version depends on the remote having a POSIX
+     * `mkdir`, and its refusals have to be parsed back out of the script's own `DSH_ERROR=` line. Windows
+     * targets have neither. The product rule — `recursive: false` refuses a name that is already taken, so a
+     * 「新建目录」 dialog cannot silently "succeed" into someone else's folder — is applied **here**, once, for
+     * both paths.
+     */
+    mkdir(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Rename/move a path (FR-2.2.2), refusing to clobber.
+     *
+     * The no-clobber rule lives in {@link renameCommand}'s script (see its notes): `mv` would either replace a
+     * file or move the source *inside* an existing directory, and both are silent.
+     */
+    rename(from: string, to: string, options: {
+        readonly createParents: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Remove a path (FR-2.2.2); `recursive: false` refuses a directory. */
+    remove(absolute: string, options: {
+        readonly recursive: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Change one path's permission bits.
+     *
+     * Runs through `exec` rather than a transport primitive because the agent has no `fs.chmod`; the same
+     * script therefore works on both tiers, which is what keeps `remote_write`'s `mode` from meaning two
+     * different things depending on the host (audit 0064 P4). `chmodCommand` re-validates the octal digits, so
+     * this is not a place where model-supplied text reaches a shell unchecked.
+     */
+    chmod(absolute: string, mode: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Create a symbolic link; refuse an existing path.
+     *
+     * Runs through `exec` for the same reason {@link chmod} does: the agent has no `fs.symlink`, and one script
+     * keeps the two tiers from disagreeing about what "create a link" means on this host.
+     */
+    symlink(target: string, linkPath: string, signal?: AbortSignal): Promise<void>;
+    /** Read a link target; `undefined` means "this is not a link", which is an answer, not an error. */
+    readlink(absolute: string, signal?: AbortSignal): Promise<string | undefined>;
+    /** Whether this backend's root contains a path (used by the router's `contains`). */
+    contains(parent: string, candidate: string): boolean;
+}
+/** Parse `KEY=value` header lines into a map. */
+export declare function parseHeaders(stdout: string): Map<string, string>;

package/lib/types/src/host/infra/cache/budget.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A **global** byte budget shared by several caches.
+ *
+ * The per-cache bounds (`maxEntries` / `maxBytes`) answer "how big may *this* cache get". They cannot answer
+ * "how much may the plugin hold in total", because the number of caches is a runtime fact: one read cache plus
+ * one listing cache per remote root, and roots are added and removed while the process runs. Before this module
+ * ten roots meant ten times the per-root allowance held forever — the bound was per root and nothing related
+ * the roots to each other (audit 0112 P3-12).
+ *
+ * The design is deliberately **not** a shared store: each cache keeps its own entries and its own recency order,
+ * and only reports/trims bytes. A shared store would have to interleave several key spaces (route keys, listing
+ * keys, different value types) and lose each cache's own `maxEntries`.
+ *
+ * @module dsh-over-ssh/infra/cache/budget
+ */
+/** One cache taking part in the budget. Implemented by `VersionedCache`. */
+export interface CacheBudgetMember {
+    /** Bytes this member currently holds. */
+    readonly bytes: number;
+    /**
+     * Drop this member's oldest entries until it holds at most `bytes`.
+     *
+     * @param bytes - the ceiling to come down to.
+     * @returns how many entries were dropped.
+     */
+    trimTo(bytes: number): number;
+    /**
+     * Drop the single oldest entry.
+     *
+     * @returns `false` when the member holds nothing, so the caller does not spin.
+     */
+    evictOldest(): boolean;
+}
+/** Limits for {@link createCacheBudget}. */
+export interface CacheBudgetLimits {
+    /** Ceiling for the **sum** over every member. */
+    readonly maxBytes: number;
+}
+/** The shared budget. */
+export interface CacheBudget {
+    /** Register a member. Registering twice is a no-op. */
+    join(member: CacheBudgetMember): void;
+    /** Stop accounting for a member (its root went away). */
+    leave(member: CacheBudgetMember): void;
+    /**
+     * Bring the sum back under the ceiling after `grown` added bytes.
+     *
+     * @param grown - the member that just grew, for diagnostics; it gets no special treatment.
+     */
+    enforce(grown?: CacheBudgetMember): void;
+    /** Bytes held by every member. */
+    readonly totalBytes: number;
+    /** The ceiling. */
+    readonly maxBytes: number;
+    /** How many members are registered. */
+    readonly memberCount: number;
+}
+/**
+ * Build a budget.
+ *
+ * Enforcement evicts from the **largest** member rather than from the one that just grew: the grower is usually
+ * what a reader is looking at right now (an open file, the directory being browsed), while the largest cache is
+ * where the pressure actually is. With one member the two rules coincide.
+ *
+ * @param limits - the total ceiling.
+ * @returns the budget.
+ */
+export declare function createCacheBudget(limits: CacheBudgetLimits): CacheBudget;

package/lib/types/src/host/infra/cache/versioned.d.ts

@@ -0,0 +1,98 @@
+/**
+ * TTL + version cache used by the remote read path.
+ *
+ * The performance budget depends on this three-state behaviour:
+ *  - within TTL: a hit with zero remote round trips;
+ *  - past TTL: a *stale* hit whose body may still be reused if a cheap version check matches
+ *    (this is what makes revalidation ≈5× cheaper than a first open);
+ *  - invalidated: no usable body.
+ *
+ * @module dsh-over-ssh/infra/cache/versioned
+ */
+import type { CacheBudget, CacheBudgetMember } from './budget.ts';
+/** Cache policy for one cache instance. */
+export interface VersionedCacheOptions {
+    /** Freshness window in milliseconds. */
+    readonly ttlMs: number;
+    readonly maxEntries: number;
+    readonly maxBytes: number;
+    /** Monotonic-or-wall clock; injectable so tests are deterministic. */
+    readonly now?: () => number;
+    /**
+     * A budget shared with the other caches of the same plugin.
+     *
+     * Omitting it keeps today's per-cache behaviour (this instance's own limits still apply); supplying it adds
+     * the missing **total** bound: when the sum over every member exceeds the budget, the largest cache gives
+     * bytes back. Without it, N remote roots hold N times the per-root allowance (audit 0112 P3-12).
+     */
+    readonly budget?: CacheBudget;
+}
+/** One lookup result. */
+export interface VersionedHit<V> {
+    readonly value: V;
+    /** The version token recorded when the body was cached. */
+    readonly version: string;
+    /** Whether the entry is still inside its freshness window. */
+    readonly fresh: boolean;
+    readonly ageMs: number;
+}
+/** Counters reported for diagnostics and the performance baseline. */
+export interface VersionedCacheStats {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly freshHits: number;
+    readonly staleHits: number;
+    /** Version checks that reused an existing body. */
+    readonly revalidations: number;
+    readonly evictions: number;
+}
+/** Freshness-aware cache keyed by route key. */
+export declare class VersionedCache<V> implements CacheBudgetMember {
+    #private;
+    constructor(options: VersionedCacheOptions, sizeOf: (value: V) => number);
+    /** Bytes this cache holds (the budget member contract). */
+    get bytes(): number;
+    /** Drop oldest entries down to `maxBytes` (the budget member contract). */
+    trimTo(maxBytes: number): number;
+    /** Drop the oldest entry (the budget member contract). */
+    evictOldest(): boolean;
+    /**
+     * Leave the shared budget, so a retired cache stops counting against the total.
+     *
+     * Called by whoever owns the cache when its root goes away. Without it a removed root's cache stayed in the
+     * accounting forever, which is the leak the budget exists to prevent.
+     */
+    leaveBudget(): void;
+    /**
+     * Look up an entry.
+     *
+     * @param key - route key.
+     * @returns the entry with its freshness, or `undefined` when nothing is retained.
+     */
+    get(key: string): VersionedHit<V> | undefined;
+    /** Insert or replace an entry, stamping it as just-read. */
+    set(key: string, value: V, version: string): boolean;
+    /**
+     * Refresh an entry's timestamp after a cheap remote version check matched.
+     *
+     * @param key - route key.
+     * @param version - the version observed by the check; a mismatch refuses the touch.
+     * @returns whether the entry was refreshed.
+     */
+    touch(key: string, version: string): boolean;
+    /** Drop one entry. */
+    invalidate(key: string): boolean;
+    /**
+     * Drop every entry whose key starts with the prefix, used when a directory epoch changes.
+     *
+     * @param prefix - key prefix.
+     * @returns the number of removed entries.
+     */
+    invalidatePrefix(prefix: string): number;
+    /** Remove everything. */
+    clear(): void;
+    /** Current counters. */
+    get stats(): VersionedCacheStats;
+}