@morlay/session-rdb 0.1.10-alpha.0 → 0.1.10-alpha.2

package/src/legacy.ts

@@ -6,7 +6,9 @@ import {
 } from "@deepseek-ai/dsh-session";
 import { createSessionFormatCatalogWithChildren } from "@deepseek-ai/dsh-session-format-catalog";
 import type { EventRow, SessionRow } from "./backend.ts";
-import { normalizeToCurrentShape, repairRequestHeaders, rowToMeta, scanRows } from "./log.ts";
+import { normalizeToCurrentShape, repairRequestHeaders } from "./log/repair.ts";
+import { rowToMeta } from "./log/rows.ts";
+import { scanRows } from "./log/export.ts";
 
 function physicalHeader(row: SessionRow): Record<string, unknown> {
   const common = {

package/src/live-routing.ts

@@ -0,0 +1,205 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { assertVersion } from "@deepseek-ai/dsh-session-persistence";
+import type { Session, SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
+import type { SessionHandle } from "@deepseek-ai/dsh-session-persistence";
+import type { SessionPersistenceRdb } from "./session-store.ts";
+import { liveEventsOf } from "./branch/index.ts";
+import { repairReadView } from "./log/repair.ts";
+
+/**
+ * live 会话的写路由：把 `session/created|event|flush|disposed` 四个订阅与四张内存表收在一处。
+ *
+ * 会话级的「缓冲—句柄—失败终态」都收在这里；装配点是 `session-store.ts` 的构造函数（`new LiveRouting(ctx, this)`），
+ * `forget(id)` 在删除会话 / 回收孤儿会话时调用。句柄自己的批量窗口在 `handles.ts`。
+ */
+/** live 会话的写句柄：`SessionHandle` 加上批量窗口的入口。 */
+interface LiveHandle extends SessionHandle {
+  enqueueLive(event: SessionEvent, reportBackgroundFailure: (error: unknown) => void): void;
+}
+
+export class LiveRouting {
+  private readonly buffers = new Map<SessionId, SessionEvent[]>();
+  private readonly ready = new Map<SessionId, Promise<void>>();
+  // 持久化初始化失败是**终态**（cwd / 继承前缀冲突、id 碰撞、后端打不开都不自愈）：记账一条 error、
+  // 丢掉已缓冲的事件，之后该会话的事件不再进内存缓冲（否则表现为「聊了一整轮、重启后全丢，
+  // 内存里还留一份无界副本」），flush 把失败抛回上游。
+  private readonly failures = new Map<SessionId, Error>();
+  private readonly dropWarned = new Set<SessionId>();
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly persistence: SessionPersistenceRdb,
+  ) {}
+
+  /** 丢掉一个会话的所有 live 记账（删除会话、孤儿会话回收时）。 */
+  forget(id: SessionId): void {
+    this.buffers.delete(id);
+    this.ready.delete(id);
+    this.failures.delete(id);
+    this.dropWarned.delete(id);
+  }
+
+  install(): void {
+    const ctx = this.ctx;
+    ctx.on("session/created", (session: Session) => {
+      this.buffers.set(session.id, []);
+      const ready = this.ensureHandle(session);
+      this.ready.set(session.id, ready);
+      this.watchReady(session, ready);
+    });
+
+    for (const session of ctx.sessions.list()) {
+      this.buffers.set(session.id, []);
+      const ready = this.ensureHandle(session);
+      this.ready.set(session.id, ready);
+      this.watchReady(session, ready);
+    }
+
+    ctx.on("session/event", (session: Session, event: SessionEvent) => {
+      const handle = this.persistence.tracker.writerOf(session.id);
+      if (handle !== undefined) {
+        handle.enqueueLive(event, (error) => {
+          ctx.logger.warn(
+            `session-rdb: background write for session "${session.id}" failed (buffered events retained): ${String(error)}`,
+          );
+        });
+        return;
+      }
+      if (this.failures.has(session.id)) {
+        if (!this.dropWarned.has(session.id)) {
+          this.dropWarned.add(session.id);
+          ctx.logger.warn(
+            `session-rdb: dropping events for live session "${session.id}" because persistence failed earlier`,
+          );
+        }
+        return;
+      }
+      this.buffers.get(session.id)?.push(structuredClone(event));
+    });
+
+    ctx.on("session/flush", (session: Session) => {
+      const failure = this.failures.get(session.id);
+      if (failure !== undefined) return Promise.reject(failure);
+      const handle = this.persistence.tracker.writerOf(session.id);
+      if (handle === undefined) {
+        const ready = this.ready.get(session.id);
+        if (ready === undefined) return undefined;
+        return ready.then(() => {
+          const settled = this.persistence.tracker.writerOf(session.id);
+          if (settled === undefined) return undefined;
+          return settled.drainLive().then(() => settled.flush());
+        });
+      }
+      return handle.drainLive().then(() => handle.flush());
+    });
+
+    ctx.on("session/disposed", (session: Session) => {
+      const ready = this.ready.get(session.id);
+      this.forget(session.id);
+      const closeHandle = (): void => {
+        const handle = this.persistence.tracker.writerOf(session.id);
+        if (handle === undefined) return;
+        handle.close().catch((error: unknown) => {
+          ctx.logger.warn(
+            `session-rdb: final drain for session "${session.id}" failed: ${String(error)}`,
+          );
+        });
+      };
+      if (ready === undefined) {
+        closeHandle();
+        return;
+      }
+      void ready.then(closeHandle, closeHandle);
+    });
+
+    ctx.effect(
+      () => async () => {
+        await Promise.allSettled(this.ready.values());
+        this.buffers.clear();
+        this.ready.clear();
+        this.failures.clear();
+        this.dropWarned.clear();
+        await this.persistence.tracker.closeAll();
+        await this.persistence.close();
+      },
+      `${this.persistence.name} open handles`,
+    );
+  }
+
+  private watchReady(session: Session, ready: Promise<void>): void {
+    void ready.catch((error: unknown) => {
+      const failure =
+        error instanceof Error
+          ? error
+          : new Error(
+              typeof error === "string"
+                ? error
+                : `live session "${session.id}" persistence failed`,
+            );
+      this.failures.set(session.id, failure);
+      this.buffers.delete(session.id);
+      this.ctx.logger.error(
+        `session-rdb: live session "${session.id}" persistence unavailable (${failure.message}); its events will not be persisted`,
+      );
+    });
+  }
+
+  private async ensureHandle(session: Session): Promise<void> {
+    const persistence = this.persistence;
+    const id = session.header.id;
+    if (persistence.tracker.writerOf(id) !== undefined) return;
+    await persistence.ready;
+    const stored = await persistence.readLog(id, {});
+    let handle: LiveHandle;
+    if (stored === undefined) {
+      handle = (await persistence.create(session.header, {
+        inheritedEventCount: session.inheritedEventCount,
+      })) as LiveHandle;
+      const seed = liveEventsOf(session);
+      if (seed.length > 0) await handle.append(seed);
+    } else {
+      if (stored.meta.cwd !== session.header.cwd) {
+        throw new Error(
+          `session "${id}" is already persisted at a different cwd (persisted: ${String(stored.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`,
+        );
+      }
+      if (stored.inheritedEventCount !== session.inheritedEventCount) {
+        throw new Error(
+          `session "${id}" is already persisted with a different inherited event count (id collision)`,
+        );
+      }
+      assertVersion(stored.meta);
+
+      repairReadView(stored.events);
+      const seed = liveEventsOf(session);
+      if (!seedCoversPrefix(seed, stored.events)) {
+        throw new Error(
+          `session "${id}" already has a persisted log on disk that does not match this live session (id collision)`,
+        );
+      }
+      handle = (await persistence.open(id, "write")) as LiveHandle;
+
+      const suffix = seed.slice(stored.events.length);
+      if (suffix.length > 0) await handle.append(suffix);
+    }
+
+    const buffered = this.buffers.get(id);
+    if (buffered !== undefined && buffered.length > 0) {
+      this.buffers.set(id, []);
+      for (const event of buffered) handle.enqueueLive(event, () => {});
+    }
+  }
+}
+
+function seedCoversPrefix(
+  seed: readonly SessionEvent[],
+  prefix: readonly SessionEvent[],
+): boolean {
+  return (
+    prefix.length <= seed.length &&
+    prefix.every((event, index) => {
+      const seedEvent = seed[index];
+      return seedEvent !== undefined && JSON.stringify(seedEvent) === JSON.stringify(event);
+    })
+  );
+}

package/src/log/export.ts

@@ -0,0 +1,84 @@
+import type { SessionEvent, SessionHeader } from "@deepseek-ai/dsh-session";
+import type { SessionFormatEvent, SessionFormatHeader } from "@deepseek-ai/dsh-session-format";
+import { sessionFormatCatalog } from "@deepseek-ai/dsh-session-format-catalog";
+import type { EventRow } from "../backend.ts";
+import { rowToEvent } from "./rows.ts";
+
+export function scanRows(
+  rows: readonly EventRow[],
+  base = 0,
+): { preserved: SessionEvent[]; tornFrom?: number } {
+  // 已提交区（最后一个 `turn/end` 及之前）必须完整：坏行/断号只有在它之后才允许当作撕裂尾部丢掉。
+  // 倒序只为找到这个边界，先按行类型筛（绝大多数行直接跳过），再解析候选行确认它本身可读。
+  let lastTurnEnd = -1;
+  for (let i = rows.length - 1; i >= 0; i--) {
+    if (rows[i]?.fType !== "turn/end") continue;
+    try {
+      rowToEvent(rows[i] as EventRow);
+      lastTurnEnd = i;
+      break;
+    } catch {
+      /* 这个 turn/end 自身坏掉：继续往前找上一个可读的边界。 */
+    }
+  }
+
+  const preserved: SessionEvent[] = [];
+  for (let i = 0; i < rows.length; i++) {
+    let event: SessionEvent;
+    try {
+      event = rowToEvent(rows[i] as EventRow);
+    } catch {
+      if (i <= lastTurnEnd)
+        throw new Error(
+          `corrupt session log: unparsable committed event at seq ${rows[i]?.fSequence}`,
+        );
+      break;
+    }
+    if (event.seq !== base + i) {
+      if (i <= lastTurnEnd)
+        throw new Error(
+          `corrupt session log: seq gap in committed region (expected ${base + i}, got ${event.seq})`,
+        );
+      break;
+    }
+    preserved.push(event);
+  }
+
+  return preserved.length < rows.length
+    ? { preserved, tornFrom: base + preserved.length }
+    : { preserved };
+}
+
+export function toJsonlArtifact(
+  meta: SessionHeader,
+  inheritedEventCount: number,
+  events: readonly SessionEvent[],
+): string {
+  const header = sessionFormatCatalog.encodeCurrentHeader(
+    {
+      ...meta,
+      delegationDepth: meta.delegationDepth ?? 0,
+    } as unknown as SessionFormatHeader,
+    inheritedEventCount,
+  );
+  const lines = [JSON.stringify(header)];
+  for (const event of events) {
+    lines.push(
+      JSON.stringify(
+        sessionFormatCatalog.encodeCurrentEvent(event as unknown as SessionFormatEvent),
+      ),
+    );
+  }
+  return lines.join("\n");
+}
+
+export function titleOfEventData(data: string): string | undefined {
+  try {
+    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 {
+    return undefined;
+  }
+}
+

package/src/{log.ts → log/repair.ts}

@@ -1,132 +1,6 @@
 import { SessionSeq } from "@deepseek-ai/dsh-session";
-import type { SessionEvent, SessionHeader, SessionId, SurfaceOp } from "@deepseek-ai/dsh-session";
-import type { SessionFormatEvent, SessionFormatHeader } 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 type { EventRow, SessionRow } from "./backend.ts";
-import { localDayKey } from "./usage.ts";
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
 
-function normalizeSurfaceOp(value: unknown): SurfaceOp {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return value as SurfaceOp;
-  }
-  const record = value as Record<string, unknown>;
-  if (record["op"] !== "replace") return value as SurfaceOp;
-  const startSeq = record["startSeq"] ?? record["start"];
-  const endSeq = record["endSeq"] ?? record["end"];
-  if (typeof startSeq !== "number" || typeof endSeq !== "number") return value as SurfaceOp;
-  return { op: "replace", startSeq: SessionSeq(startSeq), endSeq: SessionSeq(endSeq) };
-}
-
-export function rowToMeta(row: SessionRow): SessionHeader {
-  if (!Number.isSafeInteger(row.fCreatedAt) || row.fCreatedAt < 0) {
-    throw new Error("stored session createdAt must be a non-negative safe integer");
-  }
-  return {
-    version: row.fVersion as SessionHeader["version"],
-    id: row.fSessionId as SessionId,
-    createdAt: row.fCreatedAt,
-    ...(row.fCwd !== null ? { cwd: row.fCwd } : {}),
-    ...(row.fParentSession !== null ? { parentSession: row.fParentSession as SessionId } : {}),
-    isSeeded: row.fSeedLength !== null,
-    ...(row.fOrigin !== null ? { origin: row.fOrigin as "subagent" } : {}),
-    ...(row.fDelegationDepth === null ? {} : { delegationDepth: row.fDelegationDepth }),
-    ...(row.fAgentPreset === null ? {} : { agentPreset: row.fAgentPreset }),
-  };
-}
-
-export function sessionInsertRow(
-  storage: SessionStorageMetadata,
-  incarnation: string,
-): {
-  fSessionId: string;
-  fHeadEventId: string;
-  fHeadSequence: number;
-  fVersion: number;
-  fCreatedAt: number;
-  fCwd: string | null;
-  fParentSession: string | null;
-  fSeedLength: number | null;
-  fOrigin: string | null;
-  fDelegationDepth: number | null;
-  fAgentPreset: string | null;
-  fIncarnation: string;
-  fRevision: number;
-} {
-  const meta = storage.meta;
-  return {
-    fSessionId: meta.id,
-    fHeadEventId: "",
-    fHeadSequence: -1,
-    fVersion: meta.version,
-    fCreatedAt: meta.createdAt,
-    fCwd: meta.cwd ?? null,
-    fParentSession: meta.parentSession ?? null,
-    fSeedLength: meta.isSeeded ? storage.inheritedEventCount : null,
-    fOrigin: meta.origin ?? null,
-    fDelegationDepth: meta.delegationDepth ?? null,
-    fAgentPreset: meta.agentPreset ?? null,
-    fIncarnation: incarnation,
-    fRevision: 0,
-  };
-}
-
-export function sessionConflictRow(storage: SessionStorageMetadata): {
-  fVersion: number;
-  fCreatedAt: number;
-  fCwd: string | null;
-  fParentSession: string | null;
-  fSeedLength: number | null;
-  fOrigin: string | null;
-  fDelegationDepth: number | null;
-  fAgentPreset: string | null;
-} {
-  const meta = storage.meta;
-  return {
-    fVersion: meta.version,
-    fCreatedAt: meta.createdAt,
-    fCwd: meta.cwd ?? null,
-    fParentSession: meta.parentSession ?? null,
-    fSeedLength: meta.isSeeded ? storage.inheritedEventCount : null,
-    fOrigin: meta.origin ?? null,
-    fDelegationDepth: meta.delegationDepth ?? null,
-    fAgentPreset: meta.agentPreset ?? null,
-  };
-}
-
-export function rowToEvent(row: EventRow): SessionEvent {
-  const surfaceOp =
-    row.fSurfaceOp !== null ? normalizeSurfaceOp(JSON.parse(row.fSurfaceOp) as unknown) : undefined;
-  const record = JSON.parse(row.fData) as unknown;
-
-  const full =
-    typeof record === "object" &&
-    record !== null &&
-    !Array.isArray(record) &&
-    typeof (record as Record<string, unknown>)["type"] === "string" &&
-    typeof (record as Record<string, unknown>)["seq"] === "number" &&
-    typeof (record as Record<string, unknown>)["time"] === "number" &&
-    "data" in (record as Record<string, unknown>);
-  if (full) {
-    // 直接改写出参而不是 `{...record}`：冷读一页就是几万次，spread 在这里是纯开销。
-    const event = record as SessionEvent & { seq: number; time: number; surfaceOp?: unknown };
-    event.seq = row.fSequence as SessionEvent["seq"];
-    event.time = row.fCreatedAt as SessionEvent["time"];
-    if (surfaceOp !== undefined) event.surfaceOp = surfaceOp;
-    return event as SessionEvent;
-  }
-  return {
-    type: row.fType as SessionEvent["type"],
-    seq: row.fSequence,
-    time: row.fCreatedAt,
-    data: record as SessionEvent["data"],
-    ...(surfaceOp === undefined ? {} : { surfaceOp }),
-  } as SessionEvent;
-}
-
-// 与上游 `SURFACE_EVENT_TYPES`（`…/core/session/src/surface.ts`）同一集合：`developer/message` 承载
-// 工具清单的增删通知，同样是模型可见的 surface 事件，漏掉它会把它的 `surfaceOp` 当「非 surface 事件带的
-// 标记」清掉，随后的持久化校验直接拒绝整条会话（agent-loop 在工具集变化时会写这种事件）。
 const SURFACE_EVENT_TYPES = new Set([
   "system/message",
   "developer/message",
@@ -644,144 +518,3 @@ export function repairOrphanInboxSplices(events: SessionEvent[]): void {
   }
 }
 
-export function scanRows(
-  rows: readonly EventRow[],
-  base = 0,
-): { preserved: SessionEvent[]; tornFrom?: number } {
-  // 已提交区（最后一个 `turn/end` 及之前）必须完整：坏行/断号只有在它之后才允许当作撕裂尾部丢掉。
-  // 倒序只为找到这个边界，先按行类型筛（绝大多数行直接跳过），再解析候选行确认它本身可读。
-  let lastTurnEnd = -1;
-  for (let i = rows.length - 1; i >= 0; i--) {
-    if (rows[i]?.fType !== "turn/end") continue;
-    try {
-      rowToEvent(rows[i] as EventRow);
-      lastTurnEnd = i;
-      break;
-    } catch {
-      /* 这个 turn/end 自身坏掉：继续往前找上一个可读的边界。 */
-    }
-  }
-
-  const preserved: SessionEvent[] = [];
-  for (let i = 0; i < rows.length; i++) {
-    let event: SessionEvent;
-    try {
-      event = rowToEvent(rows[i] as EventRow);
-    } catch {
-      if (i <= lastTurnEnd)
-        throw new Error(
-          `corrupt session log: unparsable committed event at seq ${rows[i]?.fSequence}`,
-        );
-      break;
-    }
-    if (event.seq !== base + i) {
-      if (i <= lastTurnEnd)
-        throw new Error(
-          `corrupt session log: seq gap in committed region (expected ${base + i}, got ${event.seq})`,
-        );
-      break;
-    }
-    preserved.push(event);
-  }
-
-  return preserved.length < rows.length
-    ? { preserved, tornFrom: base + preserved.length }
-    : { preserved };
-}
-
-export function toJsonlArtifact(
-  meta: SessionHeader,
-  inheritedEventCount: number,
-  events: readonly SessionEvent[],
-): string {
-  const header = sessionFormatCatalog.encodeCurrentHeader(
-    {
-      ...meta,
-      delegationDepth: meta.delegationDepth ?? 0,
-    } as unknown as SessionFormatHeader,
-    inheritedEventCount,
-  );
-  const lines = [JSON.stringify(header)];
-  for (const event of events) {
-    lines.push(
-      JSON.stringify(
-        sessionFormatCatalog.encodeCurrentEvent(event as unknown as SessionFormatEvent),
-      ),
-    );
-  }
-  return lines.join("\n");
-}
-
-export function titleOfEventData(data: string): string | undefined {
-  try {
-    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 {
-    return undefined;
-  }
-}
-
-// 用量行的列（`t_event_usage`）：读侧维度（本地日与两个归属标记）在写入时一起物化。
-export interface EventUsageRow {
-  fEventId: string;
-  fCreatedAt: number;
-  fDay: string;
-  fProvider: string | null;
-  fModel: string | null;
-  fReferenced: number;
-  fSubagent: number;
-  fInputTokens: number;
-  fOutputTokens: number;
-  fCacheReadTokens: number;
-  fReasoningTokens: number;
-  fTotalTokens: number;
-}
-
-function numericField(value: unknown): number {
-  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
-}
-
-function textField(value: unknown): string | null {
-  return typeof value === "string" && value !== "" ? value : null;
-}
-
-// 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有；没有用量时为 undefined）：写路径据此记录
-// `t_event_usage`，统计因此不必逐行解析 JSON，两种 `f_data` 结构（带信封 / 老格式）都认。读侧维度一起物化：
-// 本地日由事件时间算，`f_referenced` 直接 1（这一批事件行与桥接行同事务），`f_subagent` 取写入它的会话是否子代理。
-export function usageRowOf(
-  event: {
-    fEventId: string;
-    fCreatedAt: number;
-    fType: string;
-    fData: string;
-  },
-  subagent: boolean,
-): EventUsageRow | undefined {
-  if (event.fType !== "assistant/message") return undefined;
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(event.fData) as Record<string, unknown>;
-  } catch {
-    return undefined;
-  }
-  const envelope = (parsed["data"] ?? parsed) as Record<string, unknown>;
-  const usage = envelope["usage"];
-  if (typeof usage !== "object" || usage === null) return undefined;
-  const source = (envelope["message"] as { source?: Record<string, unknown> } | undefined)?.source;
-  const row: EventUsageRow = {
-    fEventId: event.fEventId,
-    fCreatedAt: event.fCreatedAt,
-    fDay: localDayKey(event.fCreatedAt),
-    fProvider: textField(source?.["provider"]),
-    fModel: textField(source?.["model"]),
-    fReferenced: 1,
-    fSubagent: subagent ? 1 : 0,
-    fInputTokens: numericField((usage as Record<string, unknown>)["inputTokens"]),
-    fOutputTokens: numericField((usage as Record<string, unknown>)["outputTokens"]),
-    fCacheReadTokens: numericField((usage as Record<string, unknown>)["cacheReadTokens"]),
-    fReasoningTokens: numericField((usage as Record<string, unknown>)["reasoningTokens"]),
-    fTotalTokens: numericField((usage as Record<string, unknown>)["totalTokens"]),
-  };
-  return row;
-}

package/src/log/rows.ts

@@ -0,0 +1,107 @@
+import { SessionSeq } from "@deepseek-ai/dsh-session";
+import type { InsertRow, RowOf } from "@morlay/rdbkit";
+import { sessions } from "../entities/index.ts";
+import type { SessionEvent, SessionHeader, SessionId, SurfaceOp } from "@deepseek-ai/dsh-session";
+import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
+import type { EventRow, SessionRow } from "../backend.ts";
+
+function normalizeSurfaceOp(value: unknown): SurfaceOp {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return value as SurfaceOp;
+  }
+  const record = value as Record<string, unknown>;
+  if (record["op"] !== "replace") return value as SurfaceOp;
+  const startSeq = record["startSeq"] ?? record["start"];
+  const endSeq = record["endSeq"] ?? record["end"];
+  if (typeof startSeq !== "number" || typeof endSeq !== "number") return value as SurfaceOp;
+  return { op: "replace", startSeq: SessionSeq(startSeq), endSeq: SessionSeq(endSeq) };
+}
+
+export function rowToMeta(row: SessionRow): SessionHeader {
+  if (!Number.isSafeInteger(row.fCreatedAt) || row.fCreatedAt < 0) {
+    throw new Error("stored session createdAt must be a non-negative safe integer");
+  }
+  return {
+    version: row.fVersion as SessionHeader["version"],
+    id: row.fSessionId as SessionId,
+    createdAt: row.fCreatedAt,
+    ...(row.fCwd !== null ? { cwd: row.fCwd } : {}),
+    ...(row.fParentSession !== null ? { parentSession: row.fParentSession as SessionId } : {}),
+    isSeeded: row.fSeedLength !== null,
+    ...(row.fOrigin !== null ? { origin: row.fOrigin as "subagent" } : {}),
+    ...(row.fDelegationDepth === null ? {} : { delegationDepth: row.fDelegationDepth }),
+    ...(row.fAgentPreset === null ? {} : { agentPreset: row.fAgentPreset }),
+  };
+}
+
+/** 新建会话行（列名即表定义里的列，值全部显式给出）。 */
+export function sessionInsertColumns(
+  storage: SessionStorageMetadata,
+  incarnation: string,
+): InsertRow<RowOf<typeof sessions>> {
+  return {
+    ...sessionHeaderColumns(storage),
+    f_session_id: storage.meta.id,
+    f_head_event_id: "",
+    f_head_sequence: -1,
+    f_incarnation: incarnation,
+    f_revision: 0,
+  };
+}
+
+/** header 的八列（`upsert` 时「变了的列才写」判据也用它）。 */
+export function sessionHeaderColumns(storage: SessionStorageMetadata): {
+  f_version: number;
+  f_created_at: number;
+  f_cwd: string | null;
+  f_parent_session: string | null;
+  f_seed_length: number | null;
+  f_origin: string | null;
+  f_delegation_depth: number | null;
+  f_agent_preset: string | null;
+} {
+  const meta = storage.meta;
+  return {
+    f_version: meta.version,
+    f_created_at: meta.createdAt,
+    f_cwd: meta.cwd ?? null,
+    f_parent_session: meta.parentSession ?? null,
+    f_seed_length: meta.isSeeded ? storage.inheritedEventCount : null,
+    f_origin: meta.origin ?? null,
+    f_delegation_depth: meta.delegationDepth ?? null,
+    f_agent_preset: meta.agentPreset ?? null,
+  };
+}
+
+export function rowToEvent(row: EventRow): SessionEvent {
+  const surfaceOp =
+    row.fSurfaceOp !== null ? normalizeSurfaceOp(JSON.parse(row.fSurfaceOp) as unknown) : undefined;
+  const record = JSON.parse(row.fData) as unknown;
+
+  const full =
+    typeof record === "object" &&
+    record !== null &&
+    !Array.isArray(record) &&
+    typeof (record as Record<string, unknown>)["type"] === "string" &&
+    typeof (record as Record<string, unknown>)["seq"] === "number" &&
+    typeof (record as Record<string, unknown>)["time"] === "number" &&
+    "data" in (record as Record<string, unknown>);
+  if (full) {
+    // 直接改写出参而不是 `{...record}`：冷读一页就是几万次，spread 在这里是纯开销。
+    const event = record as SessionEvent & { seq: number; time: number; surfaceOp?: unknown };
+    event.seq = row.fSequence as SessionEvent["seq"];
+    event.time = row.fCreatedAt as SessionEvent["time"];
+    if (surfaceOp !== undefined) event.surfaceOp = surfaceOp;
+    return event as SessionEvent;
+  }
+  return {
+    type: row.fType as SessionEvent["type"],
+    seq: row.fSequence,
+    time: row.fCreatedAt,
+    data: record as SessionEvent["data"],
+    ...(surfaceOp === undefined ? {} : { surfaceOp }),
+  } as SessionEvent;
+}
+
+// 与上游 `SURFACE_EVENT_TYPES`（`…/core/session/src/surface.ts`）同一集合：`developer/message` 承载
+// 工具清单的增删通知，同样是模型可见的 surface 事件，漏掉它会把它的 `surfaceOp` 当「非 surface 事件带的