@morlay/session-rdb 0.0.21-alpha.4 → 0.0.21-alpha.6

package/drizzle/sqlite/20260922090000_v3_pinned_seq/migration.sql

@@ -0,0 +1,4 @@
+-- 只加一列：上游 0.1.7 的 workspace registry 状态多了 `pinnedSessionIds`（钉住的会话 id 集合，
+-- 最近钉住的在前；归档与钉住互斥）。归档在本库里用会话行的 `f_archived_at` 表达，钉住同理用
+-- 一个序号列：值是它在集合里的位置，读回即按它排序。
+ALTER TABLE `t_sessions` ADD `f_pinned_seq` integer;

package/drizzle/sqlite/20260922093000_v3_last_event_at/migration.sql

@@ -0,0 +1,13 @@
+-- 「最后活动时间」物化到会话行：管理面的会话列表要按它排序 + 分页，原先每行一次「该会话最后事件时间」的
+-- 相关子查询（真实库 243 行 = 4.2s）在分页下也救不了——排序要求全表先把值算出来。加列后排序与分页都只
+-- 碰 t_sessions（毫秒级），写路径负责维护；这里一次性回填，没有事件的会话留 NULL（读时回落 createdAt）。
+-- 类型写 `integer`（不是 `bigint`）：STRICT 表只认固定类型名，`bigint` 会被拒。
+ALTER TABLE `t_sessions` ADD `f_last_event_at` integer;
+--> statement-breakpoint
+UPDATE `t_sessions`
+   SET `f_last_event_at` = (
+         SELECT MAX(e.f_created_at)
+           FROM t_session_events se
+           JOIN t_events e ON e.f_event_id = se.f_event_id
+          WHERE se.f_session_id = t_sessions.f_session_id
+       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/session-rdb",
-  "version": "0.0.21-alpha.4",
+  "version": "0.0.21-alpha.6",
   "description": "RDB durable session backend for DeepSeek Harness: implements both session-persistence and session-branch (rewind / retry / fork) providers.",
   "keywords": [
     "branch",
@@ -39,35 +39,35 @@
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
   "dependencies": {
-    "@morlay/session-branch": "0.0.10-alpha.4",
+    "@morlay/session-branch": "0.0.10-alpha.6",
     "drizzle-orm": "^1.0.0-rc.5-ab785fc",
     "fflate": "^0.8.2",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session-projection": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-turn-outline": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-token-meter": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-workspace": "0.1.6-alpha.2",
+    "@deepseek-ai/dsh-compaction": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-projection-cache": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-turn-outline": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage-domain": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-token-meter": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-workspace": "0.1.7-alpha.1",
     "@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.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-format": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-query": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-settings": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage": "0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "3.18.2"
+    "@deepseek-ai/cordis": "4.0.3",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-scope": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-format": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-query": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage": "0.1.7-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.3"
   },
   "dsh": {
     "bundle": {

package/src/backend.ts

@@ -15,12 +15,17 @@ export interface SessionRow {
   fSeedLength: number | null;
   fOrigin: string | null;
   fDelegationDepth: number | null;
+  fAgentPreset: string | null;
 
   fIncarnation: string;
 
   fRevision: number;
 
   fArchivedAt: number | null;
+
+  fPinnedSeq: number | null;
+
+  fLastEventAt: number | null;
 }
 
 export interface EventInsert {
@@ -82,7 +87,8 @@ export interface BackendTx {
 
   updateHead(id: SessionId, headEventId: string, headSequence: number): Promise<void>;
 
-  bumpRevision(id: SessionId): Promise<void>;
+  /** 写批次提交时递增 revision；给了 `lastEventAt` 就一并把「最后活动时间」往前推（只增不减）。 */
+  bumpRevision(id: SessionId, lastEventAt?: number): Promise<void>;
 
   deleteBridgeTail(id: SessionId, fromSequence: number): Promise<void>;
 
@@ -97,6 +103,42 @@ export interface BackendTx {
   deleteSessions(ids: SessionId[]): Promise<number>;
 }
 
+/**
+ * 「会话行」列表项：管理面自己的列表用（完整语料，含归档）+ 标题 + 最后活动时间。
+ *
+ * 与官方列表（`session/list` → `ctx.sessionQuery.listSessions`）的区别：那条按部署策略**默认排除归档**，
+ * 这里给的是完整集合，标题也直接带出来（官方那条的标题走投影缓存）。
+ */
+export interface SessionListRowRecord {
+  sessionId: string;
+  title: string | null;
+  origin: string | null;
+  cwd: string | null;
+  createdAt: number;
+  /** 该会话最后一个事件的时间（没有事件时回落 `createdAt`）。 */
+  updatedAt: number;
+  archived: boolean;
+  subagent: boolean;
+  /** 所属工作区标题；不属于任何工作区时为 null。 */
+  workspace: string | null;
+}
+
+/** 会话行列表的查询条件：搜索、子代理过滤与分页都在后端做（前端分页等于每次拉全量）。 */
+export interface SessionListRowsQuery {
+  /** 匹配标题或所属工作区标题（大小写不敏感）；空串即不过滤。 */
+  query?: string;
+  /** 是否连子代理派生会话一起返回（默认不含）。 */
+  includeSubagents?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export interface SessionListRowsPage {
+  items: SessionListRowRecord[];
+  /** 过滤后的总数（分页前的），前端据此算页数。 */
+  total: number;
+}
+
 /** 活动计数的一个桶：本地日 + 事件类型 + 计数。 */
 export interface EventCountBucket {
   day: string;
@@ -142,6 +184,9 @@ export interface Backend {
    */
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
 
+  /** 管理面的会话行列表：完整语料（含归档）+ 标题 + 最后活动时间，按活动倒序分页。 */
+  listSessionRows(query?: SessionListRowsQuery): Promise<SessionListRowsPage>;
+
   /**
    * 活动计数**旁路累加**（派生表 `t_event_counts`，不参与写事务、失败可丢——表可销毁重建）：
    * 每个 (会话, 本地日, 事件类型) 记一行计数。

package/src/branch.ts

@@ -278,21 +278,38 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
     const seed = [...renumber(prefix, 0), ...renumber(seedSuffix, prefix.length)];
 
     const internals = this.persistence.internals();
-    const sourceRows = await internals.backend.getEventRows(sourceId);
-    const sourceEventIds = new Map(sourceRows.map((row) => [row.fSequence, row.fEventId]));
+    // 复用父会话的事件行有个前提：**读取视图的 seq 与存储行的 f_sequence 一一对应**。legacy 会话的读视图
+    // 由迁移链重建（可能重新编号、增删事件），按 seq 复用会把桥接行挂到语义不符的行上——读取时按 `f_data`
+    // 解析，子会话前缀读到的内容就会和它自己的 seed 事件对不上。那种情况下复制事件行（多几行存储，正确优先）。
+    const reusable = !source.migrated && source.events.length === source.storedCount;
     const reuse = new Map<number, string>();
-    for (const event of prefix) {
-      const eventId = sourceEventIds.get(event.seq);
-      if (eventId !== undefined) reuse.set(event.seq, eventId);
+    if (reusable) {
+      const sourceRows = await internals.backend.getEventRows(sourceId);
+      const sourceEventIds = new Map(sourceRows.map((row) => [row.fSequence, row.fEventId]));
+      for (const event of prefix) {
+        const eventId = sourceEventIds.get(event.seq);
+        if (eventId !== undefined) reuse.set(event.seq, eventId);
+      }
+    } else if (prefix.length > 0) {
+      this.live.warn?.(
+        `session-rdb: fork "${sourceId}" copies event rows instead of reusing them — its read view comes from a migration, so stored seqs need not line up`,
+      );
     }
     internals.registerReuseEventIds(childId, reuse);
-    const handle = await this.persistence.create(childMeta, {
-      inheritedEventCount: SessionLogOffset(prefix.length),
-    });
     try {
-      if (seed.length > 0) await handle.append(seed);
-    } finally {
-      await handle.close();
+      const handle = await this.persistence.create(childMeta, {
+        inheritedEventCount: SessionLogOffset(prefix.length),
+      });
+      try {
+        if (seed.length > 0) await handle.append(seed);
+      } finally {
+        await handle.close();
+      }
+    } catch (error) {
+      // fork 没成（id 已存在、append 失败等）：别把复用映射留在进程里——同一个 childId 之后的落写会按它
+      // 去复用父会话的事件行，而那条会话可能完全无关。
+      internals.dropReuseEventIds(childId);
+      throw error;
     }
     // 子会话继承了前缀事件：活动计数按子会话重算（派生表，best-effort）。
     await this.persistence.rebuildEventCounts(childId);

package/src/drizzle/postgres-v3.ts

@@ -13,3 +13,4 @@ export const tWorkspaces = tables["t_workspaces"]!;
 export const tWorkspaceSessions = tables["t_workspace_sessions"]!;
 export const tWorkspaceState = tables["t_workspace_state"]!;
 export const tSessionProjcacheRows = tables["t_session_projcache_row"]!;
+export const tEventUsage = tables["t_event_usage"]!;

package/src/drizzle/sqlite-v3.ts

@@ -13,3 +13,4 @@ export const tWorkspaces = tables["t_workspaces"]!;
 export const tWorkspaceSessions = tables["t_workspace_sessions"]!;
 export const tWorkspaceState = tables["t_workspace_state"]!;
 export const tSessionProjcacheRows = tables["t_session_projcache_row"]!;
+export const tEventUsage = tables["t_event_usage"]!;

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

@@ -16,11 +16,11 @@ export const eventUsage: TableDef = {
     f_created_at: { type: "bigint", 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 },
+    f_input_tokens: { type: "integer", notNull: true, default: 0 },
+    f_output_tokens: { type: "integer", notNull: true, default: 0 },
+    f_cache_read_tokens: { type: "integer", notNull: true, default: 0 },
+    f_reasoning_tokens: { type: "integer", notNull: true, default: 0 },
+    f_total_tokens: { type: "integer", notNull: true, default: 0 },
   },
   indexes: { idx_event_usage_created_at: { columns: ["f_created_at"] } },
 };

package/src/entities/v3/sessions.ts

@@ -14,11 +14,16 @@ export const sessions: TableDef = {
     f_seed_length: { type: "integer" },
     f_origin: { type: "text" },
     f_delegation_depth: { type: "integer" },
+    f_agent_preset: { type: "text" },
     f_incarnation: { type: "text", notNull: true },
     f_revision: { type: "integer", notNull: true },
 
     f_archived_at: { type: "bigint" },
 
+    f_pinned_seq: { type: "integer" },
+
+    f_last_event_at: { type: "bigint" },
+
     f_title: { type: "text" },
 
     f_title_seq: { type: "integer" },

package/src/import.ts

@@ -3,11 +3,11 @@ import type { Context } from "@deepseek-ai/cordis";
 import { SESSION_FORMAT_VERSION, SessionLogOffset } from "@deepseek-ai/dsh-session";
 import type { Session, SessionEvent, SessionId, SessionHeader } from "@deepseek-ai/dsh-session";
 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 { balanceRewindPrefix } from "@morlay/session-branch";
 import { unzip } from "fflate";
 import { replaceLiveSessionLog } from "./branch.ts";
+import { restoreCatalog } from "./legacy.ts";
 import type { SessionPersistenceRdb } from "./index.ts";
 
 export const SESSION_LOG_ARTIFACT_FILENAME = "session.jsonl";
@@ -30,9 +30,9 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
     throw new Error("imported session log has an unparsable header line");
   }
 
-  let restore: ReturnType<typeof sessionFormatCatalog.createRestore>;
+  let restore: ReturnType<typeof restoreCatalog.createRestore>;
   try {
-    restore = sessionFormatCatalog.createRestore(header, {
+    restore = restoreCatalog.createRestore(header, {
       recovery: "strict",
       validation: "transformed",
     });

package/src/index.ts

@@ -1,6 +1,5 @@
 import { Context } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import type { SettingsProvider } from "@deepseek-ai/dsh-settings";
 import { randomUUID } from "node:crypto";
 import { Pool } from "pg";
 import { drizzle as drizzlePg } from "drizzle-orm/node-postgres";
@@ -61,16 +60,31 @@ import { registerSessionImport } from "./import.ts";
 import { registerSessionDeletion } from "./deletion.ts";
 import { registerSessionExport } from "./export.ts";
 import { registerSessionGc } from "./gc.ts";
+import { registerSessionRows } from "./rows.ts";
 import { COUNTED_EVENT_TYPES, localDayKey, registerSessionUsage } from "./usage.ts";
 import type { UsageAggregate } from "./usage.ts";
 import { SessionQueryRdb } from "./session-query.ts";
 import { adoptLegacyRows, convertLegacyRows, isLegacyVersion } from "./legacy.ts";
+import { hasLegacyShape } from "./log.ts";
 import { installStorageTakeover } from "./storage-takeover/index.ts";
 
+/** 一批事件里的最大时间：写路径据此推进会话行的「最后活动时间」。 */
+function maxEventTime(events: readonly { readonly time?: number }[]): number | undefined {
+  let max: number | undefined;
+  for (const event of events) {
+    const time = event.time;
+    if (typeof time !== "number") continue;
+    if (max === undefined || time > max) max = time;
+  }
+  return max;
+}
+
 const DEFAULT_PROJECTION_WRITE_EVERY_EVENTS = 200;
 const DEFAULT_PROJECTION_WRITE_INTERVAL_MS = 5000;
 
 export { SCHEMA_VERSION } from "./schema.ts";
+export { SESSION_ROWS_PATH } from "./rows.ts";
+export type { SessionRowsItem, SessionRowsValue } from "./rows.ts";
 export { SessionBranchRdb, SessionBranchRdbProvider, locateTurnEnd } from "./branch.ts";
 
 export interface SessionPersistenceRdbInternals {
@@ -95,6 +109,8 @@ export interface SessionPersistenceRdbInternals {
   ): Promise<import("@deepseek-ai/dsh-session-persistence").SessionPersistenceRevision | undefined>;
 
   registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
+  /** fork 失败时丢弃还没被消费的映射。 */
+  dropReuseEventIds(childId: SessionId): void;
 }
 
 export interface ProjectionCacheOptions {
@@ -469,7 +485,7 @@ class RdbSessionHandle implements SessionHandle {
 }
 
 export class SessionPersistenceRdb extends SessionPersistence {
-  static inject = ["sessions", "settings"];
+  static inject = ["sessions"];
 
   static Config: z<Config> = z.union([
     z.object({
@@ -503,8 +519,6 @@ export class SessionPersistenceRdb extends SessionPersistence {
     }),
   ]);
 
-  static readonly settingsNs = "session-rdb";
-
   override readonly name = "session-rdb";
 
   readonly tracker = new RdbBackendTracker(this.name);
@@ -526,23 +540,11 @@ export class SessionPersistenceRdb extends SessionPersistence {
 
     injectedBackend?: Backend,
   ) {
-    let resolved: Config = config;
-    const settings = ctx.reflect.get("settings") as unknown as SettingsProvider | undefined;
-    if (settings !== undefined) {
-      const scope = settings.register(
-        SessionPersistenceRdb.settingsNs,
-        SessionPersistenceRdb.Config,
-        { base: config },
-      );
-      resolved = scope.get();
-      scope.watch(() => {
-        ctx.logger.warn("session-rdb: settings changed; restart to apply the new configuration");
-      });
-    }
     super(ctx);
 
-    this.config = resolved;
-    this.backend = injectedBackend ?? createBackend(resolved);
+    // 配置就是这一行的 config（cordis.patch.yml / profile patch，或设置页改它）；上游 0.1.7 的 settings
+    // 不再提供 namespace section 覆盖，旧 `settings.yaml` 的 `session-rdb` 段由上游一次性导进同 id 的行。
+    this.backend = injectedBackend ?? createBackend(config);
     this.ready = this.init();
     this.installLiveRouting(ctx);
 
@@ -560,6 +562,8 @@ export class SessionPersistenceRdb extends SessionPersistence {
 
     registerSessionUsage(this.ctx, this);
 
+    registerSessionRows(this.ctx, this.backend);
+
     installStorageTakeover(this.ctx, {
       repository: this.backend.storage,
       ready: this.ready,
@@ -853,7 +857,6 @@ export class SessionPersistenceRdb extends SessionPersistence {
     validateStoredEvents(meta, [...events]);
 
     const reuse = this.reuseEventIds.get(meta.id);
-    if (reuse !== undefined) this.reuseEventIds.delete(meta.id);
     let confirmedHead = -1;
     await this.backend.transaction(async (tx) => {
       if (tornTruncateTo !== undefined) {
@@ -877,9 +880,12 @@ export class SessionPersistenceRdb extends SessionPersistence {
         reuse,
       );
       await tx.updateHead(meta.id, headEventId, headSequence);
-      await tx.bumpRevision(meta.id);
+      await tx.bumpRevision(meta.id, maxEventTime(events));
       confirmedHead = headSequence;
     });
+    // 事务**成功之后**才丢掉复用映射：失败（并发写者校验、唯一键冲突等）时这份映射还没被消费，
+    // 重试同一个 append 还要靠它复用父会话的事件行——提前删掉会让前缀事件行被重新插入一遍。
+    if (reuse !== undefined) this.reuseEventIds.delete(meta.id);
 
     this.writeGuard.confirmHead(meta.id, confirmedHead);
     this.tracker.materialized(meta.id);
@@ -951,6 +957,21 @@ export class SessionPersistenceRdb extends SessionPersistence {
       }
     }
     const { preserved, tornFrom } = scanRows(eventRows, options.fromSeq ?? 0);
+    // 版本号不完全可信：写路径曾把回退视图的结果以当前版本号落库，于是库里存在「v4 标记 + 旧代形状」
+    // 的行——在扫干净的边界之内再按内容判一次（撕裂尾部与坏行已经被 `scanRows` 丢掉了）。
+    if (hasLegacyShape(preserved)) {
+      const adopted = adoptLegacyRows(row, eventRows);
+      return {
+        meta: adopted.meta,
+        inheritedEventCount: adopted.inheritedEventCount,
+        events: adopted.events,
+        incarnation: row.fIncarnation,
+        revision: row.fRevision,
+        storedCount: eventRows.length,
+        migrated: false,
+        ...(adopted.tornFrom !== undefined ? { tornFrom: adopted.tornFrom } : {}),
+      };
+    }
     return {
       meta,
       inheritedEventCount: row.fSeedLength ?? 0,
@@ -1006,6 +1027,13 @@ export class SessionPersistenceRdb extends SessionPersistence {
     log: { meta: SessionHeader; inheritedEventCount: number; events: SessionEvent[] },
   ): Promise<void> {
     await this.backend.transaction(async (tx) => {
+      // 这段重写会删光该会话的桥接行、再按迁移视图重建——与 `appendBatch` 同一个理由，先做并发写者校验：
+      // 否则另一实例在 open 之前 / 期间提交的事件会被这段重写静默丢掉。调用方刚读过这份日志（重写只发生在
+      // write open 的读路径之后），所以 guard 里没有该会话时就把当前磁盘 head 记成本实例已确认的值；
+      // 有记录时严格比较——那能抓住"读完之后另一个实例又写了"。
+      const head = await tx.getHead(id);
+      if (!this.writeGuard.has(id)) this.writeGuard.confirmHead(id, head.fHeadSequence);
+      this.writeGuard.assertNoConcurrentWriter(id, head.fHeadSequence);
       await tx.deleteBridgeTail(id, 0);
       await tx.upsertSession(
         { meta: log.meta, inheritedEventCount: SessionLogOffset(log.inheritedEventCount) },
@@ -1016,7 +1044,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
         nextSeq: 0,
       });
       await tx.updateHead(id, headEventId, headSequence);
-      await tx.bumpRevision(id);
+      await tx.bumpRevision(id, maxEventTime(log.events));
     });
   }
 
@@ -1146,6 +1174,11 @@ export class SessionPersistenceRdb extends SessionPersistence {
     this.reuseEventIds.set(childId, new Map(map));
   }
 
+  /** 丢弃一个还没被消费的复用映射（fork 失败时）：留着会让同一个 childId 之后的落写复用父会话的事件行。 */
+  dropReuseEventIds(childId: SessionId): void {
+    this.reuseEventIds.delete(childId);
+  }
+
   internals(): SessionPersistenceRdbInternals {
     return {
       backend: this.backend,
@@ -1164,6 +1197,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
       listSnapshots: (signal) => this.listSnapshots(signal),
       readStoredRevision: (id, signal) => this.readStoredRevision(id, signal),
       registerReuseEventIds: (childId, map) => this.registerReuseEventIds(childId, map),
+      dropReuseEventIds: (childId) => this.dropReuseEventIds(childId),
     };
   }
 

package/src/legacy.ts

@@ -4,9 +4,9 @@ import {
   type SessionHeader,
   type SessionId,
 } from "@deepseek-ai/dsh-session";
-import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
+import { createSessionFormatCatalogWithChildren } from "@deepseek-ai/dsh-session-format-catalog";
 import type { EventRow, SessionRow } from "./backend.ts";
-import { repairRequestHeaders, rowToMeta, scanRows } from "./log.ts";
+import { normalizeToCurrentShape, repairRequestHeaders, rowToMeta, scanRows } from "./log.ts";
 
 function physicalHeader(row: SessionRow): Record<string, unknown> {
   const common = {
@@ -18,6 +18,7 @@ function physicalHeader(row: SessionRow): Record<string, unknown> {
     ...(row.fParentSession !== null ? { parentSession: row.fParentSession } : {}),
     ...(row.fOrigin !== null ? { origin: row.fOrigin } : {}),
     delegationDepth: row.fDelegationDepth ?? 0,
+    ...(row.fAgentPreset !== null ? { agentPreset: row.fAgentPreset } : {}),
   };
 
   return row.fVersion < 2
@@ -43,11 +44,18 @@ function physicalEvent(row: EventRow): Record<string, unknown> {
   };
 }
 
+/**
+ * 读旧格式用的 catalog：v3→v4 这条边要求显式子会话证据（上游 0.1.7 起），本仓库声明
+ * **无子会话证据**——v3 的目录事实由父会话自己在成功路径上写成 `subagent/catalog` 事件，
+ * 迁移的 child evidence 只是补偿入口；我们没有更权威的子集合来源可给（见 ADR-跟随上游session-format-v4）。
+ */
+export const restoreCatalog = createSessionFormatCatalogWithChildren([]);
+
 export function convertLegacyRows(
   row: SessionRow,
   eventRows: readonly EventRow[],
 ): { meta: SessionHeader; inheritedEventCount: number; events: SessionEvent[] } {
-  const restore = sessionFormatCatalog.createRestore(physicalHeader(row), {
+  const restore = restoreCatalog.createRestore(physicalHeader(row), {
     recovery: "strict",
     validation: "transformed",
   });
@@ -77,7 +85,10 @@ export function adoptLegacyRows(
 } {
   const { preserved, tornFrom } = scanRows(eventRows, 0);
 
+  // 回退视图要独立扛住 v4 的校验：迁移链（严格）拒绝的那些旧形状在这里按字段归一
+  // （system 消息的 source、tool/result 的消息形状、自造事件类型的 ignorable 信封）。
   repairRequestHeaders(preserved);
+  normalizeToCurrentShape(preserved);
   return {
     meta: { ...rowToMeta(row), version: SESSION_FORMAT_VERSION },