@morlay/session-rdb 0.0.20 → 0.0.21-alpha.0

package/src/entities/v3/event-usage.ts

@@ -0,0 +1,25 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+/**
+ * 用量日志：一条 `assistant/message` 事件一行（按事件行唯一，fork 共享行不重复）。
+ * 统计只读这张表，不再逐行解析事件的 JSON；事件行本身仍留在 `t_events`。
+ */
+export const eventUsage: TableDef = {
+  name: "t_event_usage",
+  columns: {
+    f_event_id: {
+      type: "text",
+      primaryKey: true,
+      references: { table: "t_events", column: "f_event_id", onDelete: "cascade" },
+    },
+    f_created_at: { type: "integer", notNull: true },
+    f_provider: { type: "text" },
+    f_model: { type: "text" },
+    f_input_tokens: { type: "integer", notNull: true },
+    f_output_tokens: { type: "integer", notNull: true },
+    f_cache_read_tokens: { type: "integer", notNull: true },
+    f_reasoning_tokens: { type: "integer", notNull: true },
+    f_total_tokens: { type: "integer", notNull: true },
+  },
+  indexes: { idx_event_usage_created_at: { columns: ["f_created_at"] } },
+};

package/src/entities/v3/events.ts

@@ -15,9 +15,7 @@ export const events: TableDef = {
     f_data: { type: "text", notNull: true },
     f_created_at: { type: "bigint", notNull: true, default: 0 },
   },
