dsh-session-ops 0.1.4 → 0.2.0

package/lib/store/registry.js

@@ -22,12 +22,14 @@
  * 拿不到 `agents` 服务时 admin 保守地把全部驻留会话当成「在跑」（宁可拒绝），
  * move 则把状态当成未知（`undefined`，界面照常显示）。
  *
+ * 这里声明的都是**最小本地接口**：Cordis/DSH 的宿主对象在编译期拿不到类型，
+ * 但本模块只用到这几个字段，把它们写清楚比整片 `any` 更能挡住拼写错误。
+ *
  * @module dsh-session-ops/store/registry
  */
-
+import { messageOf } from './util.js';
 /** agent 表示「这一轮还在跑」的状态值。 */
-export const SESSION_RUNNING_STATUS = 'running'
-
+export const SESSION_RUNNING_STATUS = 'running';
 /**
  * Host 进程里仍挂着的会话 id 集合（`ctx.sessions.list()`）。
  *
@@ -37,16 +39,17 @@ export const SESSION_RUNNING_STATUS = 'running'
  * @returns `Set<string>`。
  */
 export function residentSessionIds(sessions) {
-  const ids = new Set()
-  try {
-    const list = typeof sessions?.list === 'function' ? sessions.list() : []
-    for (const session of list) ids.add(String(session.id))
-  } catch {
-    /* 没有会话存储时视为无驻留 */
-  }
-  return ids
+    const ids = new Set();
+    try {
+        const list = typeof sessions?.list === 'function' ? sessions.list() : [];
+        for (const session of list)
+            ids.add(String(session.id));
+    }
+    catch {
+        /* 没有会话存储时视为无驻留 */
+    }
+    return ids;
 }
