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

package/src/stats-fold.ts

@@ -0,0 +1,44 @@
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+import type { SessionCountBucket, SessionUsageBucket } from "./backend.ts";
+import type { EventUsageRow } from "./log/usage-row.ts";
+import { COUNTED_EVENT_TYPES, addActivityCount, localDayKey } from "./usage.ts";
+
+// 一批事件折成活动计数的桶：只数四种类型，按本地日聚合成四项。
+export function sessionCountBuckets(events: readonly SessionEvent[]): SessionCountBucket[] {
+  const counted = new Map<string, SessionCountBucket>();
+  for (const event of events) {
+    if (!(COUNTED_EVENT_TYPES as readonly string[]).includes(event.type)) continue;
+    const day = localDayKey(event.time);
+    const bucket = counted.get(day) ?? { day, turns: 0, steps: 0, userInputs: 0, toolCalls: 0 };
+    addActivityCount(bucket, event.type, 1);
+    counted.set(day, bucket);
+  }
+  return [...counted.values()];
+}
+
+// 一批用量行折成 token 桶：按「本地日 × 模型」聚合（模型未知落空串，与表口径一致）。
+export function sessionUsageBuckets(usageRows: readonly EventUsageRow[]): SessionUsageBucket[] {
+  const counted = new Map<string, SessionUsageBucket>();
+  for (const row of usageRows) {
+    const provider = row.fProvider ?? "";
+    const model = row.fModel ?? "";
+    const key = `${row.fDay}#${provider}#${model}`;
+    const bucket = counted.get(key) ?? {
+      day: row.fDay,
+      provider,
+      model,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      reasoningTokens: 0,
+      totalTokens: 0,
+    };
+    bucket.inputTokens += row.fInputTokens;
+    bucket.outputTokens += row.fOutputTokens;
+    bucket.cacheReadTokens += row.fCacheReadTokens;
+    bucket.reasoningTokens += row.fReasoningTokens;
+    bucket.totalTokens += row.fTotalTokens;
+    counted.set(key, bucket);
+  }
+  return [...counted.values()];
+}

package/src/storage-takeover/index.ts

@@ -1,14 +1,12 @@
 import type { Context } from "@deepseek-ai/cordis";
 import { storageBackendServiceKey } from "@deepseek-ai/dsh-storage";
-import type { ProjectionCacheConfig } from "./projection-cache.ts";
 import { SessionProjectionCacheRdb } from "./projection-cache.ts";
 import { RDB_STORAGE_BACKEND, RdbStorageBackend } from "./storage-backend.ts";
 import type { StorageRepository } from "./types.ts";
 
 export interface StorageTakeoverOptions {
-  repository: StorageRepository;
-
-  projectionCache: ProjectionCacheConfig;
+  /** backend 打开后才有值：接管在构造期完成，真正的读写在打开后发生。 */
+  repository: () => Promise<StorageRepository>;
 
   ready: Promise<unknown>;
 }
@@ -27,7 +25,6 @@ export function installStorageTakeover(ctx: Context, options: StorageTakeoverOpt
   });
 
   ctx.plugin(SessionProjectionCacheRdb, {
-    ...options.projectionCache,
     repository: options.repository,
     ready: options.ready,
   });

package/src/storage-takeover/legacy-domain-migration.ts