-  // 查询经 f_event_id（列级 UNIQUE 唯一索引）与 t_session_events 复合索引
-  // （按 session 过滤后回表）；f_parent_id 仅写路径构造；维度列索引为
-  // 审计/UI 过滤预留。
+
   indexes: {
     idx_events_kind: { columns: ["f_kind"] },
     idx_events_role: { columns: ["f_role"] },

package/src/entities/v3/index.ts

@@ -8,6 +8,7 @@ import { workspaces } from "./workspaces.ts";
 import { workspaceSessions } from "./workspace-sessions.ts";
 import { workspaceState } from "./workspace-state.ts";
 import { sessionProjcacheRows } from "./session-projcache-rows.ts";
+import { eventUsage } from "./event-usage.ts";
 
 export { persistenceState };
 export { schemaMeta };
@@ -19,6 +20,7 @@ export { workspaces };
 export { workspaceSessions };
 export { workspaceState };
 export { sessionProjcacheRows };
+export { eventUsage };
 
 export const sqliteTableDefs = [
   persistenceState,
@@ -31,6 +33,7 @@ export const sqliteTableDefs = [
   workspaceSessions,
   workspaceState,
   sessionProjcacheRows,
+  eventUsage,
 ] as const;
 
 export const postgresTableDefs = [
@@ -44,4 +47,5 @@ export const postgresTableDefs = [
   workspaceSessions,
   workspaceState,
   sessionProjcacheRows,
+  eventUsage,
 ] as const;

package/src/entities/v3/session-events.ts

@@ -20,7 +20,6 @@ export const sessionEvents: TableDef = {
   uniques: {
     uq_session_events_session_sequence: { columns: ["f_session_id", "f_sequence"] },
   },
-  // UNIQUE(f_session_id, f_sequence) 自动建唯一索引（按 session 过滤 + seq
-  // 范围/排序/取尾）；f_event_id 索引覆盖反向查找（孤儿事件行清理）。
+
   indexes: { idx_session_events_event_id: { columns: ["f_event_id"] } },
 };

package/src/entities/v3/session-projcache-rows.ts

@@ -1,13 +1,5 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * 投影 checkpoint 行（上游 checkpoint 的 `(sessionId, key, ver, seq, val)`
- * 逐行落库）：`f_seq` 是该行的日志水位、`f_ver` 是投影单元的 stateVersion。
- * 行是折出捷径、非权威，版本不匹配时整行丢弃。
- *
- * checkpoint 的日志 identity 不另存一份：它与 `t_sessions` 的行是 1:1，直接
- * 复用该行的 `f_version` / `f_created_at` / `f_cwd` / `f_seed_length` 做校验。
- */
 export const sessionProjcacheRows: TableDef = {
   name: "t_session_projcache_row",
   columns: {

package/src/entities/v3/sessions.ts

@@ -16,11 +16,11 @@ export const sessions: TableDef = {
     f_delegation_depth: { type: "integer" },
     f_incarnation: { type: "text", notNull: true },
     f_revision: { type: "integer", notNull: true },
-    /** 归档标记：非空即该会话已归档（毫秒时间戳），NULL 表示未归档。 */
+
     f_archived_at: { type: "bigint" },
-    /** 最新会话标题（最后一条 `session/title` 事件的 title），NULL 表示尚无标题。 */
+
     f_title: { type: "text" },
-    /** `f_title` 来源事件的稠密 seq（列表 hint 的水位）。 */
+
     f_title_seq: { type: "integer" },
   },
 };

package/src/entities/v3/storage-units.ts

@@ -1,6 +1,5 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/** storage 域版本账本：域首次打开时写入 descriptor version，其后按 accepted 集合校验。 */
 export const storageUnits: TableDef = {
   name: "t_storage_units",
   columns: {

package/src/entities/v3/workspace-sessions.ts

@@ -1,10 +1,5 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * workspace 的会话归属（上游 `workspaceRecord.sessionIds` 的数组顺序）：
- * 一个会话一行，`f_position` 是归属显示顺序。会话 id 有独立索引，可按
- * session 反查归属 workspace。
- */
 export const workspaceSessions: TableDef = {
   name: "t_workspace_sessions",
   columns: {

package/src/entities/v3/workspace-state.ts

@@ -1,11 +1,5 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * workspace 域 global 单例（上游 `workspaceDomainState`）：`initialized` 是
- * 引导标记，`pendingMutation` 拆成操作与目标两列（create / delete 的可恢复
- * 两写标记）。显示顺序（`workspaceIds`）在 `t_workspaces.f_position`，
- * 归档集由 `t_sessions.f_archived_at` 承载（归档不触碰归属槽位）。
- */
 export const workspaceState: TableDef = {
   name: "t_workspace_state",
   columns: {

package/src/entities/v3/workspaces.ts

@@ -1,10 +1,5 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * workspace 域记录表（上游 `workspace` 域 v2 的 `workspaces` 表）：
- * 记录本身拆成语义列；会话归属在 {@link workspaceSessions}（带顺序），
- * 显示顺序由 `f_position` 承载（未进入 `workspaceIds` 的记录为 -1）。
- */
 export const workspaces: TableDef = {
   name: "t_workspaces",
   columns: {

package/src/export.ts

@@ -0,0 +1,103 @@
+import { strToU8, zip } from "fflate";
+import type { Context } from "@deepseek-ai/cordis";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionPersistenceRdb } from "./index.ts";
+
+export const SESSION_EXPORT_PATH = "/api/session.export";
+
+/** 文件名只保留安全字符：会话 id 来自请求体，会写进 Content-Disposition。 */
+function safeFilename(sessionId: string): string {
+  return sessionId.replace(/[^A-Za-z0-9._-]/gu, "_");
+}
+
+/** fflate 只给回调式异步 API（同步变体被 node/no-sync 禁止）。 */
+function zipBytes(files: Record<string, Uint8Array>): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    zip(files, (error, data) => {
+      if (error === null) resolve(data);
+      else reject(error);
+    });
+  });
+}
+
+/** 导出通道：直接把会话日志打成 zip 响应体，与导入通道读同一份 artifact。 */
+export function registerSessionExport(ctx: Context, persistence: SessionPersistenceRdb): void {
+  ctx.inject(["webServer", "connection"] as const, (webCtx) => {
+    const webServer = webCtx.webServer as unknown as {
+      register(route: {
+        kind: "exact";
+        path: string;
+        handler: (
+          req: import("node:http").IncomingMessage,
+          res: import("node:http").ServerResponse,
+        ) => void | Promise<void>;
+      }): () => void;
+    };
+    const connection = webCtx.get("connection") as unknown as {
+      requestRejection(request: {
+        headers: import("node:http").IncomingHttpHeaders;
+      }): number | undefined;
+    };
+    return webCtx.effect(
+      () =>
+        webServer.register({
+          kind: "exact",
+          path: SESSION_EXPORT_PATH,
+          handler: async (req, res) => {
+            const rejection = connection.requestRejection(req);
+            if (rejection !== undefined) {
+              res.writeHead(rejection);
+              res.end(rejection === 401 ? "unauthorized" : "forbidden");
+              return;
+            }
+            if (req.method !== "POST") {
+              res.writeHead(405, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: "method not allowed" }));
+              return;
+            }
+            const chunks: Buffer[] = [];
+            for await (const chunk of req) chunks.push(chunk as Buffer);
+            let envelope: { sessionId?: unknown };
+            try {
+              envelope = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
+                sessionId?: unknown;
+              };
+            } catch {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: "request body is not JSON" }));
+              return;
+            }
+            if (typeof envelope.sessionId !== "string" || envelope.sessionId === "") {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: "missing sessionId field" }));
+              return;
+            }
+            const sessionId = envelope.sessionId;
+            try {
+              const raw = await persistence.readRaw(sessionId as SessionId);
+              if (raw === undefined) {
+                res.writeHead(404, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: `session "${sessionId}" not found` }));
+                return;
+              }
+              const zipFile = await zipBytes({ [raw.filename]: strToU8(raw.content) });
+              res.writeHead(200, {
+                "content-type": "application/zip",
+                "content-length": String(zipFile.byteLength),
+                "content-disposition": `attachment; filename="${safeFilename(sessionId)}.zip"`,
+              });
+              res.end(Buffer.from(zipFile));
+            } catch (error: unknown) {
+              res.writeHead(500, { "content-type": "application/json" });
+              res.end(
+                JSON.stringify({
+                  error: error instanceof Error ? error.message : "session export failed",
+                }),
+              );
+            }
+          },
+        }),
+      `session-rdb: ${SESSION_EXPORT_PATH} route`,
+    );
+  });
+}