-
 /**
  * 一条会话的 agent 状态（`ctx.get('agents').get(id)?.status`）。
  * @param agents - `ctx.get('agents')` 拿到的 agent 服务（可为 undefined）。
@@ -54,14 +57,14 @@ export function residentSessionIds(sessions) {
  * @returns 状态字符串；没有 agent、拿不到服务或抛错时 `undefined`（**未知**）。
  */
 export function agentSessionStatus(agents, sessionId) {
-  try {
-    const agent = typeof agents?.get === 'function' ? agents.get(sessionId) : undefined
-    return agent !== undefined && typeof agent.status === 'string' ? agent.status : undefined
-  } catch {
-    return undefined
-  }
+    try {
+        const agent = typeof agents?.get === 'function' ? agents.get(sessionId) : undefined;
+        return agent !== undefined && typeof agent.status === 'string' ? agent.status : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-
 /**
  * 真正「正在跑一轮」的会话：驻留集合里 agent 状态为 {@link SESSION_RUNNING_STATUS} 的那部分。
  *
@@ -72,37 +75,37 @@ export function agentSessionStatus(agents, sessionId) {
  * @returns `Set<string>`（可能就是 `residents` 本身）。
  */
 export function runningSessionIds(residents, agents) {
-  if (agents === undefined || typeof agents.get !== 'function') return residents
-  const running = new Set()
-  for (const id of residents) {
-    try {
-      if (agents.get(id)?.status === SESSION_RUNNING_STATUS) running.add(id)
-    } catch {
-      running.add(id)
+    if (agents === undefined || typeof agents.get !== 'function')
+        return residents;
+    const running = new Set();
+    for (const id of residents) {
+        try {
+            if (agents.get(id)?.status === SESSION_RUNNING_STATUS)
+                running.add(id);
+        }
+        catch {
+            running.add(id);
+        }
     }
-  }
-  return running
+    return running;
 }
-
 /**
  * 工作区的**完整记账**成员表（`workspace.record.sessionIds`）。
  * @param workspace - 工作区实体。
  * @returns id 数组；实体没有 record 视图时 `undefined`。
  */
 export function accountedSessionIds(workspace) {
-  const record = workspace?.record
-  return record !== undefined && Array.isArray(record.sessionIds) ? record.sessionIds : undefined
+    const record = workspace?.record;
+    return record !== undefined && Array.isArray(record.sessionIds) ? record.sessionIds : undefined;
 }
-
 /**
  * 归档集合（`registry.archivedSessionIds`）。
  * @param registry - `ctx.workspaceRegistry`。
  * @returns `Set<string>`（id 归一成字符串）。
  */
 export function archivedSessionIds(registry) {
-  return new Set(Array.isArray(registry.archivedSessionIds) ? registry.archivedSessionIds.map(String) : [])
+    return new Set(Array.isArray(registry.archivedSessionIds) ? registry.archivedSessionIds.map(String) : []);
 }
-
 /**
  * 按**完整记账**找出会话所属的工作区。
  * @param workspaces - 工作区实体数组（通常是 `registry.list()`）。
@@ -110,13 +113,13 @@ export function archivedSessionIds(registry) {
  * @returns 工作区实体，或 `undefined`。
  */
 export function workspaceOwningSession(workspaces, sessionId) {
-  for (const workspace of workspaces) {
-    const ids = accountedSessionIds(workspace)
-    if (ids !== undefined && ids.includes(sessionId)) return workspace
-  }
-  return undefined
+    for (const workspace of workspaces) {
+        const ids = accountedSessionIds(workspace);
+        if (ids !== undefined && ids.includes(sessionId))
+            return workspace;
+    }
+    return undefined;
 }
-
 /**
  * 按 id → path → title 的顺序找一个工作区（后两者不区分大小写）。
  * @param workspaces - 工作区实体数组（通常是 `registry.list()`）。
@@ -124,14 +127,20 @@ export function workspaceOwningSession(workspaces, sessionId) {
  * @returns 工作区实体，或 `undefined`。
  */
 export function findWorkspace(workspaces, key) {
-  if (typeof key !== 'string' || key.length === 0) return undefined
-  for (const workspace of workspaces) if (String(workspace.id) === key) return workspace
-  const lowered = key.toLowerCase()
-  for (const workspace of workspaces) if (String(workspace.path).toLowerCase() === lowered) return workspace
-  for (const workspace of workspaces) if (String(workspace.title).toLowerCase() === lowered) return workspace
-  return undefined
+    if (typeof key !== 'string' || key.length === 0)
+        return undefined;
+    for (const workspace of workspaces)
+        if (String(workspace.id) === key)
+            return workspace;
+    const lowered = key.toLowerCase();
+    for (const workspace of workspaces)
+        if (String(workspace.path).toLowerCase() === lowered)
+            return workspace;
+    for (const workspace of workspaces)
+        if (String(workspace.title).toLowerCase() === lowered)
+            return workspace;
+    return undefined;
 }
-
 /**
  * 把一个即将被删除的会话从它登记过的每个持久结构里摘掉。
  *
@@ -148,17 +157,17 @@ export function findWorkspace(workspaces, key) {
  * @returns 全部持久写入完成之后 resolve；值是真正被 detach 的工作区 id 列表。
  */
 export async function releaseSessionEverywhere(registry, sessionId) {
-  const detached = []
-  for (const workspace of registry.list()) {
-    if (!workspace.sessionIds.includes(sessionId)) continue
-    await workspace.detachSession(sessionId)
-    detached.push(String(workspace.id))
-  }
-  await registry.unarchiveSession(sessionId)
-  await registry.unpinSession(sessionId)
-  return detached
+    const detached = [];
+    for (const workspace of registry.list()) {
+        if (!workspace.sessionIds.includes(sessionId))
+            continue;
+        await workspace.detachSession(sessionId);
+        detached.push(String(workspace.id));
+    }
+    await registry.unarchiveSession(sessionId);
+    await registry.unpinSession(sessionId);
+    return detached;
 }
-
 /**
  * 持久化后端的**写入句柄表**（`persistence.tracker.writers`）。
  *
@@ -167,10 +176,11 @@ export async function releaseSessionEverywhere(registry, sessionId) {
  * @returns `Map<id, handle>`，或 `undefined`（后端不暴露 tracker 时）。
  */
 export function sessionWriteHandles(persistence) {
-  const tracker = persistence?.tracker
-  return tracker !== undefined && tracker.writers instanceof Map ? tracker.writers : undefined
+    const tracker = persistence?.tracker;
+    return tracker !== undefined && tracker.writers instanceof Map
+        ? tracker.writers
+        : undefined;
 }
-
 /**
  * 把「这条会话以后往哪写」在**内存里**也改成新 cwd。
  *
@@ -189,35 +199,36 @@ export function sessionWriteHandles(persistence) {
  *   ——`flushError` 只在 flush 抛错时出现；`liveSession` 是驻留会话对象（没有则 undefined）。
  */
 export async function redirectSessionWriters(options) {
-  const { writers, sessions, registry, sessionId, cwd } = options
-  const outcome = {
-    writeHandleRedirected: false,
-    liveHeaderUpdated: false,
-    registryHeaderCacheUpdated: false,
-    liveSession: undefined,
-  }
-  const handle = writers === undefined ? undefined : writers.get(sessionId)
-  if (handle !== undefined && handle !== null && typeof handle.header === 'object') {
-    try {
-      await handle.flush()
-    } catch (error) {
-      outcome.flushError = String(error?.message ?? error)
+    const { writers, sessions, registry, sessionId, cwd } = options;
+    const outcome = {
+        writeHandleRedirected: false,
+        liveHeaderUpdated: false,
+        registryHeaderCacheUpdated: false,
+        liveSession: undefined,
+    };
+    const handle = writers === undefined ? undefined : writers.get(sessionId);
+    if (handle !== undefined && handle !== null && typeof handle.header === 'object') {
+        try {
+            await handle.flush();
+        }
+        catch (error) {
+            outcome.flushError = messageOf(error);
+        }
+        handle.header = { ...handle.header, cwd };
+        outcome.writeHandleRedirected = true;
+    }
+    const live = typeof sessions?.get === 'function' ? sessions.get(sessionId) : undefined;
+    outcome.liveSession = live;
+    if (live !== undefined) {
+        live.header = { ...live.header, cwd };
+        outcome.liveHeaderUpdated = true;
     }
-    handle.header = { ...handle.header, cwd }
-    outcome.writeHandleRedirected = true
-  }
-  const live = typeof sessions?.get === 'function' ? sessions.get(sessionId) : undefined
-  outcome.liveSession = live
-  if (live !== undefined) {
-    live.header = { ...live.header, cwd }
-    outcome.liveHeaderUpdated = true
-  }
-  if (registry.headers instanceof Map) {
-    const cached = registry.headers.get(sessionId)
-    if (cached !== undefined) {
-      registry.headers.set(sessionId, { ...cached, cwd })
-      outcome.registryHeaderCacheUpdated = true
+    if (registry.headers instanceof Map) {
+        const cached = registry.headers.get(sessionId);
+        if (cached !== undefined) {
+            registry.headers.set(sessionId, { ...cached, cwd });
+            outcome.registryHeaderCacheUpdated = true;
+        }
     }
-  }
-  return outcome
+    return outcome;
 }

package/lib/store/util.js

@@ -0,0 +1,19 @@
+/**
+ * 本包内部的小工具：只放「宿主边界上重复出现、但语义必须逐字一致」的那几行。
+ *
+ * 目前只有一处：把 `unknown` 类型抛出的错误取成可读文案。JS 里的写法是
+ * `String(error?.message ?? error)`——它同时容忍 Error、任意带 `message` 的对象、
+ * 以及 `throw 'oops'` 这样的原始值。TS 的 `catch` 变量是 `unknown`，这份语义必须
+ * 原样保留（错误文案会被用户可见的报告与日志引用），所以收成一个函数。
+ *
+ * @module dsh-session-ops/store/util
+ */
+/**
+ * 取一个 unknown 错误的可读文案，语义与 `String(error?.message ?? error)` 逐字一致。
+ * @param error - catch 到的错误。
+ * @returns 可读文案。
+ */
+export function messageOf(error) {
+    const candidate = error;
+    return String(candidate?.message ?? error);
+}

package/lib/types/admin.d.ts

@@ -0,0 +1,187 @@
+/**
+ * `dsh-session-ops` 的**删除半边**（原 `dsh-session-admin` 插件的 Host 半边）。
+ *
+ * 这一半的代码搬自原 `dsh-session-admin` 的 `lib/index.js`，只有四处差异：
+ *   - 插件 entry 的 `name` / `inject` / `SETTINGS_NS` / `Config` / `resolveConfig` / `apply`
+ *     上移到 `lib/index.js`——合并后的包只有一个 entry、一份配置 schema、一个 `apply`；
+ *   - `API_PREFIX` 改名 `ADMIN_API_PREFIX`（搬迁半边占着 `MOVE_API_PREFIX`）；
+ *   - 配置键 `allowHosts` 改名 `adminAllowHosts`（两半的信任栅栏语义不同，见 `lib/index.js`）；
+ *   - 原 `apply` 里"建配置/建日志/订阅 volatile/看 enabled"那段上移到入口，剩下的接线
+ *     成为 `mountAdmin(ctx, config, log)`。
+ * 其余一字未动：扫描与范围筛选、逐条守卫、`/session-admin/api` 的方法表、
+ * `session_admin` 工具定义、Host 头版信任栅栏，连注释都保持原样。
+ *
+ * 能力：把会话的持久化数据真正从磁盘移除。一个会话在磁盘上最多占三处：
+ *   - `<home>/sessions/<项目目录键>/<session-id>/`   ← 会话日志（jsonl.zstd）
+ *   - `<home>/storages/session_projcache/sessions/<session-id>.json` ← 投影缓存
+ *   - `<home>/rewind-snapshots/<session-id>/`        ← 回退快照（可有可无）
+ * 三处一起删，并顺手清掉因此变空的项目目录。
+ *
+ * 刻意零 `@deepseek-ai/*` 运行时依赖：只用 Node 内置模块和一份 schemastery 配置
+ * schema。工具注册用普通对象（与 `dsh-subagent-in-process-driver` 同款），不做
+ * `defineTool` 导入——profile 的 node_modules 里未必解析得到 `@deepseek-ai/dsh-tools`。
+ * 代价是 `parameters` / `output.schema` 都必须自己写成**已编译的 JSON Schema**：
+ * register 不做编译，只把对象原样透传给 provider（详见 `TOOL_PARAMETERS` 注释）。
+ *
+ * @module dsh-session-ops/admin
+ */
+import { dshHome } from './store/host.js';
+import type { LogFn } from './store/host.js';
+import type { HttpRequest } from './store/http.js';
+import { decodeProjectKey } from './store/paths.js';
+import type { WorkspaceRegistryLike } from './store/registry.js';
+import type { SessionOpsConfig } from './index.js';
+/** HTTP 路由前缀（两半各一条，合并后仍然分开）。 */
+export declare const ADMIN_API_PREFIX = "/session-admin/api";
+/**
+ * `$DSH_HOME`（环境变量优先，默认 `~/.dsh`）。
+ *
+ * 实现在 `lib/store/host.js`——它与搬迁半边用的是同一份；
+ * 这里再导出，保持本仓库的公开面不变。
+ */
+export { dshHome };
+/**
+ * 把 `sessions/` 下的项目目录键还原成路径。
+ *
+ * 实现在 `lib/store/paths.js`：它与搬迁半边的 `projectKey`
+ * 是同一套规则的两个方向，规则只该有一份。这里再导出，保持本仓库的公开面不变。
+ */
+export { decodeProjectKey };
+/** 路径是否落在某个根目录内部（防目录穿越）。 */
+export declare function isInside(root: string, candidate: string): boolean;
+/** 扫描出来的一条会话记录。 */
+export interface SessionRecord {
+    id: string;
+    dir: string;
+    project: string;
+    cwd: string | null;
+    title: string | null;
+    origin: string | null;
+    parentSessionId: string | null;
+    isSeeded: boolean | null;
+    headerReadable: boolean;
+    workspaceId: string | null;
+    workspaceTitle: string | null;
+    ungrouped: boolean;
+    archived: boolean;
+    subagent: boolean;
+    cwdMissing: boolean;
+    temp: boolean;
+    bytes: number;
+    files: number;
+    updatedAt: number;
+    hasProjCache: boolean;
+    hasRewind: boolean;
+}
+/** {@link SessionAdmin.scan} 的选项。 */
+export interface ScanOptions {
+    /** `false` 跳过逐会话的体积统计（只要个数的调用方用它压开销）。 */
+    measure?: boolean;
+}
+/** {@link SessionAdmin.select} 的范围查询。 */
+export interface SelectQuery {
+    scope?: string;
+    cwdPrefix?: string;
+    search?: string;
+}
+/** {@link SessionAdmin.remove} 的选项。 */
+export interface RemoveOptions {
+    dryRun?: boolean;
+    includeWorkspace?: boolean;
+    includeArchived?: boolean;
+    includeSubagent?: boolean;
+    includeLive?: boolean;
+    /** **正在跑**、因此现在不能删的 id 集合。 */
+    live?: Set<string>;
+    callerSessionId?: string;
+    maxBatch?: number;
+}
+/** {@link SessionAdmin.remove} 里逐条的结果。 */
+export interface RemoveResult {
+    id: string;
+    status: 'skipped' | 'would-remove' | 'failed' | 'removed';
+    reason?: string;
+    bytes?: number;
+}
+/** {@link SessionAdmin.remove} 的汇总。 */
+export interface RemoveReport {
+    /** 早退（目标集合为空）时这个键不存在——与改动前的返回形状一致。 */
+    dryRun?: boolean;
+    removed: number;
+    reclaimed: number;
+    pruned: string[];
+    results: RemoveResult[];
+}
+/** {@link createSessionAdmin} 的选项。 */
+export interface CreateSessionAdminOptions {
+    /** DSH 主目录（默认 `dshHome()`）。 */
+    home?: string;
+    /** 视为「临时目录」的前缀。 */
+    tempRoots?: string[];
+    /** 删文件**之前**把一个会话从登记表里摘掉的异步回调。 */
+    releaseSession?: (sessionId: string) => Promise<unknown>;
+}
+/** 会话管理员（扫描 / 过滤 / 删除三个入口）。 */
+export interface SessionAdmin {
+    home: string;
+    sessionsRoot: string;
+    projcacheRoot: string;
+    rewindRoot: string;
+    scan(options?: ScanOptions): SessionRecord[];
+    select(records: SessionRecord[], query?: SelectQuery): SessionRecord[];
+    remove(ids: string[], options?: RemoveOptions): Promise<RemoveReport>;
+}
+/**
+ * 构造一个会话管理员。所有根目录都可注入，便于在测试里指向沙箱。
+ * @param options - `home`（DSH 主目录）、`tempRoots`（视为「临时目录」的前缀）、
+ *   `releaseSession`（删文件**之前**把一个会话从登记表里摘掉的异步回调；见 `remove`）。
+ * @returns 扫描 / 过滤 / 删除三个入口。
+ */
+export declare function createSessionAdmin(options?: CreateSessionAdminOptions): SessionAdmin;
+/**
+ * 判断一个请求是否有权访问本插件的路由。
+ *
+ * 本机 `dsh web` 常被绑到 `0.0.0.0`（局域网访问），所以「能连上端口」不等于
+ * 「是这台机器上的人」：非回环 authority 默认一律拒绝，除非在配置的
+ * `allowHosts` 里显式列出。同时拒绝 `sec-fetch-site: cross-site` 和跨源 Origin。
+ *
+ * **这份栅栏刻意留在本仓库**：`dsh-session-move` 那份按 socket 的 `remoteAddress`
+ * 判断回环、`allowHosts` 只做精确字符串匹配，既不解析 authority 也不看
+ * `sec-fetch-site`/`Origin`——两边语义不同，合并必然改掉其中一边的对外行为。
+ * 共享包只提供路由骨架（`createApiHandler`），栅栏以回调形式传进去。
+ * @param req - Node HTTP 请求。
+ * @param allowHosts - 额外信任的 authority 列表。
+ * @returns 是否放行。
+ */
+export declare function isTrustedRequest(req: HttpRequest, allowHosts?: string[]): boolean;
+/**
+ * Host cordis 上下文里删除半边用到的那部分（最小本地接口，见 `src/index.ts` 的说明）。
+ */
+export interface AdminContext {
+    logger?: Record<string, ((message: string) => unknown) | undefined> | undefined;
+    effect: (fn: () => unknown, label?: string) => unknown;
+    get: (name: string) => any;
+    webServer: {
+        register(options: unknown): unknown;
+    };
+    tools: {
+        register(definition: unknown): unknown;
+    };
+    workspaceRegistry: WorkspaceRegistryLike;
+}
+/**
+ * 挂载删除半边：路由 + 工具。
+ *
+ * 与搬迁半边刻意不同的三点（原样保留的理由）：
+ *   - 信任栅栏按 `Host` 头判断（`isTrustedRequest`），额外拒绝 `sec-fetch-site: cross-site`
+ *     与跨源 `Origin`；搬迁半边看 socket 的 `remoteAddress`；
+ *   - 响应带 `content-length`；
+ *   - 请求体按**宽松模式**读（空白 body 走 `JSON.parse` 报错，非对象不拦）。
+ *
+ * @param ctx - Host cordis 上下文（`webServer` / `tools` / `sessions` / `workspaceRegistry`）。
+ * @param config - 已解包的**活配置对象**：身份由入口保持，volatile 更新时原地覆盖，
+ *   所以下面这些闭包自动看到最新值。
+ * @param log - `(level, message) => void`（入口传的是 admin 那套行格式的文件日志）。
+ * @returns 无。
+ */
+export declare function mountAdmin(ctx: AdminContext, config: SessionOpsConfig, log: LogFn): void;

package/lib/types/engine.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 搬迁引擎：把一条会话日志从「旧 cwd 的 project 目录」搬到「新 cwd 的 project 目录」，
+ * 并改写 header 里的 cwd。不依赖 cordis，便于单测（见 test/core.test.mjs）。
+ *
+ * 命名与格式事实（都来自 dsh-session-persistence-jsonl 的实测与源码）：
+ *   - 日志路径 `<root>/<projectKey(cwd)>/<encodeSegment(id)>/session[.vN].jsonl[.zstd]`；
+ *   - `findLog` 会扫**所有** project 目录找同一个 id，多于一处就抛
+ *     `duplicate JSONL session id ... appears in multiple project directories`；
+ *   - generation 文件名必须规范（v0 不带 `vN`），临时名/带后缀的备份名不会被当成 generation。
+ * 因此搬迁必须做到「任何时刻都不存在两份规范名的日志」，见 {@link applyPlan} 的三步改名。
+ *
+ * @module dsh-session-ops/engine
+ */
+import type { SessionHeader } from './store/frames.js';
+import { findGeneration, parseGenerationName } from './store/paths.js';
+import type { GenerationEntry } from './store/paths.js';
+/** 迁移中使用的临时文件名后缀（都**不**匹配 generation 规范名）。 */
+export declare const TMP_SUFFIX = ".session-move-tmp";
+export declare const PARKED_SUFFIX = ".session-move-old";
+/**
+ * `findGeneration` / `parseGenerationName`（「目录里哪份才算规范 generation」）已经搬到
+ * `lib/store/paths.js`——删除路径也要认得同一套命名，规则只该有一份。
+ * 这里保留再导出，是为了不打断本仓库既有的导入者（`test/core.test.mjs` 就按
+ * `../lib/engine.js` 导入它们）。
+ */
+export { findGeneration, parseGenerationName };
+/** {@link planMove} 的选项。 */
+export interface PlanMoveOptions {
+    root: string;
+    sessionId: string;
+    fromCwd: string;
+    toCwd: string;
+    compression?: string;
+}
+/** 一次搬迁的计划（含 `buffer`，供 {@link applyPlan} 直接落盘）。 */
+export interface MovePlan {
+    root: string;
+    compression: string;
+    sessionId: string;
+    fromCwd: string;
+    toCwd: string;
+    fromKey: string;
+    toKey: string;
+    generation: GenerationEntry;
+    /** 源目录里除 generation 与 `session.lock` 之外的文件（真正会留在原地的）。 */
+    otherFiles: string[];
+    /** 源目录里是否有写租约文件；有则由 {@link applyPlan} 随目录一起搬走。 */
+    leaseFile: string | null;
+    otherGenerations: string[];
+    sourceDir: string;
+    targetDir: string;
+    sourcePath: string;
+    targetPath: string;
+    bytesBefore: number;
+    bytesAfter: number;
+    frameCount: number | null;
+    header: SessionHeader;
+    rewrittenHeader: SessionHeader;
+    buffer: Buffer;
+}
+/**
+ * 计算一次搬迁的计划：读源日志、改写 cwd、给出目标路径。**只读**，不写任何东西。
+ *
+ * @param options - `{root, sessionId, fromCwd, toCwd, compression}`。
+ * @returns 计划对象（含 `buffer`，供 {@link applyPlan} 直接落盘）。
+ * @throws 源日志缺失、header 与请求不符、目标已存在、源与目标同目录时。
+ */
+export declare function planMove(options: PlanMoveOptions): MovePlan;
+/** {@link applyPlan} 的搬迁报告（HTTP/工具直接回话用的就是它）。 */
+export interface MoveReport {
+    sessionId: string;
+    from: string;
+    to: string;
+    generation: string;
+    bytesBefore: number;
+    bytesAfter: number;
+    frames: number | null;
+    sourcePath: string;
+    targetPath: string;
+    moved: boolean;
+    /** 目标目录里已有租约文件、无法把源租约搬过去时，记下冲突路径。 */
+    leaseConflict?: string;
+    /** 搬租约失败时的错误文案。 */
+    leaseMoveError?: string;
+    /** 租约文件是否搬到了目标目录。 */
+    leaseMoved?: boolean;
+    /** 清空源目录失败时的错误文案。 */
+    sourceDirCleanupError?: string;
+    /** 源目录是否被清掉。 */
+    removedSourceDir?: boolean;
+    /** 源目录里剩下的文件（清空失败时非空）。 */
+    leftInSourceDir?: string[];
+    /** 落盘后读回的 header。 */
+    verifiedHeader?: {
+        id: string;
+        cwd: string | null;
+        version?: number;
+    } | null;
+    verifiedBytes?: number;
+    ok?: boolean;
+}
+/**
+ * 执行计划。三步改名保证「任何时刻都不存在两份规范名日志」：
+ *   1. 新日志先以临时名写进目标目录（此时还不是 generation）；
+ *   2. 源文件改名成 `*.session-move-old`（源目录里不再有规范名）；
+ *   3. 临时名改成规范名（此刻新日志才生效），随后删掉 `.old` 与空的源目录。
+ * 崩在 2 与 3 之间时，源数据仍在 `.old` 里、新数据仍在 `.tmp` 里，人工可救。
+ *
+ * @param plan - {@link planMove} 的返回值。
+ * @returns 搬迁报告（含 `dshReadbackSafe` 之外的事实字段，供 HTTP/工具直接回话）。
+ */
+export declare function applyPlan(plan: MovePlan): MoveReport;
+/** {@link verifyStoredLog} 的选项。 */
+export interface VerifyStoredLogOptions {
+    root: string;
+    sessionId: string;
+    cwd: string;
+    compression?: string;
+}
+/** {@link verifyStoredLog} 的报告（`header`/`bytes`/`magic` 只在可读时出现）。 */
+export interface StoredLogVerification {
+    ok: boolean;
+    error?: string;
+    header?: {
+        id: string;
+        cwd: string | null;
+    };
+    bytes?: number;
+    magic?: string;
+}
+/**
+ * 只读校验：目标位置上是否有一份可解析、id/cwd 都对得上的日志。
+ * @param options - `{root, sessionId, cwd, compression}`。
+ * @returns `{ok, header, bytes}` 或 `{ok:false, error}`。
+ */
+export declare function verifyStoredLog(options: VerifyStoredLogOptions): StoredLogVerification;