@@ -0,0 +1,118 @@
+// 一次性搬运：旧版把 workspace / schedule / cua 授权域拆成各自的语义表，现在所有域只落
+// `t_storage_records`。旧表保留不删（可回退），这里把数据读成上游的文档形状写进新表。
+//
+// 幂等由调用方用 `t_schema_meta` 的标记控制：搬过一次就不再搬，否则用户清空工作区后重启会把旧数据搬回来。
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { WorkspaceId } from "@deepseek-ai/dsh-workspace";
+import type { StorageRepository } from "./types.ts";
+
+export interface LegacyWorkspaceRow {
+  id: string;
+  path: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  position: number;
+}
+
+export interface LegacyLinkRow {
+  workspaceId: string;
+  sessionId: string;
+  position: number;
+}
+
+export interface LegacyWorkspaceStateRow {
+  initialized: number | boolean;
+  pendingOperation: string | null;
+  pendingWorkspaceId: string | null;
+}
+
+export interface LegacyScheduleRow {
+  id: string;
+  sessionId: string;
+  status: string;
+  record: string;
+  lastDelivery: string | null;
+  deliveryHistory: string | null;
+}
+
+export interface LegacyGlobalRow {
+  domain: string;
+  value: unknown;
+}
+
+export interface LegacyStorageRows {
+  workspaces: LegacyWorkspaceRow[];
+  links: LegacyLinkRow[];
+  state: LegacyWorkspaceStateRow | undefined;
+  archived: string[];
+  pinned: Array<{ id: string; seq: number }>;
+  tasks: LegacyScheduleRow[];
+  globals: LegacyGlobalRow[];
+}
+
+export const LEGACY_STORAGE_MIGRATION_KEY = "legacy_domain_storage_migrated";
+
+/**
+ * 把旧语义表的内容写进通用域存储（`workspace` / `schedule` / 上一版 `t_storage_globals` 的域）。
+ * @param rows - 旧表读出来的行。
+ * @param repository - 通用域存储。
+ */
+export async function migrateLegacyDomainStorage(
+  rows: LegacyStorageRows,
+  repository: StorageRepository,
+): Promise<void> {
+  if (rows.workspaces.length > 0 || rows.state !== undefined) {
+    for (const row of rows.workspaces) {
+      const sessionIds = rows.links
+        .filter((link) => link.workspaceId === row.id)
+        .sort((left, right) => left.position - right.position)
+        .map((link) => link.sessionId as SessionId);
+      await repository.putDomainRecord("workspace", "workspaces", row.id, {
+        path: row.path,
+        title: row.title,
+        sessionIds,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+      });
+    }
+    const pending = rows.state?.pendingOperation;
+    const pendingMutation =
+      pending === "create" || pending === "delete"
+        ? {
+            operation: pending,
+            workspaceId: (rows.state?.pendingWorkspaceId ?? "") as WorkspaceId,
+          }
+        : undefined;
+    await repository.writeDomainGlobal("workspace", {
+      initialized: rows.state === undefined ? true : Boolean(rows.state.initialized),
+      workspaceIds: rows.workspaces
+        .filter((row) => row.position >= 0)
+        .sort((left, right) => left.position - right.position)
+        .map((row) => row.id as WorkspaceId),
+      archivedSessionIds: rows.archived.map((id) => id as SessionId),
+      pinnedSessionIds: rows.pinned
+        .sort((left, right) => left.seq - right.seq)
+        .map((row) => row.id as SessionId),
+      ...(pendingMutation === undefined ? {} : { pendingMutation }),
+    });
+    await repository.insertUnitVersion("workspace", 2);
+  }
+
+  for (const row of rows.tasks) {
+    await repository.putDomainRecord("schedule", "tasks", row.id, {
+      sessionId: row.sessionId as SessionId,
+      record: JSON.parse(row.record),
+      status: row.status === "inactive" ? "inactive" : "active",
+      ...(row.lastDelivery === null ? {} : { lastDelivery: JSON.parse(row.lastDelivery) }),
+      ...(row.deliveryHistory === null ? {} : { deliveryHistory: JSON.parse(row.deliveryHistory) }),
+    });
+  }
+  if (rows.tasks.length > 0) await repository.insertUnitVersion("schedule", 1);
+
+  // 上一版只有一个域一张的 `t_storage_globals`（cua 授权域），搬进同一张通用表。
+  for (const row of rows.globals) {
+    await repository.writeDomainGlobal(row.domain, row.value);
+    await repository.insertUnitVersion(row.domain, 1);
+  }
+}

package/src/storage-takeover/projection-cache.ts