package/src/gc.ts

@@ -0,0 +1,76 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { SessionPersistenceRdb } from "./index.ts";
+
+export const SESSION_GC_PATH = "/api/session.gc";
+
+interface GcAgentLike {
+  cancel?(cause: { kind: "user" }, options?: { keepInbox?: boolean }): void;
+  whenIdle(): Promise<void>;
+}
+
+/** 让所有运行中的 agent 先退场：GC 要重写事件表，运行中的写路径必须停下来。 */
+async function stopRunningAgents(ctx: Context): Promise<number> {
+  const agents = ctx.get("agents") as { list(): GcAgentLike[] } | undefined;
+  const running = agents?.list() ?? [];
+  for (const agent of running) agent.cancel?.({ kind: "user" }, { keepInbox: true });
+  await Promise.all(running.map((agent) => agent.whenIdle()));
+  return running.length;
+}
+
+/** GC 通道：停 agent → 回收孤儿事件行 → VACUUM，一次请求完成。 */
+export function registerSessionGc(ctx: Context, persistence: SessionPersistenceRdb): void {
+  ctx.inject(["webServer", "connection"] as const, (webCtx) => {
+    const webServer = webCtx.webServer as unknown as {
+      register(route: {
+        kind: "exact";
+        path: string;
+        handler: (
+          req: import("node:http").IncomingMessage,
+          res: import("node:http").ServerResponse,
+        ) => void | Promise<void>;
+      }): () => void;
+    };
+    const connection = webCtx.get("connection") as unknown as {
+      requestRejection(request: {
+        headers: import("node:http").IncomingHttpHeaders;
+      }): number | undefined;
+    };
+    return webCtx.effect(
+      () =>
+        webServer.register({
+          kind: "exact",
+          path: SESSION_GC_PATH,
+          handler: async (req, res) => {
+            const rejection = connection.requestRejection(req);
+            if (rejection !== undefined) {
+              res.writeHead(rejection);
+              res.end(rejection === 401 ? "unauthorized" : "forbidden");
+              return;
+            }
+            if (req.method !== "POST") {
+              res.writeHead(405, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: "method not allowed" }));
+              return;
+            }
+            try {
+              const stoppedAgents = await stopRunningAgents(webCtx);
+              // 先回收孤儿会话，再回收事件行：被删会话独占的事件行才刚成为孤儿。
+              const orphanSessions = await persistence.collectOrphanSessions();
+              const orphanEvents = await persistence.collectOrphans();
+              await persistence.vacuum();
+              res.writeHead(200, { "content-type": "application/json" });
+              res.end(
+                JSON.stringify({ orphanSessions, orphanEvents, stoppedAgents, vacuumed: true }),
+              );
+            } catch (error: unknown) {
+              res.writeHead(500, { "content-type": "application/json" });
+              res.end(
+                JSON.stringify({ error: error instanceof Error ? error.message : "gc failed" }),
+              );
+            }
+          },
+        }),
+      `session-rdb: ${SESSION_GC_PATH} route`,
+    );
+  });
+}

package/src/import-storages.ts

