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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/session-rdb",
-  "version": "0.0.16-alpha.4",
+  "version": "0.0.17",
   "description": "RDB durable session backend for DeepSeek Harness: implements both session-persistence and session-branch (rewind / retry / fork) providers.",
   "keywords": [
     "branch",
@@ -35,32 +35,33 @@
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
   "dependencies": {
-    "@morlay/session-branch": "^0.0.4-alpha.4",
+    "@morlay/session-branch": "^0.0.5",
     "drizzle-orm": "^1.0.0-rc.5-ab785fc",
     "fflate": "^0.8.2",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@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",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-turn-outline": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-token-meter": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-workspace": "^0.1.5-rc.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.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/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-format": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-format-catalog": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "dsh": {
@@ -79,7 +80,8 @@
     "chai": "6.2.2",
     "magic-string": "0.30.21",
     "tinyrainbow": "3.1.1",
-    "vitest": "4.1.11"
+    "vitest": "4.1.11",
+    "zod": "4.6.1"
   },
   "scripts": {
     "build": "pnpm exec tsdown",

package/src/backend.ts

@@ -1,5 +1,6 @@
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
+import type { StorageRepository } from "./storage-takeover/types.ts";
 
 export interface SessionRow {
   fSessionId: string;
@@ -63,6 +64,9 @@ export interface BackendTx {
 
   updateSeedLength(id: SessionId, seedLength: number): Promise<void>;
 
+  /** 从事件表重算会话标题（最后一条 `session/title`）并写回会话行。 */
+  refreshTitle(id: SessionId): Promise<void>;
+
   insertEvents(events: EventInsert[]): Promise<void>;
 
   insertBridges(
@@ -91,6 +95,9 @@ export interface Backend {
 
   readonly storeIdentity: string;
 
+  /** storages 接管表（workspace 域与投影 checkpoint）的访问层：与事件日志同介质。 */
+  readonly storage: StorageRepository;
+
   open(): Promise<void>;
 
   getSession(id: SessionId): Promise<SessionRow | undefined>;

package/src/branch.ts

@@ -340,6 +340,8 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
         await tx.updateSeedLength(id, denseBoundary + 1);
         shrunk = denseBoundary + 1;
       }
+      // 截断可能删掉最新的 session/title：标题随保留前缀重算。
+      await tx.refreshTitle(id);
       await tx.bumpRevision(id);
       return shrunk;
     });

package/src/drizzle/postgres-v3.ts

@@ -9,3 +9,8 @@ export const tSchemaMeta = tables["t_schema_meta"]!;
 export const tSessions = tables["t_sessions"]!;
 export const tEvents = tables["t_events"]!;
 export const tSessionEvents = tables["t_session_events"]!;
+export const tStorageUnits = tables["t_storage_units"]!;
+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"]!;

package/src/drizzle/sqlite-v3.ts

@@ -9,3 +9,8 @@ export const tSchemaMeta = tables["t_schema_meta"]!;
 export const tSessions = tables["t_sessions"]!;
 export const tEvents = tables["t_events"]!;
 export const tSessionEvents = tables["t_session_events"]!;
+export const tStorageUnits = tables["t_storage_units"]!;
+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"]!;

package/src/entities/v3/index.ts

@@ -3,12 +3,22 @@ import { schemaMeta } from "./schema-meta.ts";
 import { sessions } from "./sessions.ts";
 import { events } from "./events.ts";
 import { sessionEvents } from "./session-events.ts";
+import { storageUnits } from "./storage-units.ts";
+import { workspaces } from "./workspaces.ts";
+import { workspaceSessions } from "./workspace-sessions.ts";
+import { workspaceState } from "./workspace-state.ts";
+import { sessionProjcacheRows } from "./session-projcache-rows.ts";
 
 export { persistenceState };
 export { schemaMeta };
 export { sessions };
 export { events };
 export { sessionEvents };
+export { storageUnits };
+export { workspaces };
+export { workspaceSessions };
+export { workspaceState };
+export { sessionProjcacheRows };
 
 export const sqliteTableDefs = [
   persistenceState,
@@ -16,6 +26,11 @@ export const sqliteTableDefs = [
   sessions,
   events,
   sessionEvents,
+  storageUnits,
+  workspaces,
+  workspaceSessions,
+  workspaceState,
+  sessionProjcacheRows,
 ] as const;
 
 export const postgresTableDefs = [
@@ -24,4 +39,9 @@ export const postgresTableDefs = [
   sessions,
   events,
   sessionEvents,
+  storageUnits,
+  workspaces,
+  workspaceSessions,
+  workspaceState,
+  sessionProjcacheRows,
 ] as const;

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

@@ -0,0 +1,27 @@
+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: {
+    f_id: { type: "serial", primaryKey: true },
+    f_session_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_sessions", column: "f_session_id", onDelete: "cascade" },
+    },
+    f_key: { type: "text", notNull: true },
+    f_ver: { type: "integer", notNull: true },
+    f_seq: { type: "integer", notNull: true },
+    f_val: { type: "text", notNull: true },
+  },
+  uniques: { uq_session_projcache_row_session_key: { columns: ["f_session_id", "f_key"] } },
+  indexes: { idx_session_projcache_row_key: { columns: ["f_key"] } },
+};

package/src/entities/v3/sessions.ts

@@ -16,5 +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

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

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

@@ -0,0 +1,24 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+/**
+ * workspace 的会话归属（上游 `workspaceRecord.sessionIds` 的数组顺序）：
+ * 一个会话一行，`f_position` 是归属显示顺序。会话 id 有独立索引，可按
+ * session 反查归属 workspace。
+ */
+export const workspaceSessions: TableDef = {
+  name: "t_workspace_sessions",
+  columns: {
+    f_id: { type: "serial", primaryKey: true },
+    f_workspace_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_workspaces", column: "f_workspace_id", onDelete: "cascade" },
+    },
+    f_session_id: { type: "text", notNull: true },
+    f_position: { type: "integer", notNull: true },
+  },
+  uniques: {
+    uq_workspace_sessions_workspace_session: { columns: ["f_workspace_id", "f_session_id"] },
+  },
+  indexes: { idx_workspace_sessions_session_id: { columns: ["f_session_id"] } },
+};

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

@@ -0,0 +1,18 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+/**
+ * workspace 域 global 单例（上游 `workspaceDomainState`）：`initialized` 是
+ * 引导标记，`pendingMutation` 拆成操作与目标两列（create / delete 的可恢复
+ * 两写标记）。显示顺序（`workspaceIds`）在 `t_workspaces.f_position`，
+ * 归档集在 `t_session_archives`。
+ */
+export const workspaceState: TableDef = {
+  name: "t_workspace_state",
+  columns: {
+    f_singleton: { type: "integer", primaryKey: true },
+    f_initialized: { type: "integer", notNull: true },
+    f_pending_operation: { type: "text" },
+    f_pending_workspace_id: { type: "text" },
+  },
+  checks: { ck_workspace_state_singleton: { expression: "f_singleton = 1" } },
+};

package/src/entities/v3/workspaces.ts

@@ -0,0 +1,19 @@
+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: {
+    f_id: { type: "serial", primaryKey: true },
+    f_workspace_id: { type: "text", notNull: true, unique: true },
+    f_path: { type: "text", notNull: true },
+    f_title: { type: "text", notNull: true },
+    f_created_at: { type: "text", notNull: true },
+    f_updated_at: { type: "text", notNull: true },
+    f_position: { type: "integer", notNull: true, default: -1 },
+  },
+};

package/src/import-storages.ts

@@ -0,0 +1,173 @@
+/**
+ * 一次性导入：把旧 `$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 {
+  ProjectionCheckpoint,
+  StorageRepository,
+  WorkspaceDomainState,
+  WorkspaceRecord,
+} 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";
+const WORKSPACE_UNIT_VERSIONS = new Set([2]);
+const PROJCACHE_UNIT = "session_projcache";
+const PROJCACHE_UNIT_VERSIONS = 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,
+): Promise<StoragesImportResult> {
+  const storagesRoot = join(options.dshHome, "storages");
+  const result: StoragesImportResult = { workspaces: 0, workspaceState: false, projcache: 0 };
+
+  const workspaceDocument = await readJson(join(storagesRoot, `${WORKSPACE_UNIT}.json`));
+  if (workspaceDocument !== undefined) {
+    const tables = unitTables(workspaceDocument, WORKSPACE_UNIT, WORKSPACE_UNIT_VERSIONS);
+    await repository.insertUnitVersion(WORKSPACE_UNIT, WORKSPACE_UNIT_VERSIONS.values().next().value as number);
+    for (const [id, record] of Object.entries(tables["workspaces"] ?? {})) {
+      await repository.putWorkspace(id, record as WorkspaceRecord);
+      result.workspaces += 1;
+    }
+    if (workspaceDocument.global !== undefined && workspaceDocument.global !== null) {
+      await repository.writeWorkspaceState(workspaceDocument.global as WorkspaceDomainState);
+      result.workspaceState = true;
+    }
+  }
+
+  const projcacheEntries = await readProjcacheEntries(storagesRoot);
+  if (projcacheEntries.length > 0) {
+    await repository.insertUnitVersion(
+      PROJCACHE_UNIT,
+      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;
+    }
+  }
+
+  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 {
+    text = await readFile(path, "utf8");
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  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,
+  versions: ReadonlySet<number>,
+): Record<string, Record<string, unknown>> {
+  const unit = document["unit"] as { name?: unknown; version?: unknown } | undefined;
+  if (unit?.name !== name) {
+    throw new Error(`storages document is not the '${name}' unit`);
+  }
+  if (typeof unit.version !== "number" || !versions.has(unit.version)) {
+    throw new Error(
+      `storages document '${name}' is stamped version ${String(unit.version)}, not in the accepted set`,
+    );
+  }
+  const tables = document["tables"];
+  if (typeof tables !== "object" || tables === null) {
+    throw new Error(`storages document '${name}' has no tables object`);
+  }
+  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");
+  let files: string[];
+  try {
+    files = (await readdir(sessionsDir)).filter((name) => name.endsWith(".json")).sort();
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return readLegacyProjcache(join(storagesRoot, `${PROJCACHE_UNIT}.json`));
+  }
+  for (const file of files) {
+    const document = (await readJson(join(sessionsDir, file))) as
+      | { version?: unknown; record?: unknown }
+      | 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;
+    if (record === undefined || typeof record !== "object") continue;
+    entries.push({
+      sessionId: SessionId(file.slice(0, -".json".length)),
+      rows: (record.rows ?? {}) as ProjectionCheckpoint,
+    });
+  }
+  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 [];
+  const tables = unitTables(document, PROJCACHE_UNIT, PROJCACHE_UNIT_VERSIONS);
+  return Object.entries(tables["sessions"] ?? {}).map(([sessionId, record]) => {
+    const value = record as { rows?: unknown };
+    return {
+      sessionId: SessionId(sessionId),
+      rows: (value.rows ?? {}) as ProjectionCheckpoint,
+    };
+  });
+}

package/src/index.ts

@@ -51,6 +51,11 @@ import { PostgresBackend } from "./postgres.ts";
 import { SessionBranchRdb } from "./branch.ts";
 import { registerSessionImport } from "./import.ts";
 import { adoptLegacyRows, convertLegacyRows, isLegacyVersion } from "./legacy.ts";
+import { installStorageTakeover } from "./storage-takeover/index.ts";
+
+/** 投影缓存默认写节流（与上游 base 装配的部署值一致）。 */
+const DEFAULT_PROJECTION_WRITE_EVERY_EVENTS = 200;
+const DEFAULT_PROJECTION_WRITE_INTERVAL_MS = 5000;
 
 export { SCHEMA_VERSION } from "./schema.ts";
 export { SessionBranchRdb, SessionBranchRdbProvider, locateTurnEnd } from "./branch.ts";
@@ -79,6 +84,14 @@ export interface SessionPersistenceRdbInternals {
   registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
 }
 
+/** 投影 checkpoint 写节流（替换上游 `session-projection-cache` 的 Config）。 */
+export interface ProjectionCacheOptions {
+  /** 两次强制点之间累积多少已提交事件强制落盘（默认 200）。 */
+  writeEveryEvents?: number;
+  /** 脏 checkpoint 在强制点之间允许滞留的最长毫秒数（默认 5000）。 */
+  writeIntervalMs?: number;
+}
+
 export type Config =
   | {
       type: "sqlite";
@@ -88,6 +101,8 @@ export type Config =
       journalMode?: JournalMode;
 
       busyTimeout?: number;
+
+      projectionCache?: ProjectionCacheOptions;
     }
   | {
       type: "postgres";
@@ -95,6 +110,8 @@ export type Config =
       connectionString: string;
 
       schema?: string;
+
+      projectionCache?: ProjectionCacheOptions;
     };
 
 /** 一个已创建但未 materialize 的会话（本进程可见，其他进程不可见）。 */
@@ -441,11 +458,29 @@ export class SessionPersistenceRdb extends SessionPersistence {
       path: z.string().required(),
       journalMode: z.union(["wal", "delete", "truncate", "persist"] as const).default("wal"),
       busyTimeout: z.number().step(1).min(0).default(DEFAULT_BUSY_TIMEOUT_MS),
+      projectionCache: z
+        .object({
+          writeEveryEvents: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_EVERY_EVENTS),
+          writeIntervalMs: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_INTERVAL_MS),
+        })
+        .default({
+          writeEveryEvents: DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
+          writeIntervalMs: DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
+        }),
     }),
     z.object({
       type: z.const("postgres"),
       connectionString: z.string().required(),
       schema: z.string().default("public"),
+      projectionCache: z
+        .object({
+          writeEveryEvents: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_EVERY_EVENTS),
+          writeIntervalMs: z.natural().min(1).default(DEFAULT_PROJECTION_WRITE_INTERVAL_MS),
+        })
+        .default({
+          writeEveryEvents: DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
+          writeIntervalMs: DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
+        }),
     }),
   ]);
 
