@morlay/session-rdb 0.0.16-alpha.1 → 0.0.16-alpha.4

package/dist/testing.mjs

@@ -5116,7 +5116,7 @@ function manageArtifactAttachment(attachment) {
 	if (attachment.body != null) attachment.bodyEncoding ??= "base64";
 }
 //#endregion
-//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.0_happy-dom@20.13.2_vite@8.2.2__9bde3b9553ba3388013323e9f29b314e/node_modules/vitest/dist/chunks/utils.BX5Fg8C4.js
+//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.1_happy-dom@20.14.3_vite@8.2.2__e05875f349154650201ff2ddb1226938/node_modules/vitest/dist/chunks/utils.BX5Fg8C4.js
 const NAME_WORKER_STATE = "__vitest_worker__";
 function getWorkerState() {
 	const workerState = globalThis[NAME_WORKER_STATE];
@@ -10019,10 +10019,10 @@ function offsetToLineNumber(source, offset) {
 	return line + 1;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.0_happy-dom@20.13.2_vite@8.2.2__9bde3b9553ba3388013323e9f29b314e/node_modules/vitest/dist/chunks/_commonjsHelpers.D26ty3Ew.js
+//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.1_happy-dom@20.14.3_vite@8.2.2__e05875f349154650201ff2ddb1226938/node_modules/vitest/dist/chunks/_commonjsHelpers.D26ty3Ew.js
 var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
 //#endregion
-//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.0_happy-dom@20.13.2_vite@8.2.2__9bde3b9553ba3388013323e9f29b314e/node_modules/vitest/dist/chunks/rpc.MzXet3jl.js
+//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.1_happy-dom@20.14.3_vite@8.2.2__e05875f349154650201ff2ddb1226938/node_modules/vitest/dist/chunks/rpc.MzXet3jl.js
 const RealDate = Date;
 let now = null;
 var MockDate = class MockDate extends RealDate {
@@ -10987,7 +10987,7 @@ function raceWith(promise, other) {
 	}))]);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.0_happy-dom@20.13.2_vite@8.2.2__9bde3b9553ba3388013323e9f29b314e/node_modules/vitest/dist/chunks/test.DNmyFkvJ.js
+//#region ../../node_modules/.pnpm/vitest@4.1.11_@opentelemetry+api@1.9.1_@types+node@26.5.1_happy-dom@20.14.3_vite@8.2.2__e05875f349154650201ff2ddb1226938/node_modules/vitest/dist/chunks/test.DNmyFkvJ.js
 var fakeTimersSrc = {};
 var global$1;
 var hasRequiredGlobal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/session-rdb",