@@ -1,14 +1,3 @@
-/**
- * 一次性导入：把旧 `$DSH_HOME/storages` 的 JSON 数据搬进 session-rdb 的
- * 语义专用表（显式命令触发，不做启动隐式导入）。旧文件保留不删，便于对账与
- * 回退。
- *
- * 支持两种来源布局：
- * - `workspace.json`：single 文档（`{unit, global, tables}`）；
- * - `session_projcache/sessions/*.json`：v7 per-record 文档；目录缺失时回退
- *   读旧 single 文档 `session_projcache.json`。
- */
-
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import type {
@@ -19,41 +8,30 @@ import type {
 } from "./storage-takeover/types.ts";
 import { SessionId } from "@deepseek-ai/dsh-session";
 
-/** 一条待导入的投影 checkpoint：identity 不落库（复用会话行），只导行。 */
 interface ImportedProjcache {
   sessionId: SessionId;
   rows: ProjectionCheckpoint;
 }
 
-/** 导入统计（按记录数）。 */
 export interface StoragesImportResult {
-  /** 导入的 workspace 记录数。 */
   workspaces: number;
-  /** 是否导入了 workspace global 单例。 */
+
   workspaceState: boolean;
-  /** 导入的投影 checkpoint 记录数。 */
+
   projcache: number;
 }
 
-/** 导入参数。 */
 export interface StoragesImportOptions {
-  /** Harness home（含 `storages/` 的目录）。 */
   dshHome: string;
 }
 
 const WORKSPACE_UNIT = "workspace";
-/** 旧 workspace 文档可接受的域版本集（对齐上游 `workspaceDomainSpec`，见对齐测试）。 */
+
 export const WORKSPACE_UNIT_VERSIONS: ReadonlySet<number> = new Set([2]);
 const PROJCACHE_UNIT = "session_projcache";
-/** 旧投影缓存文档可接受的域版本集（对齐上游 spec 的 version ∪ compatibleVersions）。 */
+
 export const PROJCACHE_UNIT_VERSIONS: ReadonlySet<number> = new Set([7, 3, 4, 5, 6]);
 
-/**
- * Import the legacy storages documents into the rdb tables.
- * @param repository - storages takeover access layer (medium already open).
- * @param options - harness home holding the legacy `storages/` tree.
- * @returns per-record import counts.
- */
 export async function importStorages(
   repository: StorageRepository,
   options: StoragesImportOptions,
@@ -85,8 +63,6 @@ export async function importStorages(
       PROJCACHE_UNIT_VERSIONS.values().next().value as number,
     );
     for (const entry of projcacheEntries) {
-      // 只导行：checkpoint 的 identity 由 t_sessions 的行承载（会话不存在时
-      // 外键拒绝写入，导入 fail loud）。
       await repository.putProjcache(entry.sessionId, entry.rows);
       result.projcache += 1;
     }
@@ -95,7 +71,6 @@ export async function importStorages(
   return result;
 }
 
-/** Read one JSON document; a missing file is `undefined`, malformed JSON fails loud. */
 async function readJson(path: string): Promise<Record<string, unknown> | undefined> {
   let text: string;
   try {
@@ -107,7 +82,6 @@ async function readJson(path: string): Promise<Record<string, unknown> | undefin
   return JSON.parse(text) as Record<string, unknown>;
 }
 
-/** Validate one legacy single document's unit identity and return its tables map. */
 function unitTables(
   document: Record<string, unknown>,
   name: string,
@@ -129,10 +103,6 @@ function unitTables(
   return tables as Record<string, Record<string, unknown>>;
 }
 
-/**
- * Read projection checkpoints from the per-record directory, falling back to
- * the legacy whole-unit document when the directory is absent.
- */
 async function readProjcacheEntries(storagesRoot: string): Promise<ImportedProjcache[]> {
   const entries: ImportedProjcache[] = [];
   const sessionsDir = join(storagesRoot, PROJCACHE_UNIT, "sessions");
@@ -149,8 +119,6 @@ async function readProjcacheEntries(storagesRoot: string): Promise<ImportedProjc
       | undefined;
     if (document === undefined) continue;
     if (typeof document.version !== "number" || !PROJCACHE_UNIT_VERSIONS.has(document.version)) {
-      // Stale per-record document: the cache reads it as absent, so the import
-      // discards it too instead of stamping it current.
       continue;
     }
     const record = document.record as { identity?: unknown; rows?: unknown } | undefined;
@@ -163,7 +131,6 @@ async function readProjcacheEntries(storagesRoot: string): Promise<ImportedProjc
   return entries;
 }
 
-/** Read the legacy whole-unit projection cache document (`{unit, tables:{sessions}}`). */
 async function readLegacyProjcache(path: string): Promise<ImportedProjcache[]> {
   const document = await readJson(path);
   if (document === undefined) return [];

package/src/import.ts

@@ -5,11 +5,11 @@ import type { Session, SessionEvent, SessionId, SessionHeader } from "@deepseek-
 import { parseSessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
 import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
-import { unzipSync } from "fflate";
+import { balanceRewindPrefix } from "@morlay/session-branch";
+import { unzip } from "fflate";
 import { replaceLiveSessionLog } from "./branch.ts";
 import type { SessionPersistenceRdb } from "./index.ts";
 
-/** 当前世代产物的文件名（读入侧接受任意 canonical 世代名，见 parseImportZip）。 */
 export const SESSION_LOG_ARTIFACT_FILENAME = "session.jsonl";
 
 export const SESSION_IMPORT_PATH = "/api/session.import";
@@ -29,7 +29,7 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
   } catch {
     throw new Error("imported session log has an unparsable header line");
   }
-  // 经 format catalog 恢复：v2 直接解码，历史版本走迁移链。
+
   let restore: ReturnType<typeof sessionFormatCatalog.createRestore>;
   try {
     restore = sessionFormatCatalog.createRestore(header, {
@@ -72,7 +72,7 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
   }
   const meta = artifact.header as SessionHeader;
   const events = artifact.events as SessionEvent[];
-  // 连续性校验：导入的 log 必须是从 0 开始的稠密 seq（落库前的最后一道闸）。
+
   for (let i = 0; i < events.length; i++) {
     if (events[i]!.seq !== i) {
       throw new Error(
@@ -80,8 +80,7 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
       );
     }
   }
-  // 继承前缀长度不得超过事件总数（上游 load 判损坏）；导出已收缩，此处
-  // 防御性收缩非自洽的 artifact。
+
   const inheritedEventCount = Math.min(artifact.inheritedEventCount, events.length);
   return {
     meta: {
@@ -100,17 +99,30 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
   };
 }
 
-export function parseImportZip(zip: Uint8Array): SessionStorageMetadata & {
-  events: SessionEvent[];
-} {
+/**
+ * fflate 的 `unzip` 是回调式异步 API（node 侧内部走 worker_threads，浏览器侧走 Web Worker），
+ * 这里桥成 Promise。它与 `unzipSync` 的差异只在同步/异步：非法 zip 走的是同一段校验代码，
+ * 拒绝的错误对象与同步版一致，因此上层文案无需区分。
+ */
+function unzipAsync(data: Uint8Array): Promise<Record<string, Uint8Array>> {
+  return new Promise((resolve, reject) => {
+    unzip(data, (error, entries) => {
+      if (error === null) resolve(entries);
+      else reject(error);
+    });
+  });
+}
+
+export async function parseImportZip(
+  zip: Uint8Array,
+): Promise<SessionStorageMetadata & { events: SessionEvent[] }> {
   let entries: Record<string, Uint8Array>;
   try {
-    entries = unzipSync(zip);
+    entries = await unzipAsync(zip);
   } catch {
     throw new Error("imported zip is not a valid ZIP archive");
   }
-  // 上游导出按世代命名（`session.v3.jsonl`），早期 rdb 导出沿用 `session.jsonl`：
-  // 两者都接受，按 canonical 名字规则识别（临时/大写/压缩后缀名不视为产物）。
+
   const artifact = Object.entries(entries).find(
     ([name]) => parseSessionFormatLogFilename(name) !== undefined,
   );
@@ -123,14 +135,11 @@ export function parseImportZip(zip: Uint8Array): SessionStorageMetadata & {
   return parseJsonlArtifact(new TextDecoder().decode(artifact[1]));
 }
 
-// 上游 Agent 的取消面（duck-type）：停止运行中的 loop。
 interface ImportAgentLike {
   cancel?(cause: { kind: "user" }, options?: { keepInbox?: boolean }): void;
   whenIdle(): Promise<void>;
 }
 
-// persistImport 会先 rewind(-1) 截断 live 会话的内存 log，不能与 agent 写日志
-// 并发；keepInbox 保留排队输入（截断后由 rewind 的 live 钩子 durable 取消）。
 async function stopAgentLoop(ctx: Context, sessionId: SessionId): Promise<void> {
   const agents = ctx.get("agents") as
     | { get(id: SessionId): ImportAgentLike | undefined }
@@ -143,29 +152,37 @@ async function stopAgentLoop(ctx: Context, sessionId: SessionId): Promise<void>
 
 export async function persistImport(
   persistence: SessionPersistenceRdb,
-  branch: { rewind(id: SessionId, toBoundary: number): Promise<unknown> } | undefined,
+  branch:
+    | {
+        rewind(id: SessionId, toBoundary: number): Promise<unknown>;
+
+        resetLiveDerivedState?(session: Session): void;
+      }
+    | undefined,
   imported: SessionStorageMetadata & { events: SessionEvent[] },
   targetId?: SessionId,
   sessions?: { get(id: SessionId): Session | undefined },
   stopLoop?: (id: SessionId) => Promise<void>,
 ): Promise<SessionId> {
   const id = targetId ?? (`session-${randomUUID()}` as SessionId);
+  // 整段导入的日志先配平：已不平衡的尾部会让接收会话的 token-meter 折叠在续写时报 step/end 无配对。
+  // 尾部未闭合的 step 是中断运行的正常形状，由上游 resume 补 closers，保持原样。
+  const events = balanceRewindPrefix(imported.events, { keepOpenTail: true });
   if (targetId !== undefined) {
     if (branch === undefined) {
       throw new Error("sessionBranch service is unavailable");
     }
-    // 覆盖语义先 rewind(-1) 截断：停止运行中的 loop（未注入端口时空操作）。
+
     if (stopLoop !== undefined) await stopLoop(targetId);
     await branch.rewind(targetId, -1);
-    // rewind 截断后追加导入事件（覆盖语义）。live 会话的 write handle 由
-    // live 路由持有——复用而非 open（open 会撞 SessionAlreadyOwnedError）。
+
     const liveHandle = persistence.tracker.writerOf(targetId);
     if (liveHandle !== undefined) {
-      if (imported.events.length > 0) await liveHandle.append(imported.events);
+      if (events.length > 0) await liveHandle.append(events);
     } else {
       const handle = await persistence.open(targetId, "write");
       try {
-        if (imported.events.length > 0) await handle.append(imported.events);
+        if (events.length > 0) await handle.append(events);
       } finally {
         await handle.close();
       }
@@ -173,24 +190,27 @@ export async function persistImport(
   } else {
     const handle = await persistence.create(
       { ...imported.meta, id },
-      { inheritedEventCount: imported.inheritedEventCount },
+      {
+        inheritedEventCount: SessionLogOffset(
+          Math.min(imported.inheritedEventCount, events.length),
+        ),
+      },
     );
-    if (imported.events.length > 0) await handle.append(imported.events);
+    if (events.length > 0) await handle.append(events);
     await handle.close();
   }
-  // 覆盖语义的 live 同步：rewind 截断的 live log 由同一批导入事件补回
-  // （不发布、不落库），使 observeSession 的 live 快照与 DB 一致。
+
   if (targetId !== undefined) {
     const live = sessions?.get(targetId);
-    if (live !== undefined) replaceLiveSessionLog(live, imported.events);
+    if (live !== undefined) {
+      replaceLiveSessionLog(live, events);
+      branch?.resetLiveDerivedState?.(live);
+    }
   }
   return id;
 }
 
 export function registerSessionImport(ctx: Context, persistence: SessionPersistenceRdb): void {
-  // webServer / connection 由其他插件注册，本后端构造早于它们——用
-  // ctx.inject 延迟到两个服务就绪后再注册 exact route（disposer 随 fiber
-  // 卸载自动回滚）；服务缺失（headless 装配、纯后端测试）时注入永不触发。
   ctx.inject(["webServer", "connection"] as const, (webCtx) => {
     const webServer = webCtx.webServer as unknown as {
       register(route: {
@@ -261,7 +281,7 @@ export function registerSessionImport(ctx: Context, persistence: SessionPersiste
             }
             let imported: SessionStorageMetadata & { events: SessionEvent[] };
             try {
-              imported = parseImportZip(zip);
+              imported = await parseImportZip(zip);
             } catch (error: unknown) {
               res.writeHead(400, { "content-type": "application/json" });
               res.end(
@@ -276,7 +296,10 @@ export function registerSessionImport(ctx: Context, persistence: SessionPersiste
                 ? (envelope.sessionId as SessionId)
                 : undefined;
             const branch = webCtx.get("sessionBranch") as unknown as
-              | { rewind(id: SessionId, toBoundary: number): Promise<unknown> }
+              | {
+                  rewind(id: SessionId, toBoundary: number): Promise<unknown>;
+                  resetLiveDerivedState?(session: Session): void;
+                }
               | undefined;
             try {
               const sessions = webCtx.get("sessions") as