@@ -499,6 +534,18 @@ export class SessionPersistenceRdb extends SessionPersistence {
     new SessionBranchRdb(this.ctx);
     // 导入端点：webServer + connection 就绪后注册 `/api/session.import`。
     registerSessionImport(this.ctx, this);
+    // storages 接管：storage hub 的 `rdb` 后端（workspace 域）与
+    // `ctx.sessionProjectionCache` 服务（替换上游插件）。
+    installStorageTakeover(this.ctx, {
+      repository: this.backend.storage,
+      ready: this.ready,
+      projectionCache: {
+        writeEveryEvents:
+          this.config.projectionCache?.writeEveryEvents ?? DEFAULT_PROJECTION_WRITE_EVERY_EVENTS,
+        writeIntervalMs:
+          this.config.projectionCache?.writeIntervalMs ?? DEFAULT_PROJECTION_WRITE_INTERVAL_MS,
+      },
+    });
   }
 
   private async init(): Promise<void> {
@@ -1249,6 +1296,12 @@ async function appendEventTail(
   }
   if (eventRows.length > 0) await tx.insertEvents(eventRows);
   await tx.insertBridges(bridgeRows);
+  // 标题是会话数据的一部分：批内出现 session/title 时同步刷新会话行，
+  // 列表消费直接取列（sessions.title 直取）。
+  // 插件合并类型不在 core 的判别联合内，按字符串比较（同 eventDimensions）。
+  if (events.some((event) => (event.type as string) === "session/title")) {
+    await tx.refreshTitle(meta.id);
+  }
   return { headEventId: parentId, headSequence: nextSeq - 1 };
 }
 

package/src/log.ts

@@ -695,3 +695,22 @@ export function toJsonlArtifact(
   }
   return lines.join("\n");
 }
+
+/**
+ * 事件行 JSON → `session/title` 的标题文本。存储层写路径保证 `f_data` 是完整
+ * 事件 JSON；形状不符（或损坏）按「无标题」处理——标题是派生显示数据。
+ * @param data - `t_events.f_data` 原文。
+ * @returns 标题文本，或 `undefined`。
+ */
+export function titleOfEventData(data: string): string | undefined {
+  try {
+    // 当前世代：`{...envelope, data:{title}}`；旧世代（v0-v2）的 f_data 直接
+    // 平铺事件 data，title 在顶层。两者都读，避免 legacy 会话的标题被清空。
+    const value = JSON.parse(data) as { data?: { title?: unknown }; title?: unknown };
+    const title = value.data?.title ?? value.title;
+    return typeof title === "string" ? title : undefined;
+  } catch {
+    // 写路径已保证 JSON；此处只可能是损坏数据，读作无标题。
+    return undefined;
+  }
+}