-  "version": "0.0.16-alpha.1",
+  "version": "0.0.16-alpha.4",
   "description": "RDB durable session backend for DeepSeek Harness: implements both session-persistence and session-branch (rewind / retry / fork) providers.",
   "keywords": [
     "branch",
@@ -35,27 +35,32 @@
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
   "dependencies": {
-    "@morlay/session-branch": "^0.0.4-alpha.1",
+    "@morlay/session-branch": "^0.0.4-alpha.4",
     "drizzle-orm": "^1.0.0-rc.5-ab785fc",
     "fflate": "^0.8.2",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-token-meter": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-turn-outline": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage-json": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-token-meter": "^0.1.5-alpha.2",
     "@types/pg": "^8.23.1",
     "drizzle-kit": "1.0.0-rc.5-ab785fc"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-format": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-format-catalog": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-format": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-format-catalog": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-settings": "^0.1.5-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "dsh": {

package/src/branch.ts

@@ -66,12 +66,45 @@ export interface LiveSessionHooks {
   getAgent(id: SessionId): LiveAgentLike | undefined;
 
   flush(session: Session): Promise<boolean>;
+
+  // 丢弃 live 会话已缓存的投影单元：rewind 直接截断内存 log，投影 registry
+  // 的 observedSeq 仍停在截断前，后续 append 的事件（seq 更小）会被 drive()
+  // 跳过，重放输入永远进不了 inbox 投影。可选：纯持久化环境没有投影服务。
+  resetProjections?(session: Session): void;
+
+  // 用截断后的 log 重写该会话的持久化投影检查点：rewind 不会产生事件，
+  // 缓存行的水位（以及基于它折出的值）仍停在截断前。超前行不会被前端投影
+  // store 的 higher-seq-wins 规则覆盖（rewind 后的正确值 seq 更小），表现为
+  // 轮次导航残留被删除的旧轮次。可选：纯持久化环境没有投影缓存服务。
+  refreshProjectionCache?(session: ProjectionCacheSession): Promise<void>;
+}
+
+/**
+ * 投影检查点刷新所需的最小会话面：cold rewind 没有 live Session 可复用，
+ * 而截断后的前缀未必是合法的独立会话（surface 引用可能悬空），不能走
+ * `Session.create` 的校验；缓存服务只读 id / header / inheritedEventCount
+ * 与事件前缀，用普通对象承载即可。
+ */
+export interface ProjectionCacheSession {
+  readonly id: SessionId;
+  readonly header: SessionHeader;
+  readonly inheritedEventCount: SessionLogOffset;
+  snapshotEvents(): readonly SessionEvent[];
+}
+
+// 投影 registry 的失效面（上游私有结构，duck-type 读取）。
+interface ProjectionRegistryLike {
+  registrations?: Map<string, { cells: WeakMap<object, unknown> }>;
 }
 
 export interface LiveAgentLike {
   session: Session;
 
   requestHeaderLogged?: boolean;
+
+  // 上游 Agent 的 inbox 契约面（ReactLoopInbox.clear）：rewind 后残留的排队
+  // 输入必须 durable 取消，否则 agent 会继续处理它们。可选：测试替身可能没有。
+  inbox?: { clear(): void };
 }
 
 export function truncateLiveSession(session: Session, newLength: number): void {
@@ -246,8 +279,12 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     if (live !== undefined) await this.live.flush(live);
     // 边界校验用原始事件（readLog，不补 closers）——inspect 会给未闭合
     // log 补合成 closers，把 user/message 边界掩盖成 turn/end，丢失 exclusive
-    // 语义。
-    const raw = live === undefined ? await this.readRawEvents(id, signal) : undefined;
+    // 语义。cold 分支同时取回 inheritedEventCount：刷新投影检查点时要用它
+    // 重建与存储一致的会话身份。
+    const raw = live === undefined ? await this.persistence.readLog(id, {}, signal) : undefined;
+    if (live === undefined && raw === undefined) {
+      throw new SessionBranchError(`session "${id}" not found`, "SESSION_NOT_FOUND");
+    }
     const inspection =
       live === undefined ? undefined : await this.persistence.internals().inspect(id, signal);
     const events = live === undefined ? raw!.events : inspection!.events;
@@ -270,7 +307,8 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     // 编辑版替换）。exclusive 截断可能残留孤儿 step/start，经平衡化剔除。
     const rawKeepLength =
       toBoundary === -1 ? 0 : boundaryEvent!.type === "turn/end" ? toBoundary + 1 : toBoundary;
-    const keepLength = balanceRewindPrefix(events.slice(0, rawKeepLength)).length;
+    const kept = balanceRewindPrefix(events.slice(0, rawKeepLength));
+    const keepLength = kept.length;
 
     const internals = this.persistence.internals();
     // 原样存储（无过滤）：live 视图与 RDB head 同空间（上游 seq），
@@ -314,6 +352,9 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       // agent 轮次游标。不调用 load——live 时 load 会先 flush 把旧内存写回，
       // 撤销本次截断。
       truncateLiveSession(live, keepLength);
+      // 投影缓存同样停在截断前的水位，必须先失效，否则截断后的重放事件
+      // （seq 回退）不会进入投影。
+      this.live.resetProjections?.(live);
       const agent = this.live.getAgent(id);
       if (agent !== undefined) {
         agent.requestHeaderLogged = false;
@@ -330,6 +371,24 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       if (handle !== undefined) {
         handle.resetAfterRewind(keepLength, newSeedLength === null ? undefined : newSeedLength);
       }
+      // 截断后强制清空排队输入：保留区里未被截断的 pending（`agent/inbox/spliced`）
+      // 仍会被 agent 处理，必须 durable 取消。cursor 已对齐，取消事件从截断点续接。
+      agent?.inbox?.clear();
+      // 取消事件先经 coordinator 缓冲，落盘后 rewind 才真正 durable（调用方
+      // 可能在 rewind 返回后直接读后端）。
+      await this.live.flush(live);
+      // 持久化投影检查点也要退到截断后的水位：rewind 不产生事件，缓存行
+      // 会停在截断前；超前行锁死前端（higher-seq-wins），轮次导航残留旧轮次。
+      await this.refreshProjectionCache(live);
+    } else {
+      // cold：用截断后的前缀 + 存储身份构造最小会话面，让缓存服务按截断后
+      // 的 log 重写检查点（没有 live 会话可复用，也不为此 resume 一个 agent）。
+      await this.refreshProjectionCache({
+        id,
+        header: meta,
+        inheritedEventCount: SessionLogOffset(raw!.inheritedEventCount),
+        snapshotEvents: () => kept,
+      });
     }
 
     const row = await internals.backend.getSession(id);
@@ -354,6 +413,19 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     }
     return { header: rowToMeta(row), revision: (await internals.readStoredRevision(id))! };
   }
+
+  /**
+   * 让持久化投影检查点跟随截断后的 log（见 {@link LiveSessionHooks.refreshProjectionCache}）。
+   * 缓存是派生数据：刷新失败只让缓存多滞后一轮，不能让 rewind 失败。
+   */
+  private async refreshProjectionCache(session: ProjectionCacheSession): Promise<void> {
+    if (this.live.refreshProjectionCache === undefined) return;
+    try {
+      await this.live.refreshProjectionCache(session);
+    } catch {
+      // 实现方（SessionBranchRdb）已记日志；此处只保证 rewind 不因派生数据失败。
+    }
+  }
 }
 
 export class SessionBranchRdb extends SessionBranch {
@@ -375,6 +447,30 @@ export class SessionBranchRdb extends SessionBranch {
         return agents?.get(id);
       },
       flush: (session) => this.ctx.sessions.flush(session),
+      resetProjections: (session) => {
+        // sessionProjections 是可选服务（纯持久化环境无 agent-loop/投影）。
+        const registry = (this.ctx as unknown as { get(name: string): unknown }).get(
+          "sessionProjections",
+        ) as ProjectionRegistryLike | undefined;
+        if (registry?.registrations === undefined) return;
+        for (const registration of registry.registrations.values()) {
+          registration.cells.delete(session);
+        }
+      },
+      refreshProjectionCache: async (session) => {
+        // sessionProjectionCache 是可选服务（纯持久化环境无投影缓存）。
+        const cache = this.ctx.get("sessionProjectionCache") as
+          | { write(session: ProjectionCacheSession): Promise<void> }
+          | undefined;
+        if (cache === undefined) return;
+        try {
+          await cache.write(session);
+        } catch (error: unknown) {
+          this.ctx.logger.warn(
+            `session-rdb: projection cache refresh after rewind for "${session.id}" failed (cache stays stale): ${String(error)}`,
+          );
+        }
+      },
     },
   );
 