@@ -46,46 +46,37 @@ type LifecycleIdentity = CheckpointIdentity & {
   isSeeded: boolean;
 };
 
-export interface ProjectionCacheConfig {
-  writeEveryEvents: number;
+// 没有攒批参数：投影检查点按「与已落库那行相比是否有变化」决定写不写，与事件条数 / 时间无关。
 
-  writeIntervalMs: number;
-}
-
-export interface SessionProjectionCacheRdbOptions extends ProjectionCacheConfig {
-  repository: StorageRepository;
+export interface SessionProjectionCacheRdbOptions {
+  /** backend 打开后才有值（构造期装配、打开后读写）。 */
+  repository: () => Promise<StorageRepository>;
   ready: Promise<unknown>;
 }
 
-interface DirtyState {
-  pending: number;
-  timer: ReturnType<typeof setTimeout> | undefined;
-}
-
 const PREDECESSOR_TITLE_KEY = "title" as Extract<keyof SessionProjectionMap, string>;
 
 export class SessionProjectionCacheRdb extends Service {
   static inject = ["sessionProjections", "sessions"];
 
   private readonly records = new Map<SessionId, StoredProjcacheEntry>();
-  private readonly dirty = new Map<Session, DirtyState>();
+  // 同一 tick 内的事件合并成一次「落库 + 检查点比对」，这不是攒批：flush 之后事件已经在库里。
+  private readonly queued = new Set<SessionId>();
 
-  private readonly directReads: boolean;
-  private readonly config: ProjectionCacheConfig;
-  private readonly repository: StorageRepository;
+  private repository!: StorageRepository;
   private readonly ready: Promise<unknown>;
+  private readonly openRepository: () => Promise<StorageRepository>;
 
   constructor(ctx: Context, options: SessionProjectionCacheRdbOptions) {
     super(ctx, SESSION_PROJECTION_CACHE_SERVICE);
-    this.config = options;
-    this.repository = options.repository;
+    this.openRepository = options.repository;
     this.ready = options.ready;
-    this.directReads = options.repository.readProjcacheDirect !== undefined;
   }
 
   protected async [Service.init](): Promise<void> {
     this.installWritePath();
     await this.ready;
+    this.repository = await this.openRepository();
 
     const pruned = await this.repository.pruneStaleProjcache();
     if (pruned > 0) {
@@ -93,15 +84,12 @@ export class SessionProjectionCacheRdb extends Service {
         `session projection cache: pruned stale snapshot(s) for ${String(pruned)} session(s)`,
       );
     }
-    if (!this.directReads) {
-      for (const entry of await this.repository.loadProjcache()) {
-        this.records.set(entry.sessionId as SessionId, entry);
-      }
+    for (const entry of await this.repository.loadProjcache()) {
+      this.records.set(entry.sessionId as SessionId, entry);
     }
   }
 
   private lookup(id: SessionId): StoredProjcacheEntry | undefined {
-    if (this.directReads) return this.repository.readProjcacheDirect?.(id);
     return this.records.get(id);
   }
 
@@ -139,12 +127,11 @@ export class SessionProjectionCacheRdb extends Service {
   ): ProjectionSnapshot | undefined {
     if (!selects(keys, PREDECESSOR_TITLE_KEY)) return snapshot;
     if (snapshot?.values[PREDECESSOR_TITLE_KEY] !== undefined) return snapshot;
-    const direct = this.repository.readSessionTitleDirect?.(id);
-    if (direct === undefined) return snapshot;
-    const values = { ...snapshot?.values, [PREDECESSOR_TITLE_KEY]: direct.title };
-
+    const title = this.records.get(id)?.title;
+    if (title === undefined) return snapshot;
+    const values = { ...snapshot?.values, [PREDECESSOR_TITLE_KEY]: title.title };
     const asOfSeq =
-      snapshot === undefined ? direct.seq : Math.min(snapshot.asOfSeq as number, direct.seq);
+      snapshot === undefined ? title.seq : Math.min(snapshot.asOfSeq as number, title.seq);
     return { asOfSeq: asOfSeq as SessionSeqCursor, values };
   }
 
@@ -200,17 +187,63 @@ export class SessionProjectionCacheRdb extends Service {
   }
 
   async write(session: Session): Promise<void> {
-    const rows = this.ctx.sessionProjections.checkpoint(session);
-    this.markClean(session);
+    // 先比差异，**有变化才碰 SQLite**：没变化直接返回，既不写检查点、也不推上游 flush
+    //（事件落库的主节奏是上游 handle 的批量窗口，逐条 flush 会把写放大到每秒数十次——
+    // 见 [设计 写路径](../designs/20260917-写路径.md)「否掉的选项」）。
+    const rows = this.ctx.sessionProjections.checkpoint(session) as unknown as Record<
+      string,
+      ProjectionCheckpointRow
+    >;
+    const previous = this.lookup(session.id)?.rows;
+    if (previous !== undefined && sameCheckpoint(previous, rows)) return;
+
+    if (this.ctx.sessions.get(session.id) === session) {
+      // 检查点是内存 log 的快照：先把 live 事件落库再写检查点，但 **flush 失败不该阻断检查点**——
+      // 否则撤回后缓存会停在旧水位，读路径一直显示撤回前的数据（要重启实例才从库里重新加载）。
+      // flush 失败本身由上游记账，这里只补一条 warn。
+      try {
+        await this.ctx.sessions.flush(session);
+      } catch (error: unknown) {
+        this.ctx.logger.warn(
+          `session projection cache: flush before checkpoint for "${session.id}" failed (checkpoint still written from the in-memory log): ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
 
-    if (this.ctx.sessions.get(session.id) === session) await this.ctx.sessions.flush(session);
-    await this.put(
+    const changed = changedRows(previous, rows);
+    const removedKeys = Object.keys(previous ?? {}).filter((key) => rows[key] === undefined);
+    await this.patch(
       session.id,
       identityOf(session.header, session.inheritedEventCount),
-      rows as unknown as Record<string, ProjectionCheckpointRow>,
+      changed,
+      removedKeys,
     );
   }
 
+  // 增量写回：只 upsert 变化的行、删掉消失的 key，其余行不碰（整份删重插是纯写放大）。
+  private async patch(
+    id: SessionId,
+    identity: CheckpointIdentity,
+    changed: Record<string, ProjectionCheckpointRow>,
+    removedKeys: readonly string[],
+  ): Promise<void> {
+    const detachedChanged = detachJson(changed);
+    await this.repository.patchProjcache(id, detachedChanged, removedKeys);
+
+    const merged: Record<string, ProjectionCheckpointRow> = {};
+    const previous = this.records.get(id)?.rows;
+    if (previous !== undefined) Object.assign(merged, previous);
+    Object.assign(merged, detachedChanged);
+    for (const key of removedKeys) delete merged[key];
+    const title = await this.repository.readSessionTitle(id);
+    this.records.set(id, {
+      sessionId: id,
+      identity,
+      rows: merged,
+      ...(title === undefined ? {} : { title }),
+    });
+  }
+
   // rewind 后 head 回退：把水位超出新 head 的投影单元丢弃，保留仍在截断前缀内的行。
   // 这是零 I/O 读的更新（不 fold 日志）：下次零 I/O 读拿到的是截断后的水位，而不是旧值。
   async truncateTo(
@@ -256,21 +289,8 @@ export class SessionProjectionCacheRdb extends Service {
   }
 
   private installWritePath(): void {
-    this.ctx.on("session/event", (session: Session, event: SessionEvent) => {
-      if (event.type === "turn/end") {
-        void this.flushSoft(session, "turn/end");
-        return;
-      }
-      const state = this.dirty.get(session) ?? { pending: 0, timer: undefined };
-      this.dirty.set(session, state);
-      state.pending += 1;
-      if (state.pending >= this.config.writeEveryEvents) {
-        void this.flushSoft(session, "count threshold");
-        return;
-      }
-      state.timer ??= setTimeout(() => {
-        void this.flushSoft(session, "interval");
-      }, this.config.writeIntervalMs);
+    this.ctx.on("session/event", (session: Session) => {
+      this.scheduleWrite(session, "event");
     });
 
     this.ctx.on("session/created", (session: Session) => {
@@ -279,19 +299,19 @@ export class SessionProjectionCacheRdb extends Service {
 
     this.ctx.on("session/disposed", (session: Session) => {
       void this.flushSoft(session, "detach");
-      this.markClean(session);
-      this.dirty.delete(session);
+      this.queued.delete(session.id);
     });
+  }
 
-    this.ctx.effect(
-      () => () => {
-        for (const state of this.dirty.values()) {
-          if (state.timer !== undefined) clearTimeout(state.timer);
-        }
-        this.dirty.clear();
-      },
-      "sessionProjectionCacheRdb.timers",
-    );
+  // 同一 tick 的多条事件合成一次：flush 一次、checkpoint 取一次、diff 一次。
+  // 落库时机不再取决于事件条数或定时器——事件一到就写库，检查点则只在真的变了才写。
+  private scheduleWrite(session: Session, trigger: string): void {
+    if (this.queued.has(session.id)) return;
+    this.queued.add(session.id);
+    queueMicrotask(() => {
+      this.queued.delete(session.id);
+      void this.flushSoft(session, trigger);
+    });
   }
 
   private async flushSoft(session: Session, trigger: string): Promise<void> {
@@ -304,16 +324,6 @@ export class SessionProjectionCacheRdb extends Service {
     }
   }
 
-  private markClean(session: Session): void {
-    const state = this.dirty.get(session);
-    if (state === undefined) return;
-    state.pending = 0;
-    if (state.timer !== undefined) {
-      clearTimeout(state.timer);
-      state.timer = undefined;
-    }
-  }
-
   private async put(
     id: SessionId,
     identity: CheckpointIdentity,
@@ -322,9 +332,50 @@ export class SessionProjectionCacheRdb extends Service {
     const detached = detachJson(rows);
 
     await this.repository.putProjcache(id, detached);
+    const title = await this.repository.readSessionTitle(id);
+    this.records.set(id, {
+      sessionId: id,
+      identity,
+      rows: detached,
+      ...(title === undefined ? {} : { title }),
+    });
+  }
+}
+
+// 「有没有变化」的判据：逐行比 `ver` 与 `val`，**不比 `seq`**。`seq` 是「最后折入的事件」水位，
+// 上游投影对每个事件都会推进它（哪怕 apply 返回同一份 state），拿它当判据等于每个事件都写一次。
+// 值没变就跳过写回：读侧仍会从旧水位重放那几条事件，得到同样的值——缓存要的是「值对不对」，
+// 不是「水位最新」。`val` 是纯 JSON（写入前已 detach），逐键序列化比较即可。
+function sameRow(before: ProjectionCheckpointRow, after: ProjectionCheckpointRow): boolean {
+  return before.ver === after.ver && JSON.stringify(before.val) === JSON.stringify(after.val);
+}
+
+// 只挑出真的变了的行：写库只碰这些行，其余行原样留在库里（不删不重插）。
+function changedRows(
+  previous: Record<string, ProjectionCheckpointRow> | undefined,
+  next: Record<string, ProjectionCheckpointRow>,
+): Record<string, ProjectionCheckpointRow> {
+  const changed: Record<string, ProjectionCheckpointRow> = {};
+  for (const [key, row] of Object.entries(next)) {
+    const before = previous?.[key];
+    if (before === undefined || !sameRow(before, row)) changed[key] = row;
+  }
+  return changed;
+}
 
-    if (!this.directReads) this.records.set(id, { sessionId: id, identity, rows: detached });
+function sameCheckpoint(
+  previous: Record<string, ProjectionCheckpointRow>,
+  next: Record<string, ProjectionCheckpointRow>,
+): boolean {
+  const keys = Object.keys(next);
+  if (keys.length !== Object.keys(previous).length) return false;
+  for (const key of keys) {
+    const before = previous[key];
+    const after = next[key];
+    if (before === undefined || after === undefined) return false;
+    if (!sameRow(before, after)) return false;
   }
+  return true;
 }
 
 function detachJson(

package/src/storage-takeover/read-model.ts

@@ -0,0 +1,189 @@
+import type { Database } from "@morlay/rdbkit";
+import {
+  and,
+  E,
+  eq,
+  gte,
+  isNull,
+  lt,
+  notInSubquery,
+  or,
+  type Condition,
+  type ExprOperand,
+} from "@morlay/rdbkit";
+import type { EventRow, ReadModel, SessionRow } from "../backend.ts";
+import { events, sessionEvents, sessions } from "../entities/index.ts";
+
+export type { ReadModel };
+
+export function createReadModel(database: Database): ReadModel {
+  const sessionsTable = sessions.table(database);
+  const eventsTable = events.table(database);
+  const links = sessionEvents.table(database);
+
+  return {
+    async getSession(id) {
+      for await (const row of sessionsTable.select().where(eq(sessionsTable.f_session_id, id))) {
+        return sessionRowOf(row);
+      }
+      return undefined;
+    },
+
+    async getEventRows(id, fromSequence) {
+      const rows: EventRow[] = [];
+      const condition =
+        fromSequence === undefined
+          ? eq(links.f_session_id, id)
+          : and(eq(links.f_session_id, id), gte(links.f_sequence, fromSequence));
+      for await (const row of links
+        .select({
+          fEventId: links.f_event_id,
+          fSequence: links.f_sequence,
+          fType: eventsTable.f_type,
+          fKind: eventsTable.f_kind,
+          fRole: eventsTable.f_role,
+          fName: eventsTable.f_name,
+          fActionId: eventsTable.f_action_id,
+          fCreatedAt: eventsTable.f_created_at,
+          fData: eventsTable.f_data,
+          fSurfaceOp: links.f_surface_op,
+        })
+        .join(events, eq(eventsTable.f_event_id, links.f_event_id))
+        .where(condition)
+        .orderBy("f_sequence")) {
+        rows.push(eventRowOf(row));
+      }
+      return rows;
+    },
+
+    async getEventTypeAt(id, sequence) {
+      for await (const row of links
+        .select({ fType: eventsTable.f_type })
+        .join(events, eq(eventsTable.f_event_id, links.f_event_id))
+        .where(and(eq(links.f_session_id, id), eq(links.f_sequence, sequence)))
+        .limit(1)) {
+        return row.fType;
+      }
+      return undefined;
+    },
+
+    async getEventTypesBefore(id, beforeSequence, limit) {
+      const rows: Array<Pick<EventRow, "fSequence" | "fType">> = [];
+      for await (const row of links
+        .select({ fSequence: links.f_sequence, fType: eventsTable.f_type })
+        .join(events, eq(eventsTable.f_event_id, links.f_event_id))
+        .where(and(eq(links.f_session_id, id), lt(links.f_sequence, beforeSequence)))
+        .orderBy("f_sequence", "desc")
+        .limit(limit)) {
+        rows.push({ fSequence: Number(row.fSequence), fType: row.fType });
+      }
+      return rows;
+    },
+
+    async listSessions() {
+      const rows: SessionRow[] = [];
+      for await (const row of sessionsTable.select()) rows.push(sessionRowOf(row));
+      return rows;
+    },
+
+    async latestTitleEvent(id) {
+      for await (const row of links
+        .select({ fSequence: links.f_sequence, fData: eventsTable.f_data })
+        .join(events, eq(eventsTable.f_event_id, links.f_event_id))
+        .where(and(eq(links.f_session_id, id), eq(eventsTable.f_type, "session/title")))
+        .orderBy("f_sequence", "desc")
+        .limit(1)) {
+        return { fSequence: Number(row.fSequence), fData: row.fData };
+      }
+      return undefined;
+    },
+
+    async listOrphanSubagentSessions() {
+      const ids: string[] = [];
+      for await (const row of sessionsTable
+        .select({ id: sessionsTable.f_session_id })
+        .where(
+          and(
+            eq(sessionsTable.f_origin, "subagent"),
+            or(
+              isNull(sessionsTable.f_parent_session),
+              notInSubquery(
+                sessionsTable.f_parent_session,
+                sessionsTable.select({ id: sessionsTable.f_session_id }).toFragment(),
+              ),
+            ),
+          ),
+        )) {
+        ids.push(row.id);
+      }
+      return ids;
+    },
+  };
+}
+
+/** `f_last_event_at` 的「只增不减」（两方言同一份表达式，值走绑定）。 */
+export function lastEventAtExpr(value: number): ExprOperand<number> {
+  return E.maxOf(E.column("f_last_event_at"), value);
+}
+
+/** header 的「变了才写」条件：逐列 `IS DISTINCT FROM` 的 OR（值全部走绑定参数）。 */
+export function headerChangedCondition(
+  header: Readonly<Record<string, string | number | null>>,
+): Condition {
+  return E.or(
+    ...Object.entries(header).map(([name, value]) =>
+      E.isDistinctFrom(E.column(name, "t_sessions"), value),
+    ),
+  );
+}
+
+/**
+ * 事件行的数值列统一收回 number：`f_created_at` 在表定义里是 `bigint`（rdbkit 读回 BigInt），
+ * 事件坐标与毫秒时间都在安全整数范围内。
+ */
+function eventRowOf(row: {
+  fEventId: string;
+  fSequence: number | bigint;
+  fType: string;
+  fKind: string;
+  fRole: string;
+  fName: string;
+  fActionId: string;
+  fCreatedAt: number | bigint;
+  fData: string;
+  fSurfaceOp: string | null;
+}): EventRow {
+  return {
+    fEventId: row.fEventId,
+    fSequence: Number(row.fSequence),
+    fType: row.fType,
+    fKind: row.fKind,
+    fRole: row.fRole,
+    fName: row.fName,
+    fActionId: row.fActionId,
+    fCreatedAt: Number(row.fCreatedAt),
+    fData: row.fData,
+    fSurfaceOp: row.fSurfaceOp,
+  };
+}
+
+/** 列名原样 → 会话行的 camelCase（列名由表定义固定，这里是唯一一处映射）。 */
+export function sessionRowOf(row: Record<string, unknown>): SessionRow {  return {
+    fSessionId: String(row["f_session_id"]),
+    fHeadEventId: String(row["f_head_event_id"]),
+    fHeadSequence: Number(row["f_head_sequence"]),
+    fVersion: Number(row["f_version"]),
+    fCreatedAt: Number(row["f_created_at"]),
+    fCwd: (row["f_cwd"] as string | null) ?? null,
+    fParentSession: (row["f_parent_session"] as string | null) ?? null,
+    fSeedLength: row["f_seed_length"] === null ? null : Number(row["f_seed_length"]),
+    fOrigin: (row["f_origin"] as string | null) ?? null,
+    fDelegationDepth: row["f_delegation_depth"] === null ? null : Number(row["f_delegation_depth"]),
+    fAgentPreset: (row["f_agent_preset"] as string | null) ?? null,
+    fIncarnation: String(row["f_incarnation"]),
+    fRevision: Number(row["f_revision"]),
+    fArchivedAt: row["f_archived_at"] === null ? null : Number(row["f_archived_at"]),
+    fPinnedSeq: row["f_pinned_seq"] === null ? null : Number(row["f_pinned_seq"]),
+    fLastEventAt: row["f_last_event_at"] === null ? null : Number(row["f_last_event_at"]),
+  };
+}