package/src/index.ts

@@ -560,6 +560,10 @@ export class SessionPersistenceRdb extends SessionPersistence {
       }
       const log = await this.readLog(id, {}, options?.signal);
       if (log === undefined) throw new SessionPersistenceNotFoundError(id);
+      // 读取视图修复必须先于校验：越界 replace（旧写入器重编号遗留的旧坐标）
+      // 降级/夹取、request/header 归一，否则上游事件校验 fail loud 拒绝整个
+      // 会话（load / open 是历史会话的加载入口，不能只依赖 handle.read）。
+      repairReadView(log.events);
       // fail-closed：未知事件类型（非 ignorable）拒绝解释。
       validateStoredEvents(log.meta, log.events);
       return this.tracker.adopt(
@@ -584,6 +588,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
       }
       const log = await this.readLog(id, {}, options?.signal);
       if (log === undefined) throw new SessionPersistenceNotFoundError(id);
+      repairReadView(log.events);
       validateStoredEvents(log.meta, log.events);
       // 迁移链会生成/合并事件（end-seed / attempt / chunk 合并），事件坐标与
       // 存储桥接行数不再相等——写打开时把迁移视图整体落库，使读写同坐标；
@@ -692,9 +697,9 @@ export class SessionPersistenceRdb extends SessionPersistence {
   }
 
   /** 原样 append 落库（handle 已校验 contiguity；torn tail 先截断）。
-   *  与上游 JSONL 一致：ignorable 事件原样存储，不做过滤。写路径校验 v2
-   *  形状（fail-closed）：未知类型（非 ignorable）与非法消息形状拒绝入库；
-   *  旧格式（v0/v1）数据只在读取时经 legacy 转换链动态转换，不落新库。 */
+   *  与上游 JSONL 一致：ignorable 事件原样存储，不做过滤。写路径校验当前
+   *  格式形状（fail-closed）：未知类型（非 ignorable）与非法消息形状拒绝入库；
+   *  非当前格式（v0/v1/v2）数据只在读取时经 legacy 转换链动态转换，不落新库。 */
   async appendBatch(
     meta: SessionHeader,
     inheritedEventCount: SessionLogOffset,
@@ -703,8 +708,8 @@ export class SessionPersistenceRdb extends SessionPersistence {
   ): Promise<boolean> {
     await this.ready;
     if (events.length === 0) return false;
-    // 写路径 v2 校验：与读路径同契约（validateStoredEvents），保证新入库
-    // 数据只能是 v2 形状。拷贝避免 adopt 替换污染调用方数组。
+    // 写路径当前格式校验：与读路径同契约（validateStoredEvents），保证新入库
+    // 数据只能是当前格式形状。拷贝避免 adopt 替换污染调用方数组。
     validateStoredEvents(meta, [...events]);
     // fork 派生会话的 seed 复用源会话事件行（不复制）；消费后清除。
     const reuse = this.reuseEventIds.get(meta.id);
@@ -763,7 +768,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
         /** 存储桥接行数（迁移链可能生成/合并事件，与 `events.length` 不同）。 */
         storedCount: number;
 
-        /** 是否经上游迁移链转换（v0/v1 → 当前格式）。 */
+        /** 是否经上游迁移链转换（非当前格式 → 当前格式）。 */
         migrated: boolean;
       }
     | undefined
@@ -779,10 +784,11 @@ export class SessionPersistenceRdb extends SessionPersistence {
         ? await this.backend.getEventRows(id)
         : await this.backend.getEventRows(id, options.fromSeq);
     signal?.throwIfAborted();
-    // 旧格式（v0/v1）历史数据：行重建为物理记录，经上游迁移链转 v2 逻辑事件。
-    // 迁移链自带 seq gap / torn tail 校验（strict recovery），无需 scanRows。
-    // 混合世代 log（旧写入器跨上游版本追加）不是任何单一已发布格式，迁移链
-    // 必然拒绝——回退为当前格式视图（header 版本归一 + 读取视图修复）。
+    // 非当前格式（v0/v1/v2）历史数据：行重建为物理记录，经上游迁移链转
+    // 当前逻辑事件。迁移链自带 seq gap / torn tail 校验（strict recovery），
+    // 无需 scanRows。混合世代 log（旧写入器跨上游版本追加）不是任何单一已
+    // 发布格式，迁移链必然拒绝——回退为当前格式视图（header 版本归一 +
+    // 读取视图修复）。
     if (isLegacyVersion(row.fVersion)) {
       try {
         const converted = convertLegacyRows(row, eventRows);
@@ -826,7 +832,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
   }
 
   /**
-   * 把迁移链读出的 v2 视图整体落库（旧格式会话写打开时的一次性迁移）。
+   * 把迁移链读出的当前格式视图整体落库（非当前格式会话写打开时的一次性迁移）。
    *
    * 迁移链会生成/合并事件（end-seed / attempt / chunk 合并），事件 seq 空间
    * 与存储桥接行数不再相等；写路径以存储 head 为锚点重编号，二者不一致会让
@@ -927,8 +933,8 @@ export class SessionPersistenceRdb extends SessionPersistence {
       );
       const row = await this.backend.getSession(id);
       if (row === undefined) throw new SessionPersistenceNotFoundError(id);
-      // 旧格式（v0/v1）会话：meta 与继承前缀来自转换链（handle.header 已是
-      // 转换后的 v2 header）；v2 会话用存储行。
+      // 非当前格式会话：meta 与继承前缀来自转换链（handle.header 已是转换后的
+      // 当前格式 header）；当前格式会话用存储行。
       if (isLegacyVersion(row.fVersion)) {
         return {
           meta: handle.header,

package/src/legacy.ts

@@ -1,5 +1,5 @@
-// 旧格式（v0/v1）历史数据读取转换：RDB 行 → v0/v1 物理记录 → 上游迁移链 →
-// v2 逻辑事件。RDB 写路径从不持久化 sourceEventSeqs（读取时重计算），且
+// 非当前格式（v0/v1/v2）历史数据读取转换：RDB 行 → 物理记录 → 上游迁移链 →
+// 当前逻辑事件。RDB 写路径从不持久化 sourceEventSeqs（读取时重计算），且
 // delta（assistant/chunk）落盘被过滤——v1→v2 迁移对无 chunk 引用的
 // assistant/message 走「无 pending 直接 emit」路径，生成 stream: [] 的 v2 事件。
 
@@ -11,39 +11,52 @@ import {
 } from "@deepseek-ai/dsh-session";
 import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
 import type { EventRow, SessionRow } from "./backend.ts";
-import { rowToMeta, scanRows } from "./log.ts";
+import { repairRequestHeaders, rowToMeta, scanRows } from "./log.ts";
 
-/** 重建 v0/v1 物理 header 记录（RDB 行 → 物理 JSON 对象）。 */
+/** 重建 v0/v1/v2 物理 header 记录（RDB 行 → 物理 JSON 对象）。 */
 function physicalHeader(row: SessionRow): Record<string, unknown> {
-  return {
+  const common = {
     type: "session",
     version: row.fVersion,
     id: row.fSessionId,
     createdAt: row.fCreatedAt,
     ...(row.fCwd !== null ? { cwd: row.fCwd } : {}),
     ...(row.fParentSession !== null ? { parentSession: row.fParentSession } : {}),
-    ...(row.fSeedLength !== null ? { seedLength: row.fSeedLength } : {}),
     ...(row.fOrigin !== null ? { origin: row.fOrigin } : {}),
     delegationDepth: row.fDelegationDepth ?? 0,
   };
+  // v0/v1 物理 header 用 seedLength 表达继承前缀；v2 起改用 isSeeded，
+  // 前缀长度由 log 里的 session/end-seed 标记推导。
+  return row.fVersion < 2
+    ? { ...common, ...(row.fSeedLength !== null ? { seedLength: row.fSeedLength } : {}) }
+    : { ...common, isSeeded: row.fSeedLength !== null };
 }
 
-/** 重建一条 v0/v1 物理事件记录（桥接行 + 事件行 → 物理 JSON 对象）。 */
+/** 重建一条 v0/v1/v2 物理事件记录（桥接行 + 事件行 → 物理 JSON 对象）。 */
 function physicalEvent(row: EventRow): Record<string, unknown> {
+  const stored = JSON.parse(row.fData) as unknown;
+  // 两种存储形状：当前写入器落完整事件信封（与 JSONL 每行同构），schema v2
+  // 时代只落 data 部分。迁移链要的是 payload，故信封形状取 `data`。
+  const full =
+    typeof stored === "object" &&
+    stored !== null &&
+    !Array.isArray(stored) &&
+    typeof (stored as Record<string, unknown>)["type"] === "string" &&
+    "data" in (stored as Record<string, unknown>);
   return {
     type: row.fType,
     seq: row.fSequence,
     time: row.fCreatedAt,
-    data: JSON.parse(row.fData) as unknown,
+    data: full ? (stored as Record<string, unknown>)["data"] : stored,
     ...(row.fSurfaceOp !== null ? { surfaceOp: JSON.parse(row.fSurfaceOp) as unknown } : {}),
   };
 }
 
 /**
- * 把旧格式（v0/v1）行转换为 v2 逻辑事件与 header。
- * @param row - 会话行（f_version < 2）。
+ * 把非当前格式（v0/v1/v2）行转换为当前逻辑事件与 header。
+ * @param row - 会话行（f_version < SESSION_FORMAT_VERSION）。
  * @param eventRows - 已扫描保留的桥接行（稠密 seq，torn tail 已剔除）。
- * @returns v2 逻辑 header、继承前缀长度与事件。
+ * @returns 当前逻辑 header、继承前缀长度与事件。
  * @throws 迁移链拒绝（格式损坏 / 无法迁移）时原样抛出。
  */
 export function convertLegacyRows(
@@ -65,9 +78,9 @@ export function convertLegacyRows(
   };
 }
 
-/** 会话行是否携带旧格式（v0/v1）数据。 */
+/** 会话行是否携带非当前格式（f_version < SESSION_FORMAT_VERSION）数据。 */
 export function isLegacyVersion(version: number): boolean {
-  return version < 2;
+  return version < SESSION_FORMAT_VERSION;
 }
 
 /**
@@ -82,7 +95,7 @@ export function isLegacyVersion(version: number): boolean {
  * 调用方须在此之后执行 `validateStoredEvents`：真正属于旧格式的类型
  * （`assistant/chunk` / `compact/*` 等）仍会被 fail-loud 拒绝。
  *
- * @param row - 会话行（f_version < 2）。
+ * @param row - 会话行（f_version < SESSION_FORMAT_VERSION）。
  * @param eventRows - 该会话全部桥接行（按 f_sequence 升序）。
  * @returns 当前格式 header（version 归一到 SESSION_FORMAT_VERSION）、收缩后的
  *   继承前缀长度、稠密事件与可选 torn tail 起点。
@@ -98,6 +111,11 @@ export function adoptLegacyRows(
   tornFrom?: number;
 } {
   const { preserved, tornFrom } = scanRows(eventRows, 0);
+  // 旧格式 request/header 归一为当前格式：v3 起 system prompt 由 surface 上的
+  // system/message 承载，header 必须省略 system / 空 tools / 空 adapterDefaults
+  // （上游事件校验 fail loud）。归一必须发生在调用方 `validateStoredEvents`
+  // 之前，否则整个会话加载失败。
+  repairRequestHeaders(preserved);
   return {
     meta: { ...rowToMeta(row), version: SESSION_FORMAT_VERSION },
     // 继承前缀不得超过事件数（历史 rewind 未收缩的损坏样式），上游 load 判